Single Sign On (Optional)
Last Updated: December 2020
Tethys Portal supports authenticating users with several social authentication and single sign on providers such as Google, Facebook, and LinkedIn via the OAuth 2.0 method. The social authentication and authorization features have been implemented using the Python Social Auth module. Social login is disabled by default, because enabling it requires registering your tethys portal instance with each provider.
Multi-Tenant SSO
A multi-tenant SSO provider is one that provides separate instances of it's SSO services for each organization or tenant that uses it. Each instance of the service is accessed via a different URL (e.g.: my-organization.onelogin.com, login.microsoftonline.com/<tenant-id>/, adfs.my-organization.com). Tethys Portal provides custom backends for some of the multi-tenant SSO providers that are able to handle multiple sets of credentials, one for each tenant. The providers supported include Okta, OneLogin, AzureAD, and AD FS.
Authentication Flow
The multi-tenant SSO authentication flow introduces an additional step in the authentication process that prompts the user for an identifier called a Tenant Key. Usually the Tenant Key is just the name of their organization or some variant of it. To illustrate the multi-tenant SSO authentication flow, consider the following example:
Jyn Erso would like to log in to a Tethys Portal that has been configured to use her company's SSO provider, OneLogin. To login, Jyn completes the following steps:
She navigates to the login page for the Tethys Portal: http://tethys.not-real.org/login/

Next, Jyn clicks on the Log In with OneLogin link.
She enters the name of her company, "Rebel Acquisitions", as the Tenant Key and presses the Next button.

She is redirected to the authentication page for her company: http://rebel-acq.onelogin.com/login2/

She enters her username and password as usual.
Jyn is then returned to the Tethys Portal, now logged in.

