The OAuth 2 plugin allows users to login using an existing account for another service, for example using an existing Microsoft, Google, or Facebook account.
You will need to enable and configure OAuth 2 in two places on Totara (both accessed from the Site administration menu):
Additionally services will need to be set-up and configured on that services site (for example in the Google developer console).
The screenshot above shows a Totara Learn login box with a number of OAuth2 service enabled including Google, Facebook, and Microsoft accounts.
Before you can use OAuth 2 as an authentication method it will need to be enabled (as instructed on the Authentication page).
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 they can be incorrectly logged in. To avoid issues with OAuth 2 logins it is recommended that you ensure the Allow accounts with same email settings is disabled under the list of Common settings on the Plugins > Authentication > Manage authentication page.
By clicking on Settings alongside the OAuth 2 authentication method or by going to Plugins > Authentication > OAuth 2 you can configure whether certain user data fields should be locked.
This is useful for sites where the user data is maintained by the administrators, either by manually editing user records or uploading 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.
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 services developer console, creating a new app, and then copying the ID and secret. Instructions for some specific services can be found below.
Once you have set up the services in Totara Learn do the following:
|Name||The name of the issuer service (e.g. Google, Facebook, etc.) this may be displayed on the login page.||-|
|Client ID||The unique ID provided by the issuer.||-|
|Client secret||A unique password or secret generated by the issuer.||-|
|Authenticate token requests via HTTP headers||Utilise the HTTP basic authentication scheme when sending client ID and password with a refresh token request. Recommended by the OAuth 2 standard, but may not be available with some issuers.||-|
|Scopes included in a login request||Some systems require additional scopes for a login request in order to read the user's basic profile. The standard scopes for an OpenID Connect compliant system are "openid profile email".||-|
|Scopes included in a login request for offline access||Each OAuth system defines a different way to request offline access. E.g. Microsoft requires an additional scope "offline_access".||-|
|Additional parameters included in a login request||Some systems require additional parameters for a login request in order to read the user's basic profile.|
|Additional parameters included in a login request for offline access||Each OAuth system defines a different way to request offline access. E.g. Google requires the additional parameters: "access_type=offline&prompt=consent". These parameters should be in URL query parameter format.||-|
|Service base URL||Base URL used to access the service.||-|
If set, this setting is a comma separated list of domains that logins will be restricted to when using this provider.
|Logo URL||This is usually the logo used by the issuer, and it may be displayed on the login page.||-|
|Show on login page||If the OAuth 2 authentication plugin is enabled, this login issuer will be listed on the login page to allow users to log in with accounts from this issuer.||-|
|Require email verification||Require that all users verify their email address before they can log in with OAuth. This applies to newly created accounts as part of the login process, or when an existing Totara account is connected to an OAuth login via matching email addresses.||-|
After a service has been set up you can edit it via the Edit column from Server > OAuth 2 services via the Administration menu.
Configure endpoints () allows you to edit, delete, or add endpoint URLs
The issuer's endpoints are the URLs which Totara connects to. There are three endpoints required for user authentication: authorization_endpoint, token_endpoint and userinfo_endpoint. For Google, Microsoft, Facebook, Nextcloud services you will not need to configure these endpoints, as these will be URLs for the OAuth provider. For example, an endpoint for Google would be . For custom services you will need to add the endpoints.
When configuring the endpoints for a service you can add more endpoints by clicking Create new endpoint for issuer "IssuerName", then add the endpoint name and URL.
The open eye icon () means a service is enabled, therefore clicking it disables the service. Whereas a closed eye icon () means the service is disabled, therefore clicking it enables the service.
If you wish to enable Microsoft account login then you will need to enable the OAuth 2 plugin on your Totara site and go to the Microsoft developer console to configure authentication.
You can see more instructions from Microsoft on their website.
If you wish to enable Google account login then you will need to enable the OAuth 2 plugin on your Totara site and go to the Google developer console to configure authentication.
You can see more about Google and OAuth 2 on their website.
If you wish to enable Facebook login then you will need to enable the OAuth 2 plugin on your Totara site and also go to the Facebook developer portal to configure authentication via their login system. The basic process is:
You can find details on how to configure Facebook login in their help documentation.