Single Sign On (Optional)¶
Last Updated: July 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 and the social buttons provided by the Social Buttons for Bootstrap. Social login is disabled by default, because enabling it requires registering your tethys portal instance with each provider.
Enable Social Login¶
Use the following instructions to setup social login for the providers you desire.
Caution
Beginning with Tethys Platform 3.0 you must configure the social auth settings in the portal_config.yml
file. See Tethys Portal Configuration for more details on how to create and configure this file. For instructions on how to configure social auth for previous versions of Tethys Platform please refer to the documentation specific to your version.
Azure Active Directory¶
Sign up for a free Microsoft Developer account or sign in with an existing account if you already have one. See: https://azure.microsoft.com/en-us/free/
Create an Azure AD or Azure AD B2C Tenant on Microsoft Azure Portal if you do not already have one. See: Quickstart: Set up a tenant
Note
Tethys Platform supports single sign on with both the Azure AD and Azure AD B2C environments.
Register a new application. See: Register a new application using the Azure portal
Select Web as the type of app.
Enter one of the following for the redirect URL:
If using an Azure AD Tenant and you selected either Accounts in any organizational directory or Accounts in any organizational directory and personal Microsoft accounts:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/azuread-oauth2/
If using an Azure AD Tenant and you selected Accounts in this organizational directory only:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/azuread-tenant-oauth2/
If using an Azure AD B2C Tenant:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/azuread-b2c/
On the Overview page of the App Registration you created in the previous step, note the Application (client) ID and Directory (tenant) ID for use in step 7.
Select Certificates & secrets from the menu on the left. Create a Client Secret and note it's value for use in step 7.
Enable the appropriate authentication backend:
If using an Azure AD Tenant and you selected either Accounts in any organizational directory or Accounts in any organizational directory and personal Microsoft accounts:
tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.azuread.AzureADOAuth2']"
If using an Azure AD Tenant and you selected Accounts in this organizational directory only:
tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.azuread_tenant.AzureADTenantOAuth2']"
If using an Azure AD B2C Tenant:
tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.azuread_b2c.AzureADB2COAuth2']"
Set the appropriate settings:
If using an Azure AD Tenant and you selected either Accounts in any organizational directory or Accounts in any organizational directory and personal Microsoft accounts:
tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_OAUTH2_KEY <Application/Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET <Client Secret>
If using an Azure AD Tenant and you selected Accounts in this organizational directory only:
tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY <Application/Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET <Client Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID <Directory/Tenant ID>
If using an Azure AD B2C Tenant:
tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_KEY <Application/Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_SECRET <Client Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_TENANT_ID <Directory/Tenant ID> --set OAUTH_CONFIG.SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_POLICY <Custom User Flow>
Note
Use
b2c_
as the value ofSOCIAL_AUTH_AZUREAD_B2C_OAUTH2_POLICY
if you do not have a custom user flow. See: User flows in Azure Active Directory B2C for more information.
References¶
For more detailed information about using Azure Active Directory social authentication see the following articles:
Active Directory Federation Services (AD FS)¶
Coordinate with the administrator of your organization's Windows server that is running AD FS to create a new App Registration for your Tethys Portal (see Step 2).
Important
Tethys Platform only supports authenticating with AD FS 2016 or later.
Follow the App Registration in AD FS section of the AD FS MSAL Web app (server app) calling web APIs documentation to register your Tethys Portal with the AD FS server with the following considerations:
- On the Welcome tab:
Select Server application accessing a web API as the Template.
- On the Server application tab:
Note the Client Identifier for use in Step 3.
Enter the following for the Redirect URI:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/adfs-oidc/
- On the Configure Application Credentials tab:
Note the Secret that is generated for use in Step 3.
- On the Configure Web API* tab:
Add the FQDN of your Tethys Portal as an Identifier.
- On the Configure Application Permissions tab:
Only the openid scope is required. However, you may consider permitting the email and profile scopes as well to allow Tethys Portal to populate its user profile.
Important
You do not need to complete the Code Configuration section.
Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the
tethys_services.backends.adfs.ADFSOpenIdConnect
backend to theAUTHENTICATION_BACKENDS
setting:tethys settings --set AUTHENTICATION_BACKENDS "['tethys_services.backends.adfs.ADFSOpenIdConnect']"
Use the
Client Identifier
andSecret
obtained in Step 2 to set theSOCIAL_AUTH_ADFS_OIDC_KEY
andSOCIAL_AUTH_ADFS_OIDC_SECRET
settings, respectively. Also, set theSOCIAL_AUTH_ADFS_OIDC_DOMAIN
setting with the Fully Qualified Domain Name (FQDN) of your AD FS server (e.g. "https://adfs.my-org.com"):tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_ADFS_OIDC_KEY <Client Identifier> --set OAUTH_CONFIG.SOCIAL_AUTH_ADFS_OIDC_SECRET <Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_ADFS_OIDC_DOMAIN <AD FS FQDN>
References¶
For more detailed information about using Active Directory Federation Services social authentication see the following articles:
Facebook¶
Create a Facebook Developer Account
You will need a Facebook developer account to register your Tethys Portal with Facebook. To create an account, visit https://developers.facebook.com and sign in with a Facebook account.
Create a Facebook App
Point to
My Apps
and selectCreate App
.Fill out the form and press
Create App ID
button.
Setup OAuth
Scroll down and locate the tile titled Facebook Login.
Press the
Setup
button on the tile (orSettings
if setup previously).Specify the following for the Valid OAuth Redirect URIs field:
https://<SERVER_DOMAIN_NAME>/oauth2/complete/facebook/
Note
Replace
<SERVER_DOMAIN_NAME>
with the value determined during the Preparation step.Note
Localhost domains are automatically enabled when the app is in development mode, so you don't need to add them for Facebook OAuth logins.
Press the
Save Changes
button.
Make the app public you wish by changing the toggle switch in the header from
Off
toOn
.
Note
The Facebook app must be public to allow Facebook authentication to non-localhost Tethys Portals.
Expand the
Settings
menu on the left and selectBasic
. Note theApp ID
andApp Secret
.Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the
social_core.backends.facebook.FacebookOAuth2
backend to theAUTHENTICATION_BACKENDS
setting:tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.facebook.FacebookOAuth2']"
Copy the
App ID
andApp Secret
to theSOCIAL_AUTH_FACEBOOK_KEY
andSOCIAL_AUTH_FACEBOOK_SECRET
settings, respectively:tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_FACEBOOK_KEY <App ID> --set OAUTH_CONFIG.SOCIAL_AUTH_FACEBOOK_SECRET <App Secret>
References¶
For more detailed information about using Facebook social authentication see the following articles:
Google¶
Create a Google Developer Account
Follow these instructions to register your project and create a client ID: Setting Up OAuth 2.0. Provide the following as you setup OAuth2:
Provide Authorized JavaScript Origins
As a security precaution, Google will only accept authentication requests from the hosts listed in the
Authorized JavaScript Origins
box. Add the domain of your Tethys Portal to the list. Optionally, you may add a localhost domain to the list to be used during testing:https://<SERVER_DOMAIN_NAME> http://localhost:8000
Note
Replace
<SERVER_DOMAIN_NAME>
with the value determined during the Preparation step.Provide Authorized Redirect URIs
You also need to provide the callback URI for Google to call once it has authenticated the user. This follows the pattern
http://<host>/oauth2/complete/google-oauth2/
:https://<SERVER_DOMAIN_NAME>/oauth2/complete/google-oauth2/ https://localhost:8000/oauth2/complete/google-oauth2/
Note
Replace
<SERVER_DOMAIN_NAME>
with the value determined during the Preparation step.Note
Some Google APIs are free to use up to a certain quota of hits. Be sure to familiarize yourself with the terms of use for each service.
Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the
social_core.backends.google.GoogleOAuth2
backend to theAUTHENTICATION_BACKENDS
setting:tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.google.GoogleOAuth2']"
Copy the
Client ID
andClient secret
into theSOCIAL_AUTH_GOOGLE_OAUTH2_KEY
andSOCIAL_AUTH_GOOGLE_AUTH2_SECRET
settings, respectively:tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_GOOGLE_OAUTH2_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET <Client secret>
References¶
For more detailed information about using Google social authentication see the following articles:
LinkedIn¶
Create a LinkedIn Developer Account
You will need a LinkedIn developer account to register your Tethys Portal with LinkedIn. To create an account, visit https://developer.linkedin.com/my-apps and sign in with a LinkedIn account.
Create a LinkedIn Application
Navigate back to https://www.linkedin.com/developers/apps, if necessary and press the
Create App
button.Fill out the form and press
Create App
.
Open the Auth tab and note the
Client ID
andClient Secret
for Step 5.Setup OAuth
Add the call back URLs under the OAuth 2.0 settings section:
https://<SERVER_DOMAIN_NAME>/oauth2/complete/linkedin-oauth2/ http://localhost:8000/oauth2/complete/linkedin-oauth2/
Note
Replace
<SERVER_DOMAIN_NAME>
with the value determined during the Preparation step.
Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the
social_core.backends.linkedin.LinkedinOAuth2
backend to theAUTHENTICATION_BACKENDS
setting:tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.linkedin.LinkedinOAuth2']"
Copy the
Client ID
andClient Secret
to theSOCIAL_AUTH_LINKEDIN_OAUTH2_KEY
andSOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET
settings, respectively:tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET <Client Secret>
References¶
For more detailed information about using LinkedIn social authentication see the following articles:
Okta¶
Tethys Platform supports two methods of Okta single sign on: OAuth 2.0 and OpenID Connect. Both methods should work and accomplish the same result. At the time of writing there were bugs in the extra dependency required by the OpenID Connect method that prevented it from working properly. Until the bugs are addressed, we recommend using the OAuth 2.0 method.
If you would like to use the OpenID Connect method, you will need to install an additional dependency (skip if using OAuth2 method):
conda install -c conda-forge python-jose
Warning
At the time of writing, the
jose
package contained syntax errors that made the OpenID Connect method unusable.Create an Okta Developer Account
You will need an Okta developer account to register your Tethys Portal with Okta. To create an account, visit https://developer.okta.com/signup/.
Create an Okta Application
Follow the steps outlined in this document to create an Okta application: Create an Okta application. Set the callback URL as follows:
OAuth 2.0 method (recommended):
https://<SERVER_DOMAIN_NAME>/oauth/complete/okta-oauth2/
OpenID Connect method:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/okta-openidconnect/
Select the General tab of the application and note the
Client ID
andClient Secret
for Step 5.Navigate back to the Dashboard page of the developer console and note the Org URL, located near the top right side of the page. The Org URL is needed for step 5.
Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the appropriate authentication backend:
OAuth 2.0 method (recommended):
tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.okta.OktaOAuth2']"
OpenID method interface:
tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.okta_openidconnect.OktaOpenIdConnect']"
Use the
Client ID
,Client Secret
, andOrg URL
to set the appropriateKEY
,CLIENT
, andAPI_URL
settings, respectively:OAuth 2.0 method (recommended):
tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OAUTH2_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OAUTH2_SECRET <Client Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OAUTH2_API_URL <Org URL>
OpenID Connect method:
tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET <Client Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL <Org URL>
References¶
For more detailed information about using Okta social authentication see the following articles:
OneLogin¶
Create an OneLogin Developer Account
You will need a OneLogin developer account to register your Tethys Portal with OneLogin. To create an account, visit https://www.onelogin.com/developer-signup.
Create an OneLogin Application
Follow the steps outlined in this document to add your portal as an app in OneLogin: Connect an OIDC enabled app.
When prompted, set the redirect URL as follows:
http://<SERVER_DOMAIN_NAME>/oauth2/complete/onelogin-oidc/ http://localhost:8000/oauth2/complete/onelogin-oidc/
If you wish, you may also want to specify the login URL for your portal:
http://<SERVER_DOMAIN_NAME>/login/ http://localhost:8000/login/
On the SSO tab, set the Token Endpoint Authentication Method to
POST
.
Select the SSO tab if you are not on it already and note the
Client ID
andClient Secret
for Step 5.Point to Settings > Account Settings and note the
Subdomain
for step 5.Add the appropriate settings to the
portal_config.yml
file using thetethys settings
command:Add the appropriate authentication backend:
tethys settings --set AUTHENTICATION_BACKENDS "['tethys_services.backends.onelogin.OneLoginOIDC']"
Use the
Client ID
,Client Secret
, andSubdomain
to set the appropriateKEY
,CLIENT
, andSUBDOMAIN
settings, respectively:tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_ONELOGIN_OIDC_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_ONELOGIN_OIDC_SECRET <Client Secret> --set OAUTH_CONFIG.SOCIAL_AUTH_ONELOGIN_OIDC_SUBDOMAIN <Subdomain>
References¶
For more detailed information about using OneLogin social authentication see the following articles:
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
: