mirror of
https://github.com/superseriousbusiness/gotosocial
synced 2025-06-05 21:59:39 +02:00
[feature] add TOTP two-factor authentication (2FA) (#3960)
* [feature] add TOTP two-factor authentication (2FA) * use byteutil.S2B to avoid allocations when comparing + generating password hashes * don't bother with string conversion for consts * use io.ReadFull * use MustGenerateSecret for backup codes * rename util functions
This commit is contained in:
tobi
GitHub
@ -3510,6 +3510,11 @@ definitions:
|
||||
example: "2021-07-30T09:20:25+00:00"
|
||||
type: string
|
||||
x-go-name: ResetPasswordSentAt
|
||||
two_factor_enabled_at:
|
||||
description: Time at which 2fa was enabled for this user. (ISO 8601 Datetime)
|
||||
example: "2021-07-30T09:20:25+00:00"
|
||||
type: string
|
||||
x-go-name: TwoFactorEnabledAt
|
||||
unconfirmed_email:
|
||||
description: Unconfirmed email address of this user, if set.
|
||||
example: someone.else@somewhere.else.example.org
|
||||
@ -12141,6 +12146,146 @@ paths:
|
||||
summary: Get your own user model.
|
||||
tags:
|
||||
- user
|
||||
/api/v1/user/2fa/disable:
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
- application/x-www-form-urlencoded
|
||||
description: |-
|
||||
If 2fa is already disabled for this user, code 409 Conflict will be returned.
|
||||
|
||||
If the instance is running with OIDC enabled, two factor authentication cannot be turned on or off in GtS, it must be enabled or disabled using the OIDC provider. All calls to 2fa api endpoints will return 422 Unprocessable Entity while OIDC is enabled.
|
||||
operationId: TwoFactorDisablePost
|
||||
parameters:
|
||||
- description: User's current password, for verification.
|
||||
in: formData
|
||||
name: password
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: QR code
|
||||
"401":
|
||||
description: unauthorized
|
||||
"403":
|
||||
description: forbidden
|
||||
"406":
|
||||
description: not acceptable
|
||||
"409":
|
||||
description: conflict
|
||||
"422":
|
||||
description: unprocessable entity
|
||||
"500":
|
||||
description: internal error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- write:accounts
|
||||
summary: Disable 2fa for the authorized user. User's current password must be provided for verification purposes.
|
||||
tags:
|
||||
- user
|
||||
/api/v1/user/2fa/enable:
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
- application/x-www-form-urlencoded
|
||||
description: |-
|
||||
If 2fa is already enabled for this user, code 409 Conflict will be returned.
|
||||
|
||||
If the instance is running with OIDC enabled, two factor authentication cannot be turned on or off in GtS, it must be enabled or disabled using the OIDC provider. All calls to 2fa api endpoints will return 422 Unprocessable Entity while OIDC is enabled.
|
||||
operationId: TwoFactorEnablePost
|
||||
parameters:
|
||||
- description: |-
|
||||
2fa code from the user's authenticator app.
|
||||
Sample: 123456
|
||||
in: formData
|
||||
name: code
|
||||
type: string
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: QR code
|
||||
"401":
|
||||
description: unauthorized
|
||||
"403":
|
||||
description: forbidden
|
||||
"406":
|
||||
description: not acceptable
|
||||
"409":
|
||||
description: conflict
|
||||
"422":
|
||||
description: unprocessable entity
|
||||
"500":
|
||||
description: internal error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- write:accounts
|
||||
summary: Enable 2fa for the authorized user, using the provided code from an authenticator app, and return an array of one-time recovery codes to allow bypassing 2fa.
|
||||
tags:
|
||||
- user
|
||||
/api/v1/user/2fa/qr.png:
|
||||
get:
|
||||
description: |-
|
||||
For the plaintext version of the QR code URI, call /api/v1/user/2fa/qruri instead.
|
||||
|
||||
If 2fa is already enabled for this user, the QR code (with its secret) will not be shared again. Instead, code 409 Conflict will be returned. To get a fresh secret, first disable 2fa using POST /api/v1/user/2fa/disable, and then call this endpoint again.
|
||||
|
||||
If the instance is running with OIDC enabled, two factor authentication cannot be turned on or off in GtS, it must be enabled or disabled using the OIDC provider. All calls to 2fa api endpoints will return 422 Unprocessable Entity while OIDC is enabled.
|
||||
operationId: TwoFactorQRCodePngGet
|
||||
produces:
|
||||
- image/png
|
||||
responses:
|
||||
"200":
|
||||
description: QR code png
|
||||
"401":
|
||||
description: unauthorized
|
||||
"403":
|
||||
description: forbidden
|
||||
"406":
|
||||
description: not acceptable
|
||||
"409":
|
||||
description: conflict
|
||||
"422":
|
||||
description: unprocessable entity
|
||||
"500":
|
||||
description: internal error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- read:accounts
|
||||
summary: Return a QR code png to allow the authorized user to enable 2fa for their login.
|
||||
tags:
|
||||
- user
|
||||
/api/v1/user/2fa/qruri:
|
||||
get:
|
||||
description: |-
|
||||
For a png of the QR code, call /api/v1/user/2fa/qr.png instead.
|
||||
|
||||
If 2fa is already enabled for this user, the QR code URI (with its secret) will not be shared again. Instead, code 409 Conflict will be returned. To get a fresh secret, first disable 2fa using POST /api/v1/user/2fa/disable, and then call this endpoint again.
|
||||
|
||||
If the instance is running with OIDC enabled, two factor authentication cannot be turned on or off in GtS, it must be enabled or disabled using the OIDC provider. All calls to 2fa api endpoints will return 422 Unprocessable Entity while OIDC is enabled.
|
||||
operationId: TwoFactorQRCodeURIGet
|
||||
produces:
|
||||
- text/plain
|
||||
responses:
|
||||
"200":
|
||||
description: QR code uri
|
||||
"401":
|
||||
description: unauthorized
|
||||
"403":
|
||||
description: forbidden
|
||||
"406":
|
||||
description: not acceptable
|
||||
"409":
|
||||
description: conflict
|
||||
"422":
|
||||
description: unprocessable entity
|
||||
"500":
|
||||
description: internal error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- read:accounts
|
||||
summary: Return a QR code uri to allow the authorized user to enable 2fa for their login.
|
||||
tags:
|
||||
- user
|
||||
/api/v1/user/email_change:
|
||||
post:
|
||||
consumes:
|
||||
|
||||
@ -225,7 +225,9 @@ If you want to reset all your policies to the initial defaults, you can click on
|
||||
|
||||
As more ActivityPub servers roll out support for interaction policies, this issue will hopefully diminish, but in the meantime GoToSocial can offer only a "best effort" attempt to restrict interactions with your posts according to the policies you have set.
|
||||
|
||||
## Email & Password
|
||||
## Account
|
||||
|
||||
In the "Account" section, you can set your email and password, and set up two-factor authentication for your account.
|
||||
|
||||
### Email Change
|
||||
|
||||
@ -245,6 +247,24 @@ You can use the Password Change section of the panel to set a new password for y
|
||||
|
||||
For more information on the way GoToSocial manages passwords, please see the [Password management document](./password_management.md).
|
||||
|
||||
### Two-Factor Authentication
|
||||
|
||||
You can use this section of the panel to enable two-factor authentication (2FA) for your account.
|
||||
|
||||
With 2FA enabled, you will have to provide a code from your configured authenticator app (Google authenticator, LastPass authenticator, etc) when you want to log in, in addition to your password.
|
||||
|
||||
To enable 2FA, install an authenticator app on your mobile device, and use it to scan the QR code. You can also copy the 2FA secret manually and paste it into your authenticator. Once you've done that, enter a code from your authenticator to verify that the authenticator and the server are synced up correctly.
|
||||
|
||||
On success, you will be shown a list of eight 2FA backup/recovery codes. Save these codes in a safe place (eg., in a password manager). If you lose access to your authenticator app, for example if you lose your device, then you can use one of these codes instead of a 2FA code when logging in. Once you have used a code, you will not be able to use it again. Should you use up all eight recovery codes, you should disable and reenable 2FA to generate new ones.
|
||||
|
||||
To disable two-factor authentication, enter your current password in the form, and click the "Disable 2FA" button.
|
||||
|
||||
!!! tip
|
||||
Two-factor authentication is recommended, as it makes it more difficult for baddies to log in to your account by guessing your password, since they would also need access to your authenticator device. For more information on different types of 2FA, see [A Guide to Common Types of Two-Factor Authentication on the Web](https://www.eff.org/deeplinks/2017/09/guide-common-types-two-factor-authentication-web).
|
||||
|
||||
!!! info
|
||||
If your instance is using OIDC as its authorization/identity provider, you will not be able to enable 2FA in the settings panel, and you should contact your OIDC provider instead.
|
||||
|
||||
## Migration
|
||||
|
||||
In the migration section you can manage settings related to aliasing and/or migrating your account to or from another account.
|
||||
|
||||
Reference in New Issue
Block a user