See also:
T393251: Support WebAuthn second factor login on Wikimedia Android app
T393250: Support WebAuthn second factor login on Wikimedia iOS app
T393329: Support WebAuthn second factor login on Wikimedia Commons app
T395459: Use OAuth rather than password-based login for Wikimedia mobile apps

Current 2FA logic in clients: Android app, iOS app, Commons app, CommonsFinder.

The way the 2FA integration in AuthManager works in a nutshell is that the OATHAuth extension registers a secondary authentication provider and implements the beginAuthentication() and continueAuthentication() methods. beginAuthentication() will be called once the primary authentication provider established the user's identity (ie. the user has submitted the username + password form), and will return one or more AuthenticationRequest objects (wrapped inside an AuthenticationResponse) that describe the next login form. Then when the user submits that form, continueAuthentication() is called, and can either do the same, or signal success (allow the login flow to proceed).

The mobile apps (along some other apps) use the action=clientlogin API. The API just does a very straightforward mapping of the returned AuthenticationRequest objects to JSON objects.

Currently OATHAuth will either return a single TOTPAuthenticationRequest or a WebAuthnAuthenticationRequest (and then keep returning it until the user successfully answers the challenge). Android and iOS both look at the API response, iterate through the AuthenticationRequest objects, and if the find a TOTPAuthenticationRequest, show the appropriate login widget to the user and know how to submit the next login step.

This will keep working as long as we can ensure a TOTPAuthenticationRequest is present in the initial response. So I think no changes will be needed on the app side at least until we do T232336: Separate recovery codes into a separate 2FA module.

On our side, we'll probably end up with some logic which looks at what 2FA methods the user has set up, select the best candidate for the initial UI, send the AuthenticationRequest for that, and send another AuthenticationRequest that can be used for switching to a different method. So we only need to follow two simple rules:

• If the user is logging in via the API, and TOTP is one of their supported 2FA methods, always offer that first.
• If the user only has one 2FA method set up, then don't send whatever AuthenticationRequest we'll be using for method switching (it wouldn't really make sense to do so anyway). I think this is not strictly necessary (the apps would not break if they receive multiple request objects, one of which is a TOTPAuthenticationRequest) but it minimizes the change to the API.

Currently you can use the TOTPAuthenticationRequest to submit either a real TOTP code or a backup code. Once we do separate backup codes from TOTP, the latter might stop working (unless we add some kind of B/C code). So we should clarify the expectations around that.

Change #1183203 had a related patch set uploaded (by Catrope; author: Catrope):

[mediawiki/extensions/OATHAuth@master] Provide backward compatibilty for the mobile apps' login flow

https://gerrit.wikimedia.org/r/1183203

The attached patch implements what @Tgr suggested above. To clarify what this means for the mobile apps:

• For users who have only TOTP enabled, nothing will change. The action=clientlogin API will continue to return a requests array with only one request, which is a TOTPAuthenticationRequest. The apps already handle this correctly.
• For users who have only WebAuthn enabled, nothing will change. The API will return one request, which is a WebAuthnAuthenticationRequest. The apps can't handle this currently, but that's already the case. (Users who have 2FA set up with only a security key or passkey can't log in through the apps.)
• For users who have both TOTP and WebAuthn enabled:
  • In the short term, with my hacky solution, the requests array will contain two requests, a TOTPAuthenticationRequest and a TwoFactorModuleSelectAuthenticationRequest. The current code in the iOS and Android apps should handle this correctly, because both apps look through the list of requests for a TOTPAuthenticationRequest and act on that one. So this is backwards compatible.
  • In the medium term, we would like to remove the hack, which would cause the API to return a WebAuthnAuthenticationRequest and a TwoFactorModuleSelectAuthenticationRequest. First, the apps would need to be updated to handle this scenario correctly. They would need to send a response with newModule set to totp(*), and then they would receive a new set of requests that includes a TOTPAuthenticationRequest. Once the updated apps are released, we would then remove the hack.

(*) If totp appears in the metadata.allowedModules field. That's currently always the case, but might change in the future; we'll keep you posted.

Change #1183203 merged by jenkins-bot:

[mediawiki/extensions/OATHAuth@master] Provide backward compatibilty for the mobile apps' login flow

https://gerrit.wikimedia.org/r/1183203

Hi there, I am the developer of CommonsFinder. Sorry to re-open this issue, but I just noticed the second point in the ticket description:

2. not have to worry about them in favor of the mobile apps migrating to another auth approach (such as OAuth)."

…and was intrigued!

I did initially want to do OAuth for CommonsFinder, but was discouraged after reading this in the mediawiki wiki

The application secret must be kept secret. Submitting it to source control or putting it into user-accessible code (such as mobile app or desktop application; even if it is obfuscated)

and the other wikimedia API

The OAuth 2.0 client credentials flow is not supported for client-side or installed apps (mobile, desktop, and single-page apps). Instead, use the user authentication flow. Read security best practices to learn more.

...which links to the Security best practices, which contradicts the statement and not mentioning that OAuth 2 should not be used for mobile apps and not mentioning any specific details that would prevent the mobile app usage.
But it also says, the page is under construction.

When I read both bits of information a few months back, I was sceptical how valid that statements still are, considering OAuth is used for other mobile apps out there and best practice regarding OAuth security in mobile apps exists, eg. using PKCE (eg. https://oauth.net/2/native-apps).

It would be great to get some clarification on that topic.
If indeed OAuth is the preferred authentication method even for mobile apps and sanctioned by WMF for public use, I'd be happy to look into implementing it in CommonsFinder. :)

cheers and best regards,
nylki