Single Sign-On (SSO)
Single sign-on is an authentication scheme that allows a user to log in with a single ID to any of several related, yet independent, software systems. (Wikipedia, CC Attribution-ShareAlike)
In other words, you can use an existing account, say your github account, to authenticate to 2FAuth.
SSO is probably overkill for a single user usage but becomes relevant in a multi-user context, especially if your organization already uses OAuth.
For now 2FAuth only supports 2 SSO providers: OpenID and Github
Enable a provider
Create the client
You have to create a client ID on the provider side first. This is required so that your 2FAuth instance is considered legit when requesting an access token to the provider.
Please refer to the vendor's documentation for instructions on how to do this. During the process, when/if asked:
- Choose the Authorization code grant flow
- Choose the Web application flow
- The Authorization callback URL is to build as:
_Your 2FAuth instance url is
_Your provider is Github
Then your callback URL is:
At the end of the process, you should be provided with a Client ID & Secret. Copy them as they are needed to set up the provider on the 2FAuth side.
Usefull resources (for Github)
Set up the provider
Setting up a provider is done by defining its dedicated environment variables on your 2FAuth instance. You can find these vars in the
.env file of 2FAuth.
# OpenID (enabled)
# Following provider is disabled
Uncomment the lines for the providers you want to enable and assign the values with the information you obtained previously during the client creation.
Uncommented providers but with empty
CLIENT_SECRET won't be available.
Sign with a provider
Once a provider is enabled, a button to Continue with this provider is available on the 2FAuth's Login page.
Clicking a button will take you through the following steps:
- You will be redirected to the provider site (where you may need to authenticate)
- You will be prompted to grant permissions to 2FAuth to access your account
- Regardless of your choice, you will be redirected back to 2FAuth
- If you have granted access, you will be authenticated. If not, you will be back to the login form
You cannot sign in via SSO with a provider account that uses an email already registered on 2FAuth. Accounts cannot be merged.
Registered without registering
When you sign in via SSO for the first time, you are registered to 2FAuth transparently. This means you own a 2FAuth user account on the instance but this account is bound to the provider account with the following restrictions:
- You won't be provided with a password, but the reset password feature will apply if you need one (e.g. to delete your account)
- The 2FAuth account cannot be unbound from the provider account.
- You cannot change your information from 2FAuth. But changes made on the provider side are reflected on 2FAuth each time you sign in via SSO.
As an administrator, you can fully disable Single sign-On from the 2FAuth UI.
Go to Settings > Options, scroll down to the Administration section and uncheck.
- Existing "SSO users" won't be able to sign in via SSO anymore, but their accounts remain. Still, the password reset feature can be used so they can get a password and sign in again.
- There is no need to disable the providers env vars.
Enabling back SSO restores the providers and the ability for SSO users to sign in again.