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

SSO is enabled by default. You can check it at Admin > App setup, in the Registrations section.

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.

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.

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:

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

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 Admin > App setup, scroll down to the Registrations 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.