Feature/totp 2fa handler

[jcoffi]

Add TOTP Two-Factor Authentication Handler

Overview

This PR adds a new built-in Two-Factor Authentication handler that automatically generates Time-based One-Time Password (TOTP) codes for authentication with Interactive Brokers. This eliminates the need for manual input during the 2FA process and enables fully automated authentication workflows.

Features

• Fully automated TOTP code generation: No manual user input required
• Compatible with standard TOTP implementations: Works with Google Authenticator, Authy, and other TOTP apps
• Simple configuration: Only requires setting two environment variables
• Secure logging: Only logs the last two digits of generated codes for security
• Comprehensive error handling: Clear error messages for common issues
• Standalone test mode: Easy verification of handler functionality

Implementation Details

• Added TotpTwoFaHandler class that inherits from TwoFaHandler
• Integrated with IBeam's existing 2FA handler selection mechanism
• Uses the pyotp library for standards-compliant TOTP code generation
• Follows Google Python Style Guide for code quality and consistency
• Includes comprehensive unit tests with 100% code coverage

Configuration

Users can enable the TOTP handler by setting:

export IBEAM_TWO_FA_HANDLER=TOTP
export IBEAM_TOTP_SECRET=YOUR_TOTP_SECRET

Documentation

• Added detailed documentation in docs/two_factor_authentication.md
• Updated main README.md to highlight 2FA support
• Created standalone documentation in docs/totp_handler.md
• Added inline code documentation following Google Python Style Guide

Security Considerations

• The handler reads secrets securely from environment variables
• No hardcoded secrets in the codebase
• Logs only the last two digits of generated codes to prevent exposure
• Raises clear exceptions if secrets are missing or invalid

Testing

• Added comprehensive unit tests in tests/test_totp_handler.py
• Tests cover initialization, code generation, error handling, and logging
• Added standalone test mode for easy verification

Dependencies

• Added pyotp dependency to requirements.txt

This PR addresses the need for fully automated authentication when 2FA is enabled on IBKR accounts, making IBeam more versatile.

[Voyz]

hey @jcoffi thanks for the contribution. I assume that the code in this PR is at least partially written by AI, in this case the OpenHands it seems. While it's great to see AI being able to write such quality code, I'm want to ask a few things first:

1. Have you read the code?
2. Have you run manual tests to confirm that the implementation works? Can you successfully automate 2FA with this code?
3. IBKR website sometimes displays a 'Failed' error when inputting 2FA code from Google Authenticator despite typing it in correctly, do you experience it here?
4. Could you please redact the documentation as it seems to be repeating itself in various files
5. While the documentation gives a good overview, it lacks an actual guide for how to use this method. Could you provide a step-by-step description on how to use this. Where would the user get the secret, where to put it, how to enable, etc.

Additionally, based on my conversations with IBKR support, I think that TOTP is not available to all IBKR users. Not sure what the criteria is, but I'd be careful with claiming that it completely solves it - we may want to rephrase the docs regarding this.

Appreciate your initiative here 🙌

[jcoffi]

The documentation doesn't mention TOTP being limited access. https://www.ibkrguides.com/securelogin/sls/twofactorauth.htm

I'll come back to this. Just very busy for the next few days.

[amaeckelberghe]

Thanks for this PR. Any updates on its status? I'm quite interested given that for iOS users the Google Messages 2FA is not available from what I understand so it would be useful to have another alternative off-the-shelve.

[jcoffi]

If you want to test it, pull the PR and try it. But eventually, it appears they are going to force everyone to use the IBKR app to MFA as the only option. They are doing it by geographic region. But if you're in with the old MFA, you can keep using it.

[Voyz]

@jcoffi I saw you made a few commits, but I'm not sure if you've addressed all the points I brought up in the past PR review? Is it ready for another review?

@amaeckelberghe have a look at IBind and OAuth authentication for an alternative: https://github.com/Voyz/ibind/wiki/Authentication

[jcoffi]

It's not ready yet. It will either be ready in the next few days or I'll probably close it.

…

On Fri, Jun 13, 2025 at 9:35 AM voyz ***@***.***> wrote: *Voyz* left a comment (Voyz/ibeam#250) <#250 (comment)> @jcoffi <https://github.com/jcoffi> I saw you made a few commits, but I'm not sure if you've addressed all the points I brought up in the past PR review? Is it ready for another review? @amaeckelberghe <https://github.com/amaeckelberghe> have a look at IBind and OAuth authentication for an alternative: https://github.com/Voyz/ibind/wiki/Authentication — Reply to this email directly, view it on GitHub <#250 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFBU5KC7BGT3TAR47TQ5FMD3DL4WXAVCNFSM6AAAAAB3XOJMJ2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZQHEYTKNRUG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[amaeckelberghe]

@jcoffi I saw you made a few commits, but I'm not sure if you've addressed all the points I brought up in the past PR review? Is it ready for another review?

@amaeckelberghe have a look at IBind and OAuth authentication for an alternative: https://github.com/Voyz/ibind/wiki/Authentication

Thanks both.

@Voyz : IBind with OAuth looks to be exactly what I need, thanks for the reference (and the effort on these libraries)!

@jcoffi : I had pulled your docker image and ran it. The code seems to work fuctionally on my end, however the login itself failed when I tried it (Timeout reached when waiting for authentication. The website seems to not be loaded correctly. Consider increasing IBEAM_PAGE_LOAD_TIMEOUT.). I have increased IBEAM_PAGE_LOAD_TIMEOUT but I'm assuming there's something else that still went wrong on my side. Just wanted to share it in case of relevance for you. I'm switching to IBind with OAuth but nonetheless thanks a lot for your work on this. Much appreciated.

[jcoffi]

Your account has to be setup for TOTP at IBKR for this to work. I may come back to this eventually. But for now, I'll close it. I just don't have time right now.

[Voyz]

@jcoffi No problem, thanks for the initiative nevertheless 🙌