Last Updated: August 5, 2015
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.
These instructions assume that you have generated a new settings file after upgrading to Tethys Platform 1.2.0 or later. If this is not the case, please review the Social Auth Settings section.
- Create a Google Developer Account
You will need a Google developer account to register your Tethys Portal with Google. To create an account, visit https://developers.google.com and sign in with a Google account.
- Create a New Project
Use the Google Developer Console to create a new project.
- Create a New Client ID
After the project has been created, select the project and use the navigation on the left to go to
APIs & auth > Credentialsand press the
Create new Client IDbutton in the OAuth section.
- Configure the Consent ScreenIn the window that appears, select
Web Applicationand press
Configure consent screen. The consent screen is what the user sees when they log into Tethys using their Google account. You need to provide information like the name of your Tethys Portal and your logo.
- Provide Authorized Origins
As a security precaution, Google will only accept authentication requests from the hosts listed in the
www.example.org, you would add the following entries:https://www.example.org http://localhost:8000
- 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/. For a Tethys Portal at domain
Create Client IDButtonTake note the
Client secretthat are assigned to your app for the next step.
- Enable the Google+ API
- Use the navigation on the left to go to
APIs & auth > APIs.
- Search for
Google+ APIand select it from the results.
- Click on the
Enable APIbutton to enable it.
Some Google APIs are free to use up to a certain quota of hits. Familiarize your self with the quotas for any APIs you use by selecting the API and viewing the
settings.pyscript located in
social.backends.google.GoogleOAuth2backend to the
AUTHENTICATION_BACKENDSsetting:AUTHENTICATION_BACKENDS = ( ... 'social.backends.google.GoogleOAuth2', 'django.contrib.auth.backends.ModelBackend', )
Client secretto the
SOCIAL_AUTH_GOOGLE_AUTH2_SECRETsettings, respectively:SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = '...' SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = '...'
- 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.
My Appsand select
Become a Facebook Developer. Click on
Register Nowand then accept the terms.
- Create a Facebook App
- Point to
My Appsand select
Add a New App.
- Select the
- Type the name of the new app in the text field and press the
Create New Facebook App IDbutton from the drop down.
- Choose a category and press
Create App ID.
- View the Quick Start tutorial if you wish or press the
Skip Quick Startbutton to skip.
- Note the
App Secretfor Step 5.
- Setup OAuth
Settingsfrom the left navigation menu and add a
- Click on the
Advancedtab and add the callback URIs to the Valid OAuth redirect URIs field. For example, if my Tethys Portal was located at
Status & Reviewfrom the left navigation menu. Make the app public by changing the toggle switch to
The Facebook app must be public for you to allow anyone to authenticate using Facebook in your Tethys Portal. For testing, you can use the
Rolesmenu item to add specific Facebook users that are allowed to authenticate when the app is in development mode.
settings.pyscript located in
social.backends.facebook.FacebookOAuth2backend to the
AUTHENTICATION_BACKENDSsetting:AUTHENTICATION_BACKENDS = ( ... 'social.backends.facebook.FacebookOAuth2', 'django.contrib.auth.backends.ModelBackend', )
App secretto the
SOCIAL_AUTH_FACEBOOK_SECRETsettings, respectively:SOCIAL_AUTH_FACEBOOK_KEY = '...' SOCIAL_AUTH_FACEBOOK_SECRET = '...'
For more detailed information about using Facebook social authentication see the following articles:
- 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.
- Create and setup a HydroShare Application
- Navigate to https://www.hydroshare.org/o/applications/register/.
- 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
- Client id: Leave unchanged. Note this value for step 3.
- Client secret: Leave unchanged. Note this value for step 3.
- Client type: Select "Confidential".
- Authorization grant type: Select "Authorzation code".
- 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/
- Press the "Save" button.
settings.pyscript located in
social.backends.hydroshare.HydroShareOAuth2backend to the
AUTHENTICATION_BACKENDSsetting:AUTHENTICATION_BACKENDS = ( 'tethys_services.backends.hydroshare.HydroShareOAuth2', ... 'django.contrib.auth.backends.ModelBackend', )
Client Secretto the
SOCIAL_AUTH_HYDROSHARE_SECRETsettings, respectively:SOCIAL_AUTH_HYDROSHARE_KEY = '...' SOCIAL_AUTH_HYDROSHARE_SECRET = '...'
- 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
(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:
Append the following classes in
Client Secretto the following variables:
Note: To prevent any unexpected behavior in section (4), a Tethys account SHOULD NOT be associated with multiple HydroShare social accounts.
For more detailed information about using HydroShare social authentication see the following articles:
Social Auth Settings¶
Social authentication requires Tethys Platform 1.2.0 or later. If you are using an older version of Tethys Platform, you will need to upgrade by following either the Upgrade to 2.1.0 instructions. The
settings.py script is unaffected by the upgrade. You will need to either generate a new
settings.py script using
tethys gen settings or add the following settings to your existing
settings.py script to support social login.
INSTALLED_APPS = ( ... 'social.apps.django_app.default', ) MIDDLEWARE_CLASSES = ( ... 'tethys_portal.middleware.TethysSocialAuthExceptionMiddleware', ) TEMPLATE_CONTEXT_PROCESSORS = ( ... 'django.core.context_processors.request', 'social.apps.django_app.context_processors.backends', 'social.apps.django_app.context_processors.login_redirect', ) # OAuth Settings SOCIAL_AUTH_ADMIN_USER_SEARCH_FIELDS = ['username', 'first_name', 'email'] SOCIAL_AUTH_SLUGIFY_USERNAMES = True SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/apps/' SOCIAL_AUTH_LOGIN_ERROR_URL = '/accounts/login/' # OAuth Providers ## Google SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = '' SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = '' ## Facebook SOCIAL_AUTH_FACEBOOK_KEY = '' SOCIAL_AUTH_FACEBOOK_SECRET = '' SOCIAL_AUTH_FACEBOOK_SCOPE = ['email'] ## LinkedIn SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY = '' SOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET = '' ## HydroShare SOCIAL_AUTH_HYDROSHARE_KEY = '' SOCIAL_AUTH_HYDROSHARE_SECRET = ''