4.18.3.2.1. Integrating with an OAuth2 Identity Provider

Open edX has specific instructions for Google, Facebook, LinkedIn, and Azure Active Directory. For more information about how to set up one or more of these integrations, see Common OAuth2 Providers.

The system also supports integrations with alternative OAuth2 providers. For more information, see Additional OAuth2 Providers (Advanced).

4.18.3.2.1.1. Common OAuth2 Providers

Integrating with the most common OAuth2 IdPs has several steps.

  1. Register the Open edX instance with the provider.
  2. Configure Open edX.
  3. Add the provider configuration.

4.18.3.2.1.1.1. Register the Open edX Instance

The most commmon OAuth2 providers are Google, Facebook, LinkedIn, and Azure Active Directory.

4.18.3.2.1.1.1.1. Register the Open edX Instance with Google

The following instructions describe how to configure Google as a third party authentication provider so that users can use Google accounts (which includes Google Apps accounts) to sign in. These are based on the official Google instructions.

  1. Obtain credentials to access the Google API. To do this, follow the official Google instructions to go to the Google Developers Console, create a new project, and enable the Google+ API service.
  2. In the Google Developers Console, select API Manager, and then select OAuth Consent Screen.
  3. For Product name shown to users enter the name of your Open edX instance (for example, “Example Academy Online”).
  4. Select Save.
  5. Select the Credentials tab, select Create credentials, and then select OAuth client ID.
    • For Application type, select Web application.
    • Leave the Authorized JavaScript origins field blank.
    • For Authorized redirect URIs, enter <Open edX instance domain>/auth/complete/google-oauth2/. For example, for devstack, enter http://localhost:8000/auth/complete/google-oauth2/.
    • Select Create to finish creating the credentials.
  6. After you obtain the credentials, note the client ID and the client secret.

4.18.3.2.1.1.1.2. Register the Open edX Instance with Facebook

