- 10 Jun 2024
- 5 minutes to read
Configure OAuth 2
- Updated on 10 Jun 2024
- 5 minutes to read
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):
- Go to Quick-access menu > Plugins > Authentication > Manage authentication.
- Click the eye icon () alongside OAuth 2 to enable it (the eye will be open once the authentication method is enabled).
- Navigate to Quick-access menu > Server > OAuth 2 services.
- Configure the service you want to use (see 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).
Currently OAuth 2 identification is based on the user's email address. This means that when two users in the system have the same email address they can be logged in as the incorrect user. To avoid issues with OAuth 2 logins, 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.
- Go to Quick-access menu > Plugins > Authentication > OAuth 2.
- Configure the settings as required.
- 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:
- Go to Quick-access menu > Server > OAuth 2 services.
- Select Create a new service, choosing the relevant option for the service you are setting up.
- Configure the settings.
- Click Save changes.
Login via Microsoft account
If you wish to enable Microsoft account login then you will need to enable the OAuth 2 plugin on your Totara site, then go to the Microsoft Azure portal to configure authentication.
- Go to the Microsoft Azure portal.
- Click New registration under App registrations.
- Give your app a name, e.g. 'Totara'.
- Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) for Supported account types.
- Choose Web for Redirect URI.
- Add your site's URL appended with /admin/oauth2callback.php to the Redirect URLs section, e.g. https://totaralearn.com/admin/oauth2callback.php.
- Click Register.
- Take a note of the Application (client) ID.
- Select Authentication from the side menu.
- Ensure that the Implicit grant settings are disabled.
- Select API permissions from the side menu.
- Ensure that the User.Read permission is available under Microsoft Graph (1), and if it is not then add it now.
- Select Certificates & secrets from the side menu and click New client secret.
- Add a description, e.g. your app name (Totara), and select when the password/secret will expire.
- Copy the generated secret string value for use in Totara.
- In Totara go to Server > OAuth 2 services from the quick-access menu.
- Click Create a new Microsoft service.
- Enter the password generated in the Microsoft Azure portal as the Secret and the application ID as the Client ID.
- Click Save changes.
You can see more instructions from 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.
- Go to the Google developer console.
- Create a new project using either the Select a project dropdown at the top or the Create button.
- Give the project a name, e.g. 'Totara login'.
- Click Create.
- Go to Credentials from the left-hand menu.
- Select the OAuth consent screen section and complete the settings.
- Click Save.
- Select the Credentials tab, then choose OAuth client ID from the Create credentials dropdown.
- 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
- Click Create.
- Take a note of the client ID and secret generated.
- In Totara, go to Quick-access menu > Server > OAuth 2 services.
- Click Create a new Google service.
- Enter the Secret and Client ID given in the Google developer console.
- Click Save changes.
You can see more about Google and OAuth 2 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 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:
- Create a report using the Linked logins report source.
- Save and view the new report.
- 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.
- 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.
© Copyright 2024 Totara Learning Solutions. All rights reserved.