OAuth 2 services: Difference between revisions

Latest revision as of 16:19, 2 January 2018

OAuth2 services

Moodle 3.3 adds support for OAuth 2 services, 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".

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.

Adding an issuer

If possible, use one of the preconfigured services if yours is among it. You can still configure individual details later on. You can choose from this list:

Preconfigured issuers

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.

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.
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.
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.

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 Google Drive repository or OneDrive repository.
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 (Moodle 3.3.2 onwards).
A system account is not needed for login functionality.

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.

@@ Line 2: / Line 2: @@
 ==OAuth2 services==
-Moodle 3.3 adds support for OAuth 2 services in core which can be used by any plugins to provide authenticated access to external services either as the current user, or using a system account.
+* Moodle 3.3 adds support for OAuth 2 services, 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 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 are used for example, to provide a "Login using Google/Microsoft/Facebook" feature on the login page, and then to share that authenticated session with repositories like Google Drive and Office 365 without having to re-authenticate.
+== Login ==
+See [[OAuth 2 authentication]] for details of how to enable the feature.
+== Open ID Connect ==
-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.
+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.
-== Login ==
+== Issuer Configuration ==
+First some terminology: In these scenarios, Moodle is the "client" and the remote service (Google, Facebook, ...) is the "issuer" or "provider".
+=== 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 LinkedIn service]]
+* [[OAuth 2 Twitter service]]
+* [[OAuth 2 Github service]]
+=== Adding an issuer ===
+If possible, use one of the preconfigured services if yours is among it. You can still configure individual details later on. You can choose from this list:
+ [[Image:OAuth2-predefined-issuers.png|frame|center|Preconfigured issuers]]
+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.
+See [[#Advanced_issuer_settings|Advanced issuer settings (below)]] for explanations of some of the settings.
+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.
+; Configure endpoints : Define the issuer's endpoints, i.e. the URLs that Moodle will connect to.
+; 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.
+; 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.
+=== Connecting a system account ===
-The steps required to enable login using an OAuth 2 service are:
+* 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 [[Google Drive repository]] or [[OneDrive repository]].
+* 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 (Moodle 3.3.2 onwards).
+* A system account is not needed for login functionality.
-# Create the OAuth 2 Service using the administration page at "Site administration -> Server -> OAuth 2 Services". There are templates available to create a pre-configured OAuth 2 service for Google, Office 365 and Facebook or you can manually enter all the required details for a custom OAuth 2 service.
+=== Advanced issuer settings ===
-# Register a new application with the OAuth 2 Service provider. Instructions for how to do this with Google, Office 365 and Facebook are listed below.
-# Enter the Client ID and Secret into the configuration page for the OAuth 2 service in Moodle.
-# Enable the OAuth 2 Authentication module.
-=== Open ID Connect ===
+; 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.
-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.
+==See also==
-=== How do I get a client ID and secret? ===
+* [[:Category:OAuth 2]]
-The client ID and secret are created outside of Moodle when setting up the OAuth provider. Instructions for prominent OAuth 2 providers are linked here.
+[[Category:OAuth 2]]
-* [[OAuth2_Services_Setup_Project_In_Google|Setup Project In Google]]
+[[es:Servicios OAuth 2]]
-* [[OAuth2_Services_Setup_Project_In_Microsoft|Setup Project In Microsoft]]
+[[de:OAuth2 Services]]
-* [[OAuth2_Services_Setup_Project_In_Facebook|Setup Project In Facebook]]

Documentation