To create the app in the Facebook developer portal, follow these steps.

  1. Sign in to Facebook, then go to the Facebook for Developers page.

  2. Select Add a New App, and then select Website.

  3. Enter a name for the app, and then select Create New Facebook App ID.

  4. Enter your information in the rest of the fields in the app creation process.

  5. Under Quick Start for Website, select Skip Quick Start.

    You are now at the developer console page for the new Facebook app.

  6. Select Settings, and note the App ID and App Secret.

  7. On the Settings page, select Add Platform, and then select Website.

  8. For Site URL, enter the URL of your Open edX instance (for example, <http://localhost:8000/> for devstack).

  9. In the App Domains field, enter the domain name from this URL (for example, localhost).

  10. Select Save Changes.

4.18.3.2.1.1.1.3. Register the Open edX Instance with LinkedIn

To create the LinkedIn app, follow these steps.

  1. Go to the LinkedIn Developers page.
  2. Click Create Application, enter your information in the form, and then submit the form.
  3. On the page that opens with information about the app, note the Client ID and Client Secret.
  4. In the OAuth 2.0 section, for Authorized Redirect URL, enter <Open edX instance domain>/auth/complete/linkedin-oauth2/. For example, for devstack, enter http://localhost:8000/auth/complete/linkedin-oauth2/.
  5. Select Update to save your information.

4.18.3.2.1.1.1.4. Register the Open edX Instance with Azure Active Directory

You can use Azure Active Directory to allow users with Microsoft Office 365 Business accounts to sign in to Open edX. Note that this feature currently does not work with other types of Microsoft accounts (such as “@live.com” or “@hotmail.com” accounts).

  1. If you do not have a Microsoft account, create one on the Microsoft sign in page.

  2. If you do not have an Azure subscription, create one on the Azure account creation page.

    Note

    You must enter a credit card on this page, but if you do not create any virtual machines or other services besides Azure AD, you will not be charged.

  3. Go to the Azure sign in page.

  4. Click New, locate Active Directory, and then select Create.

  5. Enter a name, domain name, and country.

  6. Create the new application.

    1. Find the new Active Directory in the portal, select Applications, select Add, and then select Add an application my organization is developing.
    2. Enter a name for the app, and then select Web Application.
    3. For Sign-on URL, enter <LMS URI>/auth/complete/azuread-oauth2/. For example, you might enter http://localhost:8000/auth/complete/azuread-oauth2/.
    4. For App ID URL, enter <LMS URI>/sign in. For example, you might enter http://localhost:8000/sign in.
    5. Finish creating the new app.
  7. In the portal, locate your Azure AD application, click Configure, and then locate and make a note of the client ID. For example, the client ID may be fe3c3868-0faa-44ee-a1bf-1110aeab1a65.

  8. In the Keys section, select a two-year duration, and then select Save to create a secret key. Note the value of the key. For example, the key value may be abcdef12341yHlmOrR8D3vlV1cD2VtL7k9xk9DSB8vw=.

  9. In the Permissions to other applications section, locate the Delegated Permissions option for Windows Azure Active Directory, and then select Sign in and read user profile.

  10. Verify the Azure AD domain name. To do this, follow these steps.

    1. In the portal, locate the new Active Directory.
    2. Select Domains, select Add, and then add the root domain you want to use (for example, edx.org). Make sure that you add the root domain first, and then follow the TXT record verification process.
    3. (optional) After the domain has been verified, add subdomains (for example, courses.edx.org). Subdomains also request verification, but do not need it.
  11. In the Active Directory, select Applications, and then select the application that you created.

  12. Enable multi-tenant support.

4.18.3.2.1.1.2. Configure Open edX

Configuring Open edX is very similar for Google, Facebook, LinkedIn, and Azure.

  1. In the lms.env.json file, change the value of FEATURES > ENABLE_THIRD_PARTY_AUTH to true (it is false by default).

  2. If necessary, make sure that the correct backend is specified.

    • If you are using Google, Facebook, LinkedIn, or Active Directory, open the lms.env.json file and look for the THIRD_PARTY_AUTH_BACKENDS list. By default, the file does not contain this list.

      If the lms.env.json file does not contain the THIRD_PARTY_AUTH_BACKENDS list, you do not have to complete any additional steps.

      If the lms.env.json file contains the THIRD_PARTY_AUTH_BACKENDS list, add the backend for the applicable IdP to the list.

      • For Google, add "social.backends.google.GoogleOAuth2".
      • For Facebook, add "social.backends.facebook.FacebookOAuth2".
      • For LinkedIn, add "social.backends.linkedin.LinkedinOAuth2".
      • For Azure Active Directory, add
        "social.backends.azuread.AzureADOAuth2".
    • If you are using a custom backend, add the applicable OAuth2 provider to the THIRD_PARTY_AUTH_BACKENDS list in the lms.env.json file. If the file does not contain the THIRD_PARTY_AUTH_BACKENDS list, create the list, and then add the OAuth2 provider.

    For more information, see the AWS template file file in GitHub.

  3. In the lms.auth.json file, add the client secret. To do this, create the SOCIAL_AUTH_OAUTH_SECRETS key if the key does not already exist, and then add the appropriate value for your IdP.

    Note

    If you are using Ansible, set the EDXAPP_SOCIAL_AUTH_OAUTH_SECRETS variable.

    • For Google, add the following value.

      "SOCIAL_AUTH_OAUTH_SECRETS": { "google-oauth2":
         "abcdef123456789101112131" }
      
    • For Facebook, add the following value.

      "SOCIAL_AUTH_OAUTH_SECRETS": {
         "facebook": "98765432181bbe3a2596efa8ba7abcde"
      }
      
    • For LinkedIn, add the following value.

      "SOCIAL_AUTH_OAUTH_SECRETS": { "linkedin-oauth2": "4D3Cb2aB1C0dEFGH" }
      
    • For Azure, add the following value.

      "SOCIAL_AUTH_OAUTH_SECRETS": { "azuread-oauth2":
          "abcdef12341yHlmOrR8D3vlV1cD2VtL7k9xk9DSB8vw=" }
      
  4. Restart the LMS server so that it will use the new settings.

4.18.3.2.1.1.3. Add the Provider Configuration

  1. Go to <LMS URI>/admin/third_party_auth/oauth2providerconfig/. For example, on devstack, go to http://localhost:8000/admin/third_party_auth/oauth2providerconfig/.

  2. Select Add Provider Configuration (OAuth).

  3. Make sure that Enabled is selected.

  4. For Icon Class, enter the appropriate value.

    • For Google, enter fa-google-plus.
    • For Facebook, enter fa-facebook.
    • For LinkedIn, enter fa-linkedin.
    • For Azure, leave the field blank.
  5. For Name, enter the appropriate value.

    • For Google, enter Google.
    • For Facebook, enter Facebook.
    • For LinkedIn, enter LinkedIn.
    • For Azure, enter Microsoft.
  6. For Backend Name, select the appropriate value.

    • For Google, select google-oauth2.
    • For Facebook, select facebook.
    • For LinkedIn, select linkedin-oauth2.
    • For Azure, select azuread-oauth2.

    Note

    If the value does not appear in the list, either the ENABLE_THIRD_PARTY_AUTH setting or the THIRD_PARTY_AUTH_BACKENDS setting is not configured correctly.

  7. For Client ID, enter the client ID that you noted earlier.

  8. Leave Client Secret blank. Open edX sets the secret through lms.auth.json, which is more secure.

  9. (Optional) If you want Facebook or LinkedIn to provide the user’s email address during registration, enter the following code into Other settings.

    For Facebook, use this code.

    {
        "SCOPE": ["email"],
        "PROFILE_EXTRA_PARAMS": {
            "fields": "id, name, email"
        }
    }
    

    For LinkedIn, use this code.

    { "SCOPE": ["r_basicprofile", "r_emailaddress"], "FIELD_SELECTORS":
     ["email-address"] }
    
  10. Select Save.

Users who have an account with the IdP that you have configured can now sign in.

Note

For Google only, if you see the following error message, the SOCIAL_AUTH_OAUTH_SECRETS setting is not correct.

'unicode' object has no attribute 'get'

To resolve this problem, make sure that this setting does not appear multiple times in the lms.auth.json file.

4.18.3.2.1.2. Additional OAuth2 Providers (Advanced)

You can add any other third party authentication provider that supports the OAuth2 standard to the Open edX platform. To do this, follow these steps.

Note

OAuth1 providers are also supported and can be configured using these same steps. However, OAuth2 is preferred over OAuth1 wherever possible.

  1. In lms.env.json, change the value of FEATURES > ENABLE_THIRD_PARTY_AUTH to true (it is false by default).

  2. Install the python-social-auth authentication backend specific to that provider, and determine the python module path of the backend.

    • If the provider is a python-social-auth supported backend, the backend is already installed.

      To determine the python module path of the backend, locate the backend in the list of python-social-auth backends, open the file for the backend, and locate the name of the class. The python module path is of the format social.backends.<file name>.<class name>.

      For example, for GitHub, the file is github.py and the class in that file is GithubOAuth2. The backend module path is therefore social.backends.github.GithubOAuth2.

    • If the provider is not a python-social-auth supported backend, you must create a new Python package that includes the code required to implement the backend. Your python package must contain a module with a class that subclasses social.backends.oauth.BaseOAuth2. For more information, see the python-social-auth documentation, or see the code of the fully supported backends (such as Google or Facebook) for examples.

  3. Enable the python-social-auth authentication backend specific to that provider:

    1. In the THIRD_PARTY_AUTH_BACKENDS setting in lms.env.json, add the full path of the module to the list.
    2. (optional) Set the value of THIRD_PARTY_AUTH_BACKENDS to match the default value in the aws.py file, and then add any additional backends you need.
  4. Obtain a client ID and client secret from the provider.

  5. Add the client secret to lms.auth.json. To do this, create a new key called SOCIAL_AUTH_OAUTH_SECRETS if it doesn’t already exist, and then add the backend name to that key as follows.

    "SOCIAL_AUTH_OAUTH_SECRETS": { "backend-name": "secret" }
    

    If you are using Ansible, the variable to set is called EDXAPP_SOCIAL_AUTH_OAUTH_SECRETS.

  6. Restart the LMS server so that it will use the new settings.

  7. Go to <LMS URI>/admin/third_party_auth/oauth2providerconfig/. For example, on devstack, go to http://localhost:8000/admin/third_party_auth/oauth2providerconfig/.

  8. Select Add Provider Configuration (OAuth).

  9. Make sure that Enabled is selected.

  10. For Icon Class, select one of the following options.

    • Use a generic icon by entering fa-sign-in.
    • Use a relevant Font Awesome icon.
    • Upload an SVG icon using the Icon Image field.
  11. For Name, enter the name of the provider.

  12. For Backend Name, select the backend name from the list. (If it does not appear in the list, either the ENABLE_THIRD_PARTY_AUTH setting or the THIRD_PARTY_AUTH_BACKENDS setting is not configured correctly.)

  13. For Client ID, enter the client ID that you noted earlier.

  14. Leave Client Secret blank. Open edX sets the secret through lms.auth.json, which is more secure.

  15. Select Save.

Users can now sign in using this OAuth2 provider.