Table Of Contents

Social Authentication (Optional)

Last Updated: May 2020

Tethys Portal supports authenticating users with Google, Facebook, LinkedIn and HydroShare 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.

Google

1. 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:

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

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

2. Add the appropriate settings to the portal_config.yml file using the tethys settings command:

   Add the social_core.backends.google.GoogleOAuth2 backend to the AUTHENTICATION_BACKENDS setting:

   tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.google.GoogleOAuth2']"
   

   Copy the Client ID and Client secret into the SOCIAL_AUTH_GOOGLE_OAUTH2_KEY and SOCIAL_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:

• Developer Console Help

• Google Identity Platform

Facebook

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

2. Create a Facebook App

   1. Point to My Apps and select Create App.

   2. Fill out the form and press Create App ID button.

3. Setup OAuth

   1. Scroll down and locate the tile titled Facebook Login.

   2. Press the Setup button on the tile (or Settings if setup previously).

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

   4. Press the Save Changes button.

   3. Make the app public you wish by changing the toggle switch in the header from Off to On.

   Note

   The Facebook app must be public to allow Facebook authentication to non-localhost Tethys Portals.

4. Expand the Settings menu on the left and select Basic. Note the App ID and App Secret.

5. Add the appropriate settings to the portal_config.yml file using the tethys settings command:

   Add the social_core.backends.facebook.FacebookOAuth2 backend to the AUTHENTICATION_BACKENDS setting:

   tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.facebook.FacebookOAuth2']"
   

   Copy the App ID and App Secret to the SOCIAL_AUTH_FACEBOOK_KEY and SOCIAL_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:

• Facebook Login

• Facebook Login for the Web with the JavaScript SDK

LinkedIn

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

2. Create a LinkedIn Application

   1. Navigate back to https://www.linkedin.com/developers/apps, if necessary and press the Create App button.

   2. Fill out the form and press Create App.

3. Open the Auth tab and note the Client ID and Client Secret for Step 5.

4. Setup OAuth

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

5. Add the appropriate settings to the portal_config.yml file using the tethys settings command:

   Add the social_core.backends.linkedin.LinkedinOAuth2 backend to the AUTHENTICATION_BACKENDS setting:

   tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.linkedin.LinkedinOAuth2']"
   

   Copy the Client ID and Client Secret to the SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY and SOCIAL_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:

• LinkedIn: Authenticating with OAuth 2.0

HydroShare

1. Create a HydroShare Account

   You will need a HydroShare account to register your Tethys Portal with HydroShare. To create an account, visit https://www.hydroshare.org.

2. Create and setup a HydroShare Application

   1. Navigate to https://www.hydroshare.org/o/applications/register/.

   2. Name: Give this OAuth app a name. It is recommended to use the domain of your Tethys Portal instance as the name, like: www.my-tethys-portal.com

   3. Client id: Leave unchanged. Note this value for step 3.

   4. Client secret: Leave unchanged. Note this value for step 3.

   5. Client type: Select "Confidential".

   6. Authorization grant type: Select "Authorization code".

   7. Redirect uris: Add the call back URLs. The protocol (http or https) that matches your Tethys Portal settings should be included in this url. For example:

   if your Tethys Portal was located at the domain ``https://www.my-tethys-portal.com``:
       https://www.my-tethys-portal.com/oauth2/complete/hydroshare/
   
   if your Tethys Portal was on a local development machine:
       http://localhost:8000/oauth2/complete/hydroshare/
       or
       http://127.0.0.1:8000/oauth2/complete/hydroshare/
   

   8. Press the "Save" button.

3. Add the appropriate settings to the portal_config.yml file using the tethys settings command:

   Add the tethys_services.backends.hydroshare.HydroShareOAuth2 backend to the AUTHENTICATION_BACKENDS setting:

   tethys settings --set AUTHENTICATION_BACKENDS "['tethys_services.backends.hydroshare.HydroShareOAuth2']"
   

   Assign the Client id and Client secret to the SOCIAL_AUTH_HYDROSHARE_KEY and SOCIAL_AUTH_HYDROSHARE_SECRET settings, respectively:

   tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_HYDROSHARE_KEY <Client id> --set OAUTH_CONFIG.SOCIAL_AUTH_HYDROSHARE_SECRET <Client secret>
   

