Edit OAuth 2
- 04 Aug 2023
- 2 minutes to read
Edit OAuth 2
- Updated on 04 Aug 2023
- 2 minutes to read
Article Summary
Share feedback
Thanks for sharing your feedback!
After an OAuth 2 service has been set up, you can edit it to make changes as required.
Editing the settings
- Go to Quick-access menu > Server > OAuth 2 services.
- Click the cog icon (
) in the Edit column. - Make your changes to the settings.
- Click Save changes.
) in the Edit column.Configure endpoints
- Go to Quick-access menu > Server > OAuth 2 services.
- Click the list icon (
) in the Edit column. - Click the cog icon () to edit the endpoint Name or URL.
- Click Save changes.
) in the Edit column.You can also delete an endpoint by clicking the cross icon (
), or add a new endpoint by clicking Create new endpoint for issuer "[issuer name]".
The issuer's endpoints are the URLs which Totara connects to. There are three endpoints required for user authentication:
- authorization_endpoint
- token_endpoint
- userinfo_endpoint
For Google, Microsoft, Facebook, and 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 https://accounts.google.com/o/oauth2/v2/auth. For custom services you will need to add the endpoints.
Configure user field mappings
You can edit, delete, or create mappings between user data fields on the issue site and your Totara site to ensure the correct information is brought across.
To configure user field mappings, follow these steps:
- Go to Quick-access menu > Server > OAuth 2 services.
- Click the person icon (
) in the Edit column. - Click the cog icon () to edit the External field name and Internal field name fields.
- Click Save changes.
) in the Edit column.You can also delete a user field with the cross icon (), or add a new user field mapping by clicking Create new user field mapping for issuer "[issuer name]".
When configuring field mappings, the External field name uses the hyphen character (-) as a separator for nested object fields. For example, the name country-region will look up the region field of a country object in the response data from an OAuth 2 userinfo request.
If your userinfo data contains any hyphens in the field names then you will need to escape them using a backslash character (\) in the External field name field in Totara. For example, if you set the External field name to country-region Totara will try to find the field country-region in the userinfo response data. Therefore you should set the External field name to country\-region to ensure that the field name is interpreted correctly.
When configuring OAuth 2 with Microsoft Azure AD, only certain fields will be available to map by default.
If you want Microsoft to provide additional fields, you will need to configure Totara to request them by editing the userinfo_endpoint URL of the Microsoft API connection. For example, if you wanted to map the department field in addition to the default fields, you would change the URL from:
https://graph.microsoft.com/v1.0/me
to
https://graph.microsoft.com/v1.0/me?$select=businessPhones,displayName,givenName,id,jobTitle,mail,mobilePhone,officeLocation,preferredLanguage,surname,userPrincipalName,department
Note that if you are adding fields in this way, you also need to list all of the default fields in the URL.
You can use Microsoft's Graph Explorer tool to confirm what data is available (i.e. the exact field names) and amend the URL accordingly.
If you want Microsoft to provide additional fields, you will need to configure Totara to request them by editing the userinfo_endpoint URL of the Microsoft API connection. For example, if you wanted to map the department field in addition to the default fields, you would change the URL from:
https://graph.microsoft.com/v1.0/me
to
https://graph.microsoft.com/v1.0/me?$select=businessPhones,displayName,givenName,id,jobTitle,mail,mobilePhone,officeLocation,preferredLanguage,surname,userPrincipalName,department
Note that if you are adding fields in this way, you also need to list all of the default fields in the URL.
You can use Microsoft's Graph Explorer tool to confirm what data is available (i.e. the exact field names) and amend the URL accordingly.
© Copyright 2024 Totara Learning Solutions. All rights reserved.
Was this article helpful?
