OAuth 2 services: Difference between revisions
From MoodleDocs
Helen Foster (talk | contribs) |
(Update to 4.1) |
||
| Line 1: | Line 1: | ||
{{Server settings}} | {{Server settings}} | ||
==OAuth2 services== | ==OAuth2 services== | ||
* Moodle supports OAuth 2 services (or "Issuers"), which can be used by any plugin to provide authenticated access to external services either as the current user, or using a system account. | |||
* Moodle | |||
* OAuth 2 services are used for example, to provide a "Log in using Google/Microsoft/Facebook" feature on the login page, and then to share that authenticated session with repositories like [[Google Drive repository|Google Drive]] and [[OneDrive repository|OneDrive]] without having to re-authenticate. | * OAuth 2 services are used for example, to provide a "Log in using Google/Microsoft/Facebook" feature on the login page, and then to share that authenticated session with repositories like [[Google Drive repository|Google Drive]] and [[OneDrive repository|OneDrive]] without having to re-authenticate. | ||
* OAuth 2 services can be used by plugins even if they do not use them on the login page, and it's possible to login to multiple services at the same time. | * OAuth 2 services can be used by plugins even if they do not use them on the login page, and it's possible to login to multiple services at the same time. | ||
== Login == | == Login == | ||
See [[OAuth 2 authentication]] for details of how to enable the feature. | See [[OAuth 2 authentication]] for details of how to enable the feature. | ||
== Open ID Connect == | == Open ID Connect == | ||
Open ID Connect is a standard for OAuth 2 login services that makes it easier to setup a working login system. If the service you are setting up is Open ID Connect compliant, you will only have to enter the base url for the service, and Moodle will discover all the other information required by requesting the "discovery document" which is expected to exist at <issuer base url>/.well-known/openid-configuration. | Open ID Connect is a standard for OAuth 2 login services that makes it easier to setup a working login system. If the service you are setting up is Open ID Connect compliant, you will only have to enter the base url for the service, and Moodle will discover all the other information required by requesting the "discovery document" which is expected to exist at <issuer base url>/.well-known/openid-configuration. | ||
== Issuer Configuration == | == Issuer Configuration == | ||
First some terminology: In these scenarios, Moodle is the "client" and the remote service (Google, Facebook, ...) is the "issuer" or "provider". | First some terminology: In these scenarios, Moodle is the "client" and the remote service (Google, Facebook, ...) is the "issuer" or "provider". | ||
To configure OAuth 2 services, go to '''Site administration > Server > Server > OAuth 2 services'''. | |||
[[File:OAuth - Services.png|border|center|frameless|900x900px]] | |||
=== How do I get a client ID and secret? === | === How do I get a client ID and secret? === | ||
The client ID and secret are provided by the issuer, so you need to set it up outside of Moodle, at the issuer. Instructions for prominent OAuth 2 providers are linked here. | The client ID and secret are provided by the issuer, so you need to set it up outside of Moodle, at the issuer. Instructions for prominent OAuth 2 providers are linked here. | ||
* [[OAuth 2 Google service]] | * [[OAuth 2 Google service]] | ||
* [[OAuth 2 Microsoft service]] | * [[OAuth 2 Microsoft service]] | ||
* [[OAuth 2 Facebook service]] | * [[OAuth 2 Facebook service]] | ||
* [[OAuth 2 Nextcloud service]] | * [[OAuth 2 Nextcloud service]] | ||
* [[OAuth 2 Open Badges service]] | * [[OAuth 2 Open Badges service]] | ||
* [[OAuth 2 LinkedIn service]] | |||
* [[OAuth 2 Clever service]] | |||
For custom services you will need to find out how to obtain the client ID and secret. The issuer will need configuring with the corresponding redirect URL for Moodle which is '''<wwwroot>/admin/oauth2callback.php''', e.g. if your Moodle site is https://moodle.example.com, then the redirect URL is https://moodle.example.com/admin/oauth2callback.php. | For custom services you will need to find out how to obtain the client ID and secret. The issuer will need configuring with the corresponding redirect URL for Moodle which is '''<wwwroot>/admin/oauth2callback.php''', e.g. if your Moodle site is https://moodle.example.com, then the redirect URL is https://moodle.example.com/admin/oauth2callback.php. | ||
=== Adding an issuer === | === Adding an issuer === | ||
If possible, use one of the preconfigured services if yours is among it. You can still configure individual details later on. | If possible, use one of the preconfigured services if yours is among it. You can still configure individual details later on. | ||
Choose from the list, then the following settings appear: | Choose from the list, then the following settings appear: | ||
[[Image:OAuth2-issuer-settings.png|frame|center|Issuer settings]] | |||
As a general rule, don't change any settings, except for '''Name''', '''Client ID''', '''Client Secret''', and '''Service Base URL''', unless installation instructions advise you to. Apart from that the defaults are usually fine, especially if you use one of the preconfigured services. | |||
As a general rule, don't change any settings, except for '''Name''', '''Client ID''', '''Client Secret''', and '''Service Base URL''', unless installation instructions advise you to. Apart from that the defaults are usually fine, especially if you use one of the preconfigured services. | |||
See [[#Advanced_issuer_settings|Advanced issuer settings (below)]] for explanations of some of the settings. | See [[#Advanced_issuer_settings|Advanced issuer settings (below)]] for explanations of some of the settings. | ||
====Login domains==== | ====Login domains==== | ||
This setting only applies if "Show on login page" is checked. If specified, only users with matching emails will be able to sign-up and log in using this service. | This setting only applies if "Show on login page" is checked. If specified, only users with matching emails will be able to sign-up and log in using this service. | ||
This restriction will apply on top of the allowed and denied email domains settings in [[Managing_authentication|Manage authentication]], however the latter are only checked when a user is created and are not checked again when the user logs in. | This restriction will apply on top of the allowed and denied email domains settings in [[Managing_authentication|Manage authentication]], however the latter are only checked when a user is created and are not checked again when the user logs in. | ||
====Further configuration options==== | ====Further configuration options==== | ||
After an issuer has been created, further configuration options are shown to the right of the service. Usually no change is required for preconfigured services. | After an issuer has been created, further configuration options are shown to the right of the service. Usually no change is required for preconfigured services. | ||
[[Image:OAuth2-issuer-other-settings.png|frame|center|Further configuration options for OAuth 2 issuers]] | |||
; Edit : Go to the settings screen again. | ; Edit : Go to the settings screen again. | ||
; Configure endpoints : Define the issuer's endpoints, i.e. the URLs that Moodle will connect to. The following endpoints are mandatory for user authentication: '''authorization_endpoint''', '''token_endpoint''' and '''userinfo_endpoint'''. (Example image below). | ; Configure endpoints : Define the issuer's endpoints, i.e. the URLs that Moodle will connect to. The following endpoints are mandatory for user authentication: '''authorization_endpoint''', '''token_endpoint''' and '''userinfo_endpoint'''. (Example image below). | ||
| Line 60: | Line 45: | ||
; Disable : Mark the issuer as disabled; plugins may not use them. | ; Disable : Mark the issuer as disabled; plugins may not use them. | ||
; Move up / down : Change the order of appearance in the issuer table. | ; Move up / down : Change the order of appearance in the issuer table. | ||
[[File:endpoints.png|frame|center|Example endpoints for a custom service]][[File:user_field_mappings.png|frame|center|Example user field mappings]] | [[File:endpoints.png|frame|center|Example endpoints for a custom service]][[File:user_field_mappings.png|frame|center|Example user field mappings]] | ||
=== Connecting a system account === | === Connecting a system account === | ||
A system account may be connected. It may be needed by plugins in order to provide advanced functionality, such as access controlled links from the [[Nextcloud repository]], [[Google Drive repository]] or [[OneDrive repository]]. | A system account may be connected. It may be needed by plugins in order to provide advanced functionality, such as access controlled links from the [[Nextcloud repository]], [[Google Drive repository]] or [[OneDrive repository]]. | ||
[[File:connecting a system account.png|frame|center|Connecting a system account]] | [[File:connecting a system account.png|frame|center|Connecting a system account]] | ||
To connect to a system account, click the Connect icon (half open box with arrow), then select the appropriate account. | To connect to a system account, click the Connect icon (half open box with arrow), then select the appropriate account. | ||
The system account should be a dedicated account for this purpose only. The system account doesn't require an email address to be associated with it. A system account is not needed for login functionality. | The system account should be a dedicated account for this purpose only. The system account doesn't require an email address to be associated with it. A system account is not needed for login functionality. | ||
[[File:errorsNotification.png|thumb|right|Notification preferences page]] | [[File:errorsNotification.png|thumb|right|Notification preferences page]] | ||
==== Refreshing Access Token ==== | ==== Refreshing Access Token ==== | ||
There is a scheduled task to regularly update the OAuth token for service accounts, ''Refresh OAuth tokens for service accounts'' (''\core\oauth2\refresh_system_tokens_task''). If for any reason the token cannot be refreshed, e.g. if the authorization expires, all Moodle administrators will be notified. | There is a scheduled task to regularly update the OAuth token for service accounts, ''Refresh OAuth tokens for service accounts'' (''\core\oauth2\refresh_system_tokens_task''). If for any reason the token cannot be refreshed, e.g. if the authorization expires, all Moodle administrators will be notified. | ||
| Line 82: | Line 60: | ||
'''Caution''': A user who turns off the ''Important errors with the site'' notification may not receive other important information related to site errors. For example, the user will not receive e-mails about the results of the antivirus scan or any notification sent from a third-party plugin that uses the core message provider ''errors''. | '''Caution''': A user who turns off the ''Important errors with the site'' notification may not receive other important information related to site errors. For example, the user will not receive e-mails about the results of the antivirus scan or any notification sent from a third-party plugin that uses the core message provider ''errors''. | ||
Currently there are not many notifications sent using this message provider; unfortunately, there is no way to list them, so it is recommended to check the notifications that were received before and those that are received after deactivating the notification. | Currently there are not many notifications sent using this message provider; unfortunately, there is no way to list them, so it is recommended to check the notifications that were received before and those that are received after deactivating the notification. | ||
=== Advanced issuer settings === | === Advanced issuer settings === | ||
; Authenticate token requests via HTTP headers : This should be the norm according to the OAuth 2 standard. However, most providers don't support this and require authentication details in the body instead. For most configurations, leave this checkbox disabled, unless instructions advise you to check it. | ; Authenticate token requests via HTTP headers : This should be the norm according to the OAuth 2 standard. However, most providers don't support this and require authentication details in the body instead. For most configurations, leave this checkbox disabled, unless instructions advise you to check it. | ||
==See also== | ==See also== | ||
* [[OAuth 2 authentication]] | |||
* [[ | * [[OAuth 2 Troubleshooting]] | ||
* [https://moodle.org/mod/forum/discuss.php?d=351727 Oauth2 problems in Moodle 3.3] forum discussion | * [https://moodle.org/mod/forum/discuss.php?d=351727 Oauth2 problems in Moodle 3.3] forum discussion | ||
* [https://moodle.org/mod/forum/discuss.php?d=362593 Problem to configure Oauth2 with Microsoft Office365] forum discussion | * [https://moodle.org/mod/forum/discuss.php?d=362593 Problem to configure Oauth2 with Microsoft Office365] forum discussion | ||
[[Category:OAuth 2]] | [[Category:OAuth 2]] | ||
[[es:Servicios OAuth 2]] | [[es:Servicios OAuth 2]] | ||
[[de:OAuth2 Services]] | [[de:OAuth2 Services]] | ||
Revision as of 11:21, 6 December 2022
OAuth2 services
- Moodle supports OAuth 2 services (or "Issuers"), which can be used by any plugin to provide authenticated access to external services either as the current user, or using a system account.
- OAuth 2 services are used for example, to provide a "Log in using Google/Microsoft/Facebook" feature on the login page, and then to share that authenticated session with repositories like Google Drive and OneDrive without having to re-authenticate.
- OAuth 2 services can be used by plugins even if they do not use them on the login page, and it's possible to login to multiple services at the same time.
Login
See OAuth 2 authentication for details of how to enable the feature.
Open ID Connect
Open ID Connect is a standard for OAuth 2 login services that makes it easier to setup a working login system. If the service you are setting up is Open ID Connect compliant, you will only have to enter the base url for the service, and Moodle will discover all the other information required by requesting the "discovery document" which is expected to exist at <issuer base url>/.well-known/openid-configuration.
Issuer Configuration
First some terminology: In these scenarios, Moodle is the "client" and the remote service (Google, Facebook, ...) is the "issuer" or "provider". To configure OAuth 2 services, go to Site administration > Server > Server > OAuth 2 services.
How do I get a client ID and secret?
The client ID and secret are provided by the issuer, so you need to set it up outside of Moodle, at the issuer. Instructions for prominent OAuth 2 providers are linked here.
- OAuth 2 Google service
- OAuth 2 Microsoft service
- OAuth 2 Facebook service
- OAuth 2 Nextcloud service
- OAuth 2 Open Badges service
- OAuth 2 LinkedIn service
- OAuth 2 Clever service
For custom services you will need to find out how to obtain the client ID and secret. The issuer will need configuring with the corresponding redirect URL for Moodle which is <wwwroot>/admin/oauth2callback.php, e.g. if your Moodle site is https://moodle.example.com, then the redirect URL is https://moodle.example.com/admin/oauth2callback.php.
Adding an issuer
If possible, use one of the preconfigured services if yours is among it. You can still configure individual details later on.
Choose from the list, then the following settings appear:
Issuer settings
As a general rule, don't change any settings, except for Name, Client ID, Client Secret, and Service Base URL, unless installation instructions advise you to. Apart from that the defaults are usually fine, especially if you use one of the preconfigured services. See Advanced issuer settings (below) for explanations of some of the settings.
Login domains
This setting only applies if "Show on login page" is checked. If specified, only users with matching emails will be able to sign-up and log in using this service.
This restriction will apply on top of the allowed and denied email domains settings in Manage authentication, however the latter are only checked when a user is created and are not checked again when the user logs in.
Further configuration options
After an issuer has been created, further configuration options are shown to the right of the service. Usually no change is required for preconfigured services.
Further configuration options for OAuth 2 issuers
- Edit
- Go to the settings screen again.
- Configure endpoints
- Define the issuer's endpoints, i.e. the URLs that Moodle will connect to. The following endpoints are mandatory for user authentication: authorization_endpoint, token_endpoint and userinfo_endpoint. (Example image below).
- Configure user field mappings
- If you use the issuer as an identity provider, you can configure how the provider's response (from the userinfo_endpoint) should be mapped to Moodle user fields. You should set up mappings for internal field names firstname, lastname and email so that the user is fully set up when they log in as these fields are mandatory in Moodle. If any of these are not mapped the user will be redirected to their Edit profile page and prompted for the missing information. (Example image below).
- Delete
- Delete the issuer configuration.
- Disable
- Mark the issuer as disabled; plugins may not use them.
- Move up / down
- Change the order of appearance in the issuer table.
Example endpoints for a custom service
Example user field mappings
Connecting a system account
A system account may be connected. It may be needed by plugins in order to provide advanced functionality, such as access controlled links from the Nextcloud repository, Google Drive repository or OneDrive repository.
Connecting a system account
To connect to a system account, click the Connect icon (half open box with arrow), then select the appropriate account.
The system account should be a dedicated account for this purpose only. The system account doesn't require an email address to be associated with it. A system account is not needed for login functionality.
Refreshing Access Token
There is a scheduled task to regularly update the OAuth token for service accounts, Refresh OAuth tokens for service accounts (\core\oauth2\refresh_system_tokens_task). If for any reason the token cannot be refreshed, e.g. if the authorization expires, all Moodle administrators will be notified.
If an admin user does not wish to receive these notifications, it can be set up on the Notification preferences page. The notification option to deactivate is Important errors with the site.
Caution: A user who turns off the Important errors with the site notification may not receive other important information related to site errors. For example, the user will not receive e-mails about the results of the antivirus scan or any notification sent from a third-party plugin that uses the core message provider errors. Currently there are not many notifications sent using this message provider; unfortunately, there is no way to list them, so it is recommended to check the notifications that were received before and those that are received after deactivating the notification.
Advanced issuer settings
- Authenticate token requests via HTTP headers
- This should be the norm according to the OAuth 2 standard. However, most providers don't support this and require authentication details in the body instead. For most configurations, leave this checkbox disabled, unless instructions advise you to check it.
See also
- OAuth 2 authentication
- OAuth 2 Troubleshooting
- Oauth2 problems in Moodle 3.3 forum discussion
- Problem to configure Oauth2 with Microsoft Office365 forum discussion