4. Work with HydroShare in your app

Once user has logged in Tethys through HydroShare OAuth, your app is ready to retrieve data from HydroShare on behalf of this HydroShare user using HydroShare REST API Client (hs_restclient). A helper function is provided to make this integration smoother.

# import helper function
from tethys_services.backends.hs_restclient_helper import get_oauth_hs

# your controller function
def home(request)

    # put codes in a 'try..except...' statement
    try:
        # pass in request object
        hs = get_oauth_hs(request)

        # your logic goes here. For example: list all HydroShare resources
        for resource in hs.getResourceList():
            print(resource)

    except Exception as e:
        # handle exceptions
        pass

5. (Optional) Link to a testing HydroShare instance

   The production HydroShare is located at https://www.hydroshare.org/. In some cases you may want to link your Tethys Portal to a testing HydroShare instance, like hydroshare-beta. Tethys already provides OAuth backends for hydroshare-beta and hydroshare-playground. To activate them, you need to go through steps 1-3 for each backend (replace www.hydroshare.org with the testing domain urls accordingly).

   At step 3:

   1. Append the following classes in AUTHENTICATION_BACKENDS settings:

      hydroshare-beta:

      tethys_services.backends.hydroshare_beta.HydroShareBetaOAuth2

      hydroshare-playground:

      tethys_services.backends.hydroshare_playground.HydroSharePlaygroundOAuth2

   2. Assign the Client ID and Client Secret to the following variables:

      hydroshare-beta:

      SOCIAL_AUTH_HYDROSHARE_BETA_KEY

      SOCIAL_AUTH_HYDROSHARE_BETA_SECRET

      hydroshare-playground:

      SOCIAL_AUTH_HYDROSHARE_PLAYGROUND_KEY

      SOCIAL_AUTH_HYDROSHARE_PLAYGROUND_SECRET

   Note

   To prevent any unexpected behavior in section (4), a Tethys account SHOULD NOT be associated with multiple HydroShare social accounts.

References

For more detailed information about using HydroShare social authentication see the following articles:

• https://github.com/hydroshare/hydroshare/wiki/HydroShare-REST-API#oauth-20-support

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.

Caution

Social authentication requires Tethys Platform 1.2.0 or later. For instructions on how to configure social auth for previous versions of Tethys Platform please refer to the documentation specific to your version.

The following settings in the portal_config.yml are used to configure social authentication:

AUTHENTICATION_BACKENDS:
  - social.backends.google.GoogleOAuth2
  - social.backends.facebook.FacebookOAuth2
  - social.backends.linkedin.LinkedinOAuth2
  - tethys_services.backends.hydroshare.HydroShareOAuth2

OAUTH_CONFIG:
  SOCIAL_AUTH_GOOGLE_OAUTH2_KEY: ''
  SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET: ''

  SOCIAL_AUTH_FACEBOOK_KEY: ''
  SOCIAL_AUTH_FACEBOOK_SECRET: ''
  SOCIAL_AUTH_FACEBOOK_SCOPE: ['email']

  SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY: ''
  SOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET: ''

  SOCIAL_AUTH_HYDROSHARE_KEY: ''
  SOCIAL_AUTH_HYDROSHARE_SECRET: ''

You can use the tethys settings command to easily set the settings in the portal_config.yml. For example:

tethys settings --set AUTHENTICATION_BACKENDS "['social_core.backends.google.GoogleOAuth2', 'social_core.backends.facebook.FacebookOAuth2']"

tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_GOOGLE_OAUTH2_KEY <Client ID> --set OAUTH_CONFIG.SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET <Client secret>

tethys settings --set OAUTH_CONFIG.SOCIAL_AUTH_FACEBOOK_KEY <App ID> --set OAUTH_CONFIG.SOCIAL_AUTH_FACEBOOK_SECRET <App Secret>

Important

Remember to restart the Tethys servers to effect any changes to the portal_config.yml:

sudo supervisor restart all

Table Of Contents

• Social Authentication (Optional)
  • Enable Social Login
    • Google
      • References
    • Facebook
      • References
    • LinkedIn
      • References
    • HydroShare
      • References
  • Social Auth Settings

arrow_back

Previous

Forgotten Password Recovery (Optional)

arrow_forward

Next

Web Analytics (Optional)