Page Comparison

...

Note that it is important to give the user at least one way to recover access without the OTP application. We can later extend this using for example SMS or Email as a backup to send the user otp codes to regain access. We would also need to setup a way for the user to contact us in case any attempt to regain access is failing so that we can potentially help them regain access (e.g. disable 2FA for them once their identify is verified).

{
"type": "totp"
}

{
"id": <id of the generated secret>,
"type": "totp",
"secret": "<Base64 encoded secret>",
"secretBase32": "<Base32 encoded version of the secret>"
"alg": "SHA1",
"digits": 6,
"period": 30
}

{
"secretId": <id from enroll API>,
"totp": <totp from app>
}

{
  "status": "enabled"
}

{
  "codes": ["abc", "efg"]
}

Proposed 2FA auth API Design

...

The 2fa_token and a totp code can be used to finalize authentication with 2fa:

{
 "2fa_token": <token received in the 401 mfa_required response>,
 "otp_type": "totp",
 "otp_code": <totp from app>
}

{
 "access_token": "<the access token that would be obtain from authentication>"
}

For example, first we send a login request:

...

HTTP/2 200

{"access_token": "c3VwZXIgczNjcjN0IGFjY2VzcyB0b2tlbg=="}

Open Questions

1. Should we implement some sort of step-up authentication? E.g. when the user tries to create a PAT, should we ask for the 2FA code? Or is it enough to validate that the user has 2FA enabled?
   → We decided to avoid adding additional checks, we need to inform the user when PAT are added/removed with an email.

2. The design requires that the 2FA/token takes in input a 2FA_token. This token would help the backend to understand the context (e.g. login, scopes). This is needed because Synapse does not use sessions and we need to support google as a 3rd party. How long should this token be valid? Should it be a one-time use token?
   → The token should only be valid for a brief time, e.g. 5 minutes.

3. I specifically didn’t add any validation for access tokens. This means that even after enrolling in 2FA existing tokens will be valid. Should we instead encode into the access tokens a claim such as “2fa_auth_time” that we can validate (for presence only) when the user has 2FA enabled? This would mean that any token after 2FA is enabled will be invalidated and the user needs to login again (potentially having to input the 2FA code twice).
   → This is still open for discussion: on one hand invalidating previous issued tokens is more secure, on the other hand it has the potential to break existing workflows and script and reducing usability →

   Jira Legacy
   server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key PLFM-7637

4. Relevant to the previous point: using the refresh token grant we can technically keep refreshing tokens without user interaction (at least through an oauth client), should we limit the amount of time before the user needs to re-authenticate? E.g. Using the previous 2fa_auth_time we could check if 2fa is enabled and if it was performed in the last 30 days.
   → We decided that client token issued through client credentials are secure enough and there is no need for additional 2FA checking

5. Should we send an email when we enable/disable 2FA with a link to the documentation?
   → Open JIRA(s) related to this.

6. Should we implement the standard to support for the acr_values in the /oauth2/token endpoint to allow oauth clients to enforce the use of 2FA? (See https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest ) →

   Jira Legacy
   server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key PLFM-7629

7. What other ways should we support as a backup to regain access to the account (aside from recovery codes)? Email, sms, security keys? →

   Jira Legacy
   server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key PLFM-7633