---
title: "Configure OAuth 2"
slug: "configure-oauth2"
tags: ["Explainer", "How-to", "Site Administrator", "Totara Platform"]
updated: 2026-04-28T13:31:55Z
published: 2026-04-28T13:31:55Z
canonical: "totara.help/configure-oauth2"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://totara.help/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure OAuth 2
The OAuth 2 plugin allows users to log in using an existing account for another service, such as a Microsoft, Google, or Facebook account.
## Enable authentication method
You will need to enable and configure OAuth 2 in two places on Totara (in both the **Manage authentication** and **Server** sections):
1. Go to *Quick-access menu > Plugins > Authentication > Manage authentication*.
2. Click the eye icon ( ) alongside **OAuth 2** to enable it (the eye will be open once the authentication method is enabled).
3. Navigate to *Quick-access menu > Server > OAuth 2 services*.
4. Configure the service you want to use (see [Create new OAuth 2 service](/19/docs/configure-oauth2#create-new-oauth-2-service) below).
Additionally, services will need to be set up and configured on that service's site (for example in the Google developer console).
OAuth 2 identification uses the OIDC 'sub' claim to uniquely identify users after their initial login. For the first login, the user's email address is used to match them with an existing account. This means that if a user's email address changes in the external service, it will be automatically updated in Totara when they next log in. However, to avoid potential issues during initial account matching when two users in the system have the same email address, it is recommended that you ensure the Allow accounts with same email setting is disabled under the list of Common settings on the Quick-access > Plugins > Authentication > Manage authentication page.
## **Creating and linking accounts**
Once OAuth 2 authentication has been enabled you can configure how accounts are created and managed.
1. Go to *Quick-access menu > Plugins > Authentication > OAuth 2*.
2. Configure the [settings](/19/docs/oauth2-settings) as required.
3. Click **Save changes** when you are done.
As well as behavioural settings, you can also configure whether certain user data fields should be locked. This is useful for sites where the user data is maintained by the Site Administrators, either by manually editing user records or uploading data using the **Upload users** facility. If you are locking fields that are required by Totara, make sure that you provide that data when creating user accounts, or the accounts will be unusable. Consider setting the lock mode to **Unlocked if empty** to avoid this problem.
Each user field can be set to either **Unlocked**, **Unlocked if empty**, or **Locked**. Remember to click **Save changes** when you are done.
## Create new OAuth 2 service
Once you have enabled the OAuth 2 authentication method, you can now set up services to use as a login method. First of all you will need to go to that service and set up authentication on that end. This usually works by going to that service's developer console, creating a new app, and then copying the ID and secret. Instructions for some commonly used services can be found below.
Once you have set up the services in Totara, follow these steps:
1. Go to *Quick-access menu > Server > OAuth 2 services*.
2. Select **Create a new service**, choosing the relevant option for the service you are setting up.
3. Configure the [settings](/19/docs/oauth2-settings).
4. Click **Save changes**.
## **Login via Microsoft account**
> [!WARNING]
> Note: Microsoft recommends **single-tenant configurations** for organisations. Single-tenant setups provide greater control over identity management, policy enforcement, and data isolation, reducing the risk of data exposure across tenants.
1. Go to the [Microsoft Azure portal.](https://azure.microsoft.com/account/)
2. Go to **Microsoft Entra ID.**
3. On the Overview pane, note the **Tenant ID.**
4. Click **New registration** under *Manage > App registrations.*
5. Give your app a name, e.g. 'Totara'.
6. Select either **Accounts in this organizational directory only ([TENANTNAME] only - Single tenant)** (recommended) or **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** for Supported account types.
7. Choose **Web** for Redirect URI.
8. Add your site's URL appended with **/admin/oauth2callback.php** to the **Redirect URLs** section, e.g. [https://totaralearn.com/admin/oauth2callback.php](https://totaralearn.com/admin/oauth2callback.php).
9. Click **Register.**
10. Take a note of the **Application (client) ID.**
11. Select **Authentication** from the side menu.
12. Ensure that the **Implicit grant** settings are **disabled**.
13. Select **API permissions** from the side menu.
14. Ensure that the **User.Read** permission is available under **Microsoft Graph (1)**, and if it is not then add it now.
15. Select **Certificates & secrets** from the side menu and click **New client secret**.
16. Add a description, e.g. your app name (Totara), and select when the password/secret will expire.
17. Copy the generated secret string value for use in Totara.
18. In Totara go to the *Quick-access menu > Server > OAuth 2 consumer details.*
19. Click **Create a new Microsoft service**.
20. Enter the password generated in the Microsoft Azure portal as the **Secret** and the application ID as the **Client ID**.
21. Click **Save changes**.
22. If using a single tenanted Entra configuration (recommended), do the following:
1. Click Configure endpoints for the Microsoft service you've created
2. Edit the **authorization_endpoint** value to be `https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize` where TENANT_ID is the Entra Tenant ID noted earlier
3. Edit the **token_endpoint** value to be `https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token` where TENANT_ID is the Entra Tenant ID noted earlier
You can see more [instructions from Microsoft](https://docs.microsoft.com/en-us/azure/app-service/configure-authentication-provider-microsoft) on their website.
## **Login via Google account**
If you wish to enable Google account login then you will need to enable the OAuth 2 plugin on your Totara site, then go to the Google developer console to configure authentication.
1. Go to the [Google developer console](https://console.developers.google.com/).
2. Create a new project using either the **Select a project** dropdown at the top or the **Create** button.
3. Give the project a name, e.g. 'Totara login'.
4. Click **Create**.
5. Go to **Credentials** from the left-hand menu.
6. Select the **OAuth consent screen** section and complete the settings.
7. Click **Save**.
8. Select the **Credentials** tab, then choose **OAuth client ID** from the **Create credentials** dropdown.
9. Choose the **Web application** option and set the **Authorized redirect URIs** as your site's URL appended with **/admin/oauth2callback.php**, e.g. **https://totaralearn.com/admin/oauth2callback.php**
10. Click **Create**.
11. Take a note of the client ID and secret generated.
12. In Totara, go to *Quick-access menu > Server > OAuth 2 services*.
13. Click **Create a new Google service**.
14. Enter the **Secret** and **Client ID** given in the Google developer console.
15. Click **Save changes**.
You can see more about [Google and OAuth 2](https://developers.google.com/identity/protocols/OAuth2) on their website.
## **Login via Facebook**
If you wish to enable Facebook login then you will need to enable the OAuth 2 plugin on your Totara site, then go to the Facebook developer portal to configure authentication via their login system. The basic process is:
- Create a Facebook app via Facebook for Developers. This will need to have a Display name and Contact email.
- In the Product, select FacebookLogin.
- Choose the Web option and configure the settings.
- Make a note of the App ID and App Secret.
- In Totara, go to Quick-access menu > Server > OAuth 2 services.
- Click Create a new Facebook service.
- Enter the Secret (the App Secret) and Client ID (the AppID) given in Facebook.
- Click Save changes.
You can find details on how to configure [Facebook login](https://developers.facebook.com/docs/facebook-login/web) in their help documentation.
## **Troubleshooting: Linked OAuth 2 logins for deleted user accounts**
If a user with a linked OAuth 2 login is deleted from your site, they may have issues if they later create a new account and attempt to use OAuth 2 for authentication. If this occurs, follow these steps to remove the linked login:
1. Create a report using the **Linked logins** report source.
2. Save and view the new report.
3. Set the **User status** filter to **Deleted**. The report will now display all of the deleted users who have a linked login for OAuth 2.0.
4. In the **Actions** column, click the cross icon ( ) next to the user's account to remove the linked login for this account.
The user can then link OAuth 2 with their active account.
Only use this method to delete linked logins for deleted accounts when you know there is an issue. Removing linked logins for active accounts may result in access issues.
Join the [Totara Community](https://totara.community/) for more resources to help you get the most out of Totara.
© Copyright 2026 Totara Learning Solutions. All rights reserved.