Powered by

# 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.

# Enabling SSO

SSO is enabled by default. You can check it or change it at Admin > Auth.

# 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_url]/socialite/callback/[the_provider_name]

Example:
_Your 2FAuth instance url is https://2fauth.mydomain.com
_Your provider is Github

Then your callback URL is:
https://2fauth.mydomain.com/socialite/callback/github

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)

Manage your OAuth apps
https://github.com/settings/developers

creating-an-oauth-app
https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app

# 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. See also the SSO setting section.

# OpenID (enabled)
OPENID_AUTHORIZE_URL=https://samples.auth0.com/authorize
OPENID_TOKEN_URL=https://samples.auth0.com/oauth/token
OPENID_USERINFO_URL=
OPENID_CLIENT_ID=hfQ3kkxs3C45mCsc0fI8lvthuQGr7bqc
OPENID_CLIENT_SECRET=1QzLnSc1Rc3MCPm0QV2FLNaKk-Jk0bUjaCageDvxIkd2-Mp50ipiP-MCPm0QV-Da

# Following provider is disabled
# GITHUB_CLIENT_ID=xhfmb8tp7yo6vivbo1ba
# GITHUB_CLIENT_SECRET=r6t44wdh4jlm5mwso10erbjaux1b6cn1zspb3gk5

Uncomment the lines for the providers you want to enable and assign the values with the information you obtained previously during the client creation.

# Sign with a provider

Once a provider is enabled, a button to Continue with this provider is available on the 2FAuth's Login page.

Continue With buttons for SSO
Continue With buttons for SSO

Clicking a button will take you through the following steps:

  1. You will be redirected to the provider site (where you may need to authenticate)
  2. You will be prompted to grant permissions to 2FAuth to access your account
  3. Regardless of your choice, you will be redirected back to 2FAuth
  4. If you have granted access, you will be authenticated. If not, you will be back to the login form

# 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.

# Use SSO only

SSO can be set as the only authentication method available on your 2FAuth instance. Go to Admin > Auth, scroll down to the Single Sign-On section and check Use SSO only .

Enabling this setting has the following effects:

  • Most authentication features are disabled for standard users: Password & WebAuthn Login, Password Reset, Registration, OAuth PAT and WebAuthn devices management.
  • Administrators can still log in with their password or WebAuthn. This is a security feature to prevent lockout if no SSO provider is available.

# Disabling SSO

As an administrator, you can fully disable Single Sign-On from the 2FAuth UI.

Go to Admin > Auth, scroll down to the Single Sign-On section and uncheck Enable Single Sign-On .

Note that:

  • 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 unset the providers env vars.

Enabling back SSO restores the providers and the ability for SSO users to sign in again.