Versions Compared

Old Version 7

changes.mady.by.user Marco Marasca

Saved on

compared with

New Version 8

changes.mady.by.user Marco Marasca

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

API

Request

Response

Description

POST /2fa/enroll

Code Block
{
"type": "totp"
}
Code Block
{
"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
}

Initiate the enrollment for the user to 2FA.

The server generates a shared secret to use with an OTP application that is sent back to the user.

The client can generate a QR code for convenience so that the user can scan the secret when adding it to the OTP application (e.g. google authenticator). The URL to embed in the QR code can follow this format: https://github.com/google/google-authenticator/wiki/Key-Uri-Format#issuer .

For example: otpauth://totp/Synapse:alice@google.com?secret=<secretBase32>&issuer=Synapse%20Prod&algorithm=SHA1&digits=6&period=30.

Note that the endpoint can be invoked even if the user has 2FA already enabled.

The server will re-generate a secret that is not used until it is enabled, this allows the user to reset the 2FA without affecting existing 2FA.

POST /2fa

Code Block
{
"secretId": <id from enroll API>,
"totp": <totp from app>
}
Code Block
{
  "status": "enabled"
}

Enable 2FA for the user, uses the secret that was generated from the enroll API.

Note that the server will use only one secret to verify TOTPs.

This backend will replace other 2FA secrets already enabled if the request is successful.

POST /2fa/recovery_codes

Code Block
languagejson
{
  "codes": ["abc", "efg"]
}

Re-generates a set of recovery codes (we can provide at least 10 codes).

The codes are a one-time use code that the user can use to recover access to their account.

This endpoint will re-generate the codes on each call and associate them with the currently enabled 2FA.

The generated codes are hashed and never retrieved again.

Note that the user can end up using all of the recovery codes, in this case we should warn the user (maybe an email, or a notification in the browser?) that new codes should be re-generated.

If 2FA is not enabled the API will return a 403 with the error code 2fa_enrollement_required400.

DELETE /2fa

Disable 2FA for the user.

If 2FA is not enabled the API will return a 403 with the error code 2fa_enrollement_required400.

Proposed 2FA auth API Design

...