Note
The default title for the page that requests the Tenant Key (see screenshot for step 3) is "Tenant", but it can be customized via the SSO_TENANT_ALIAS
setting:
SSO_TENANT_ALIAS: 'Company'
Configuration
Configuring multi-tenant SSO backends is similar to configuring other SSO backends. The primary difference is that you will need to provide the required settings (i.e. KEY
, SECRET
, etc.) for multiple tenants instead of globally for the backend. All of these tenant settings are organized under a MULTI_TENANT
setting for the backend, and settings for each tenant are grouped under a Tenant Key. For example:
SOCIAL_AUTH_ONELOGIN_OIDC_MULTI_TENANT:
tenant1:
SOCIAL_AUTH_ONELOGIN_OIDC_KEY: <Tenant 1 Key>
SOCIAL_AUTH_ONELOGIN_OIDC_SECRET: <Tenant 1 Secret>
SOCIAL_AUTH_ONELOGIN_OIDC_SUBDOMAIN: <Tenant 1 Subdomain>
tenant2:
SOCIAL_AUTH_ONELOGIN_OIDC_KEY: <Tenant 2 Key>
SOCIAL_AUTH_ONELOGIN_OIDC_SECRET: <Tenant 2 Secret>
SOCIAL_AUTH_ONELOGIN_OIDC_SUBDOMAIN: <Tenant 2 Subdomain>
Tenant Keys
A Tenant Key is a string that is used to identify a set of settings for a tenant under one of the MULTI_TENANT
settings. Tenant Keys may only contain the following characters:
any lowercase letter
any number
spaces
hyphens (-)
underscores (_)
Care should be taken when selecting Tenant Keys, as users will be required to enter it whenever they login to your Tethys Portal using that tenant. The values provided by users are normalized to all lower case characters before attempting the lookup in the MULTI_AUTH
settings. In other words, "Rebel Acquisitions", "rebel acquisitions" and "REBEL ACQUISITIONS" are all normalized to the Tenant Key "rebel acquisitions".
Please use the following guidelines when choosing a Tenant Key:
Choose something easy to remember and intuitive for the user.
Use the name of the organization or a short variant of it if possible.
Tenant keys may include spaces to allow for more intuitive values for users.
Users may use title case or any other case when entering the Tenant Key, but the Tenant Key must always be specified using lowercase letters in the
portal_config.yml
.
The following values are examples of invalid Tenant Keys for the portal_config.yml
:
"Rebel Acquisitions" -> no uppercase characters allowed.
"palpatine & vaders" -> the "&" character is not allowed.
"watto's_repair" -> no apostrophes allowed.
The following values are examples of valid Tenant Keys for the portal_config.yml
:
"rebel acquisitions"
"palpatine and vaders"
"wattos_repair"
"maz-kanatas"
The following is an example of a MULTI_TENANT
setting with valid Tenant Keys:
SOCIAL_AUTH_ONELOGIN_OIDC_MULTI_TENANT:
rebel acquisitions:
...
palpatine and vaders:
...
wattos_repair:
...
maz-kanatas:
...
Note
The following regular expression is used to validate Tenant Keys: '^[\w\s_-]+$'
. You may override this value with your own using the SSO_TENANT_REGEX
setting:
SSO_TENANT_REGEX: '^[\w\s^$_-]+$'
See Regular expression operations for more details on valid regular expression syntax in Python.
Azure AD Multi Tenant
Follow the normal steps for registering the Tethys Portal with the organization's AzureAD tenant and obtain the Application (client) ID, Client Secret, and Directory (tenant) ID (see: Azure Active Directory Steps 3-5).
Enable the appropriate multi-tenant backend for Azure AD:
If using an Azure AD Tenant and you selected Accounts in this organizational directory only:
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.azuread.AzureADTenantOAuth2MultiTenant
Warning
Do not enable both the
AzureADTenantOAuth2MultiTenant
andAzureADTenantOAuth2
backends at the same time. TheAzureADTenantOAuth2MultiTenant
will fall back to behaving like theAzureADTenantOAuth2
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.If using an Azure AD B2C Tenant:
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.azuread.AzureADB2COAuth2MultiTenant
Warning
Do not enable both the
AzureADB2COAuth2MultiTenant
andAzureADB2COAuth2
backends at the same time. TheAzureADB2COAuth2MultiTenant
will fall back to behaving like theAzureADB2COAuth2
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.
Add the appropriate
MULTI_TENANT
setting with the settings for one or more tenants grouped under the desired Tenant Key:If using an Azure AD Tenant and you selected Accounts in this organizational directory only:
pythonSOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY: <Application/Client ID> SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID: <Directory/Tenant ID> <tenant_key>: SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY: <Application/Client ID> SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID: <Directory/Tenant ID>
If using an Azure AD B2C Tenant:
pythonSOCIAL_AUTH_AZUREAD_B2C_OAUTH2_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_KEY: <Application/Client ID> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_TENANT_ID: <Directory/Tenant ID> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_POLICY: b2c_ <tenant_key>: SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_KEY: <Application/Client ID> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_TENANT_ID: <Directory/Tenant ID> SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_POLICY: b2c_
AD FS Multi Tenant
Follow the normal steps for registering the Tethys Portal on with the AD FS server and obtain the Client Identifier, Secret, and Server Domain Name (see: Active Directory Federation Services (AD FS) Steps 1-2).
Enable the multi-tenant backend for AD FS:
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.adfs.ADFSOpenIdConnectMultiTenant
Warning
Do not enable both the
ADFSOpenIdConnectMultiTenant
andADFSOpenIdConnect
backends at the same time. TheADFSOpenIdConnectMultiTenant
will fall back to behaving like theADFSOpenIdConnect
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.Add the
MULTI_TENANT
setting with the settings for one or more AD FS servers grouped under the desired Tenant Key:pythonSOCIAL_AUTH_ADFS_OIDC_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_ADFS_OIDC_KEY: <Client Identifier> SOCIAL_AUTH_ADFS_OIDC_SECRET: <Secret> SOCIAL_AUTH_ADFS_OIDC_DOMAIN: <Server Domain Name> <tenant_key>: SOCIAL_AUTH_ADFS_OIDC_KEY: <Client Identifier> SOCIAL_AUTH_ADFS_OIDC_SECRET: <Secret> SOCIAL_AUTH_ADFS_OIDC_DOMAIN: <Server Domain Name>
Okta Multi Tenant
Follow the normal steps for registering the Tethys Portal with the organization's Okta instance and obtain the Client ID, Client Secret, and Org URL (see: Okta Steps 2-4).
Enable the appropriate multi-tenant backend for Azure AD:
OAuth 2.0 method (recommended):
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.okta.OktaOauth2MultiTenant
Warning
Do not enable both the
OktaOauth2MultiTenant
andOktaOAuth2
backends at the same time. TheOktaOauth2MultiTenant
will fall back to behaving like theOktaOAuth2
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.OpenID Connect method:
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.okta.OktaOpenIdConnectMultiTenant
Warning
Do not enable both the
OktaOpenIdConnectMultiTenant
andOktaOpenIdConnect
backends at the same time. TheOktaOpenIdConnectMultiTenant
will fall back to behaving like theOktaOpenIdConnect
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.
Add the appropriate
MULTI_TENANT
setting with the settings for one or more tenants grouped under the desired Tenant Key:OAuth 2.0 method (recommended):
pythonSOCIAL_AUTH_OKTA_OAUTH2_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_OKTA_OAUTH2_KEY: <Client ID> SOCIAL_AUTH_OKTA_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_OKTA_OAUTH2_API_URL: <Org URL> <tenant_key>: SOCIAL_AUTH_OKTA_OAUTH2_KEY: <Client ID> SOCIAL_AUTH_OKTA_OAUTH2_SECRET: <Client Secret> SOCIAL_AUTH_OKTA_OAUTH2_API_URL: <Org URL>
OpenID Connect method:
pythonSOCIAL_AUTH_OKTA_OPENIDCONNECT_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY: <Client ID> SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET: <Client Secret> SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL: <Org URL> <tenant_key>: SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY: <Client ID> SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET: <Client Secret> SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL: <Org URL>
OneLogin Multi Tenant
Follow the normal steps for registering the Tethys Portal on with the OneLogin server and obtain the Client ID, Client Secret, and Subdomain (see: OneLogin Steps 2-4).
Enable the multi-tenant backend for OneLogin:
pythonAUTHENTICATION_BACKENDS: - tethys_services.backends.onelogin.OneLoginOIDCMultiTenant
Warning
Do not enable both the
OneLoginOIDCMultiTenant
andOneLoginOIDC
backends at the same time. TheOneLoginOIDCMultiTenant
will fall back to behaving like theOneLoginOIDC
if theMULTI_TENANT
setting is not present, so it is not necessary to use both.Add the
MULTI_TENANT
setting with the settings for one or more OneLogin servers grouped under the desired Tenant Key:pythonSOCIAL_AUTH_ONELOGIN_OIDC_MULTI_TENANT: <tenant_key>: SOCIAL_AUTH_ONELOGIN_OIDC_KEY: <Client ID> SOCIAL_AUTH_ONELOGIN_OIDC_SECRET: <Client Secret> SOCIAL_AUTH_ONELOGIN_OIDC_SUBDOMAIN: <Subdomain> <tenant_key>: SOCIAL_AUTH_ONELOGIN_OIDC_KEY: <Client ID> SOCIAL_AUTH_ONELOGIN_OIDC_SECRET: <Client Secret> SOCIAL_AUTH_ONELOGIN_OIDC_SUBDOMAIN: <Subdomain>
Social Auth Settings
Beginning with Tethys Platform 3.0.0 the social auth settings are configured in the
portal_config.yml
file. The following is a summary of all the settings that would need to be added for the various supported social auth backends.The following settings in the
portal_config.yml
are used to configure social authentication:You can use the
tethys settings
command to easily set the settings in theportal_config.yml
. For example:Important
Remember to restart the Tethys servers to effect any changes to the
portal_config.yml
: