Integrating with an OAuth2 Identity Provider

CoLab
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).

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.

Register the Open edX Instance

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.

  1. Go to the Azure sign in page.
  2. Click New, locate Active Directory, and then select Create.
  3. Enter a name, domain name, and country.
  4. Create a new application.
  5. Find the new Active Directory in the portal, select Applications, select Add, and then select Add an application my organization is developing.
  6. Enter a name for the app, and then select Web Application.
  7. For Sign-on URL, enter <LMS URI>/auth/complete/azuread-oauth2/. For example, you might enter http://localhost:8000/auth/complete/azuread-oauth2/.
  8. For App ID URL, enter <LMS URI>/sign in. For example, you might enter http://localhost:8000/sign in.
  9. Finish creating the new app.
  10. 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.
  11. 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=.
  12. 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.
  13. Verify the Azure AD domain name. To do this, follow these steps.
  14. In the portal, locate the new Active Directory.
  15. 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.
  16. (optional) After the domain has been verified, add subdomains (for example, courses.edx.org). Subdomains also request verification, but do not need it.
  17. In the Active Directory, select Applications, and then select the application that you created.
  18. Enable multi-tenant support.

Configure Open edX

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

  1. In the lms.yml 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.yml file and look for the THIRD_PARTY_AUTH_BACKENDS list. By default, the file does not contain this list.If the lms.yml file does not contain the THIRD_PARTY_AUTH_BACKENDS list, you do not have to complete any additional steps.If the lms.yml file contains the THIRD_PARTY_AUTH_BACKENDS list, add the backend for the applicable IdP to the list.
  • For Google, add "social_core.backends.google.GoogleOAuth2".
    • For Facebook, add "social_core.backends.facebook.FacebookOAuth2".
    • For LinkedIn, add "social_core.backends.linkedin.LinkedinOAuth2".
    • For Azure Active Directory, add

"social_core.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.yml` 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](https://github.com/openedx/edx-platform/blob/b3462e5b1c3cc45ad8673f3f12e84fa17ffa6b64/lms/envs/aws.py#L586-L596) file in GitHub.
3. In the `lms.yml` 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=" }
  1. Restart the LMS server so that it will use the new settings.