OAuth 2 API - Revision history

Mits: ja link

2023-03-22T15:04:18Z

ja link

← Older revision		Revision as of 15:04, 22 March 2023
Line 170:		Line 170:

	The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.		The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.

			[[ja:開発:OAuth_2_API]]

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:30:06Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:30, 14 July 2021
				
Line 51:
Line 51:
Despite what is said in the code documentation, it is best to check that the client is authenticated and if not,  redirect the user to log in. Despite what is said in the code documentation, it is best to check that the client is authenticated and if not,  redirect the user to log in.



<code php> <syntaxhighlight lang="php">
if (!$client->is_logged_in()) { if (!$client->is_logged_in()) {
     redirect($client->get_login_url());      redirect($client->get_login_url());
Line 126:
Line 126:
To use this class - we pass the oauth2 client to the constructor and then use the "call" method to call functions from the api. To use this class - we pass the oauth2 client to the constructor and then use the "call" method to call functions from the api.



<code php> <syntaxhighlight lang="php">
$service = new \fileconverter_googledrive\rest($client);             $service = new \fileconverter_googledrive\rest($client);            



Line 138:
Line 138:
Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected: Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:



<code php> <syntaxhighlight lang="php">
if ($issuer->is_system_account_connected()) { if ($issuer->is_system_account_connected()) {
     // Rock and roll.      // Rock and roll.
Line 146:
Line 146:
If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).   If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).  



<code php> <syntaxhighlight lang="php">
$client = \core\oauth2\api::get_system_oauth_client($issuer); $client = \core\oauth2\api::get_system_oauth_client($issuer);
</syntaxhighlight> </syntaxhighlight>
Line 154:
Line 154:
If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account.   If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account.  



<code php> <syntaxhighlight lang="php">
**                                                                                                                                   **                                                                                                                                  
  * Callback to get the required scopes for system account.                                                                              * Callback to get the required scopes for system account.

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:03:50Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:03, 14 July 2021
Line 36:		Line 36:
	[...]		[...]

	</~~code~~>		</syntaxhighlight>


Line 47:		Line 47:
	$client = \core\oauth2\api::get_user_oauth_client($this->issuer, $returnurl, $scopes);		$client = \core\oauth2\api::get_user_oauth_client($this->issuer, $returnurl, $scopes);

	</~~code~~>		</syntaxhighlight>

	Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.		Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.
Line 55:		Line 55:
	redirect($client->get_login_url());		redirect($client->get_login_url());
	}		}
	</~~code~~>		</syntaxhighlight>

	'''What is return URL?'''		'''What is return URL?'''
Line 120:		Line 120:
	}		}

	</~~code~~>		</syntaxhighlight>

	This example defines 2 functions in the external API 'create' and 'delete'. It specifies the http methods to use when calling these functions as well as the list of parameters. It also specifies that these functions return 'json' which means that the rest class will automatically decode the json response into an object. The url for each function call can contain parameters in the url (marked with curly braces). These will be replaced when they are passed as arguments to the function. Any remaining arguments will be appended as query parameters.		This example defines 2 functions in the external API 'create' and 'delete'. It specifies the http methods to use when calling these functions as well as the list of parameters. It also specifies that these functions return 'json' which means that the rest class will automatically decode the json response into an object. The url for each function call can contain parameters in the url (marked with curly braces). These will be replaced when they are passed as arguments to the function. Any remaining arguments will be appended as query parameters.
Line 132:		Line 132:

	$service->call('delete', $params);		$service->call('delete', $params);
	</~~code~~>		</syntaxhighlight>

	== How do I call API functions when the user is not logged in (e.g. from a scheduled task)? ==		== How do I call API functions when the user is not logged in (e.g. from a scheduled task)? ==
Line 142:		Line 142:
	// Rock and roll.		// Rock and roll.
	}		}
	</~~code~~>		</syntaxhighlight>

	If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).		If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).
Line 148:		Line 148:
	<code php>		<code php>
	$client = \core\oauth2\api::get_system_oauth_client($issuer);		$client = \core\oauth2\api::get_system_oauth_client($issuer);
	</~~code~~>		</syntaxhighlight>

	This client can now be used to access apis as the Moodle system user.		This client can now be used to access apis as the Moodle system user.
Line 167:		Line 167:
	return '';		return '';
	}		}
	</~~code~~>		</syntaxhighlight>

	The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.		The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:03:02Z
Text replacement - "<code php>  " to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 30:
Line 30:
* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints. * Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.



<code php> <syntaxhighlight lang="php">class google extends openidconnect implements issuer_interface {
  
class google extends openidconnect implements issuer_interface { 
[...] [...]



Line 44:
Line 42:
Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API. Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.



<code php> <syntaxhighlight lang="php">// Get an issuer from the id.
  
// Get an issuer from the id. 
$issuer = \core\oauth2\api::get_issuer($issuerid); $issuer = \core\oauth2\api::get_issuer($issuerid);
// Get an OAuth client from the issuer. // Get an OAuth client from the issuer.
Line 77:
Line 73:
There is an abstract class \core\oauth2\rest which contains helper functions to allow you to wrap a external rest api in an easier to use class. To use it, make a subclass in your own plugin and define the "get_api_functions()" method.   There is an abstract class \core\oauth2\rest which contains helper functions to allow you to wrap a external rest api in an easier to use class. To use it, make a subclass in your own plugin and define the "get_api_functions()" method.  



<code php> <syntaxhighlight lang="php">/**                                                                                                                                  
  
/**                                                                                                                                   
  * Google Drive Rest API.                                                                                                               * Google Drive Rest API.                                                                                                            
  *                                                                                                                                      *



Sarjona: Implement issuer
2021-05-13T07:30:01Z
Implement issuer

				
				
				
				
				
				← Older revision
				Revision as of 07:30, 13 May 2021
				
Line 24:
Line 24:






== I setup an OAuth 2 Issuer - how to I use it in code? == == How a new issuer service should be implemented? ==
Any OAuth2 Service should have a class into the lib/classes/oauth2/service/ folder extending from a discovery system (core\oauth2\discovery\base_definition) and implementing core\oauth2\service\issuer_interface:
 
* Discovery system indicates the way the endpoints should be obtained.
* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.
 
<code php>
 
class google extends openidconnect implements issuer_interface {
[...]
 
class imsobv2p1 extends imsbadgeconnect implements issuer_interface {
[...]
 
</code>
 
 
== I set up an OAuth 2 Issuer - how do I use it in code? ==
Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API. Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.






Sarjona: Open Badge Connect API information
2021-05-11T10:00:30Z
Open Badge Connect API information

				
				
				
				
				
				← Older revision
				Revision as of 10:00, 11 May 2021
				
Line 15:
Line 15:
=== Open ID Connect === === Open ID Connect ===
Open ID Connect is a protocol built on top of OAuth 2 which provides some standardisation and inter-operability for OAuth 2 based services. If a "base service url" is entered for an Issuer - Moodle will attempt to retrieve the "well known configuration" which provides all the information about the other endpoints required to complete the setup for this service. E.g. for Google - the base service url is "https://accounts.google.com/". By appending ".well-known/openid-configuration" to the url we can find the service description at https://accounts.google.com/.well-known/openid-configuration which contains all the required information for us to automatically complete the setup for this service. This will work with any Open ID connect compliant service. Open ID Connect is a protocol built on top of OAuth 2 which provides some standardisation and inter-operability for OAuth 2 based services. If a "base service url" is entered for an Issuer - Moodle will attempt to retrieve the "well known configuration" which provides all the information about the other endpoints required to complete the setup for this service. E.g. for Google - the base service url is "https://accounts.google.com/". By appending ".well-known/openid-configuration" to the url we can find the service description at https://accounts.google.com/.well-known/openid-configuration which contains all the required information for us to automatically complete the setup for this service. This will work with any Open ID connect compliant service.

=== Open Badge Connect API ===
Open Badge Connect API is a specification built by IMS Global which provides some standardisation and interoperability for OAuth 2 based services. If a "base service URL" is entered for an Issuer, Moodle will attempt to retrieve the "well-known configuration" (.well-known/badgeconnect.json) which provides all the information about the endpoints required to complete the setup for this service. Besides, if no client id and secret are given, the registration endpoint will be called to get them (and safe time and effort to the admin).
E.g. for IMS Global testing platform, the base service URL is "https://dc.imsglobal.org/". By appending ".well-known/badgeconnect.json" to the URL we can find the service description which contains all the required information for us to automatically complete the setup for this service (endpoints, client id and secret, image...).



=== User field mappings === === User field mappings ===



Bencellis: /* I setup an OAuth 2 Issuer - how to I use it in code? */
2020-10-17T09:27:03Z
I setup an OAuth 2 Issuer - how to I use it in code?

				
				
				
				
				
				← Older revision
				Revision as of 09:27, 17 October 2020
				
Line 32:
Line 32:
</code> </code>



What is return URL?   Despite what is said in the code documentation, it is best to check that the client is authenticated and if not,  redirect the user to log in.
 
<code php>
if (!$client->is_logged_in()) {
    redirect($client->get_login_url());
}
</code> 
 
'''What is return URL?''' 



This is a url that will take you back to the current page. The way OAuth works is that the call to get the OAuth client will check to see if we have a valid session with all of the required scopes. If we don't - the user will be redirected immediately to the OAuth login page. When they have logged in - they are redirected back to the "returnurl" in Moodle which must end up making the same call to get an OAuth client - except this time we have a valid session so the client is returned. The returnurl MUST include the sesskey as one of the parameters. This is a url that will take you back to the current page. The way OAuth works is that the call to get the OAuth client will check to see if we have a valid session with all of the required scopes. If we don't - the user will be redirected immediately to the OAuth login page. When they have logged in - they are redirected back to the "returnurl" in Moodle which must end up making the same call to get an OAuth client - except this time we have a valid session so the client is returned. The returnurl MUST include the sesskey as one of the parameters.



What are the scopes? '''What are the scopes?'''



These are named "permission grants" which the user is asked to accept. E.g. "email" is a scope which allows Moodle to see the email address for your logged in account. Each of the requested permissions will be displayed to the user with a description of what they mean and the user will have to "grant" Moodle this level of access - or cancel the operation. It is best practice not to request more scopes than are needed at any one time, and to incrementally request additional scopes as they are going to be used by different features in Moodle. For example - when logging into Moodle we only need to request access to the users basic profile and email address. When accessing a repository - we will need to request read/write access to the users files. Each time we create an oauth client class, we list the scopes that we will be using with this instance of the oauth client - if the user has only approved some of the scopes we request - they will be redirected to a consent screen where they approve the additional level of access. These are named "permission grants" which the user is asked to accept. E.g. "email" is a scope which allows Moodle to see the email address for your logged in account. Each of the requested permissions will be displayed to the user with a description of what they mean and the user will have to "grant" Moodle this level of access - or cancel the operation. It is best practice not to request more scopes than are needed at any one time, and to incrementally request additional scopes as they are going to be used by different features in Moodle. For example - when logging into Moodle we only need to request access to the users basic profile and email address. When accessing a repository - we will need to request read/write access to the users files. Each time we create an oauth client class, we list the scopes that we will be using with this instance of the oauth client - if the user has only approved some of the scopes we request - they will be redirected to a consent screen where they approve the additional level of access.





Damyon: /* How do I call API functions when the user is not logged in (e.g. from a scheduled task)? */
2017-03-27T04:01:35Z
How do I call API functions when the user is not logged in (e.g. from a scheduled task)?

				
				
				
				
				
				← Older revision
				Revision as of 04:01, 27 March 2017
				
Line 145:
Line 145:
}    }   
</code> </code>

The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.





Damyon: /* I setup an OAuth 2 Issuer - how to I use it in code? */
2017-03-27T03:58:45Z
I setup an OAuth 2 Issuer - how to I use it in code?

				
				
				
				
				
				← Older revision
				Revision as of 03:58, 27 March 2017
				
Line 111:
Line 111:
</code> </code>



How do I call API functions when the user is not logged in (e.g. from a scheduled task)? == How do I call API functions when the user is not logged in (e.g. from a scheduled task)? ==



Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected: Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:

<code php> <code php>
if ($issuer->is_system_account_connected()) { if ($issuer->is_system_account_connected()) {
     // Rock and roll.      // Rock and roll.
} }
</code>

If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved). 

<code php>
$client = \core\oauth2\api::get_system_oauth_client($issuer);
</code>

This client can now be used to access apis as the Moodle system user.

If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account. 

<code php>
**                                                                                                                                 
 * Callback to get the required scopes for system account.                                                                          
 *                                                                                                                                  
 * @param \core\oauth2\issuer $issuer                                                                                               
 * @return string                                                                                                                   
 */                                                                                                                                 
function fileconverter_googledrive_oauth2_system_scopes(\core\oauth2\issuer $issuer) {                                              
    if ($issuer->get('id') == get_config('fileconverter_googledrive', 'issuerid')) {                                                
        return 'https://www.googleapis.com/auth/drive';                                                                             
    }                                                                                                                               
    return '';                                                                                                                      
}  
</code> </code>



Damyon at 03:54, 27 March 2017
2017-03-27T03:54:15Z


				
				
				
				
				
				← Older revision
				Revision as of 03:54, 27 March 2017
				
Line 109:
Line 109:



$service->call('delete', $params);                           $service->call('delete', $params);                          
</code>

How do I call API functions when the user is not logged in (e.g. from a scheduled task)?

Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:
<code php>
if ($issuer->is_system_account_connected()) {
    // Rock and roll.
}
</code> </code>

← Older revision		Revision as of 13:30, 14 July 2021
Line 51:		Line 51:
	Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.		Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.

	<~~code~~ php>		<syntaxhighlight lang="php">
	if (!$client->is_logged_in()) {		if (!$client->is_logged_in()) {
	redirect($client->get_login_url());		redirect($client->get_login_url());
Line 126:		Line 126:
	To use this class - we pass the oauth2 client to the constructor and then use the "call" method to call functions from the api.		To use this class - we pass the oauth2 client to the constructor and then use the "call" method to call functions from the api.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$service = new \fileconverter_googledrive\rest($client);		$service = new \fileconverter_googledrive\rest($client);

Line 138:		Line 138:
	Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:		Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:

	<~~code~~ php>		<syntaxhighlight lang="php">
	if ($issuer->is_system_account_connected()) {		if ($issuer->is_system_account_connected()) {
	// Rock and roll.		// Rock and roll.
Line 146:		Line 146:
	If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).		If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).

	<~~code~~ php>		<syntaxhighlight lang="php">
	$client = \core\oauth2\api::get_system_oauth_client($issuer);		$client = \core\oauth2\api::get_system_oauth_client($issuer);
	</syntaxhighlight>		</syntaxhighlight>
Line 154:		Line 154:
	If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account.		If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account.

	<~~code~~ php>		<syntaxhighlight lang="php">
	**		**
	* Callback to get the required scopes for system account.		* Callback to get the required scopes for system account.

← Older revision		Revision as of 13:03, 14 July 2021
Line 30:		Line 30:
	* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.		* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.

	<~~code~~ php>		<syntaxhighlight lang="php">class google extends openidconnect implements issuer_interface {

	class google extends openidconnect implements issuer_interface {
	[...]		[...]

Line 44:		Line 42:
	Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.		Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.

	<~~code~~ php>		<syntaxhighlight lang="php">// Get an issuer from the id.

	// Get an issuer from the id.
	$issuer = \core\oauth2\api::get_issuer($issuerid);		$issuer = \core\oauth2\api::get_issuer($issuerid);
	// Get an OAuth client from the issuer.		// Get an OAuth client from the issuer.
Line 77:		Line 73:
	There is an abstract class \core\oauth2\rest which contains helper functions to allow you to wrap a external rest api in an easier to use class. To use it, make a subclass in your own plugin and define the "get_api_functions()" method.		There is an abstract class \core\oauth2\rest which contains helper functions to allow you to wrap a external rest api in an easier to use class. To use it, make a subclass in your own plugin and define the "get_api_functions()" method.

	<~~code~~ php>		<syntaxhighlight lang="php">/**

	/**
	* Google Drive Rest API.		* Google Drive Rest API.
	*		*

← Older revision		Revision as of 07:30, 13 May 2021
Line 24:		Line 24:


	== I ~~setup~~ an OAuth 2 Issuer - how to I use it in code? ==		== How a new issuer service should be implemented? ==
			Any OAuth2 Service should have a class into the lib/classes/oauth2/service/ folder extending from a discovery system (core\oauth2\discovery\base_definition) and implementing core\oauth2\service\issuer_interface:

			* Discovery system indicates the way the endpoints should be obtained.
			* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.

			<code php>

			class google extends openidconnect implements issuer_interface {
			[...]

			class imsobv2p1 extends imsbadgeconnect implements issuer_interface {
			[...]

			</code>


			== I set up an OAuth 2 Issuer - how do I use it in code? ==
	Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.		Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.

← Older revision		Revision as of 10:00, 11 May 2021
Line 15:		Line 15:
	=== Open ID Connect ===		=== Open ID Connect ===
	Open ID Connect is a protocol built on top of OAuth 2 which provides some standardisation and inter-operability for OAuth 2 based services. If a "base service url" is entered for an Issuer - Moodle will attempt to retrieve the "well known configuration" which provides all the information about the other endpoints required to complete the setup for this service. E.g. for Google - the base service url is "https://accounts.google.com/". By appending ".well-known/openid-configuration" to the url we can find the service description at https://accounts.google.com/.well-known/openid-configuration which contains all the required information for us to automatically complete the setup for this service. This will work with any Open ID connect compliant service.		Open ID Connect is a protocol built on top of OAuth 2 which provides some standardisation and inter-operability for OAuth 2 based services. If a "base service url" is entered for an Issuer - Moodle will attempt to retrieve the "well known configuration" which provides all the information about the other endpoints required to complete the setup for this service. E.g. for Google - the base service url is "https://accounts.google.com/". By appending ".well-known/openid-configuration" to the url we can find the service description at https://accounts.google.com/.well-known/openid-configuration which contains all the required information for us to automatically complete the setup for this service. This will work with any Open ID connect compliant service.

			=== Open Badge Connect API ===
			Open Badge Connect API is a specification built by IMS Global which provides some standardisation and interoperability for OAuth 2 based services. If a "base service URL" is entered for an Issuer, Moodle will attempt to retrieve the "well-known configuration" (.well-known/badgeconnect.json) which provides all the information about the endpoints required to complete the setup for this service. Besides, if no client id and secret are given, the registration endpoint will be called to get them (and safe time and effort to the admin).
			E.g. for IMS Global testing platform, the base service URL is "https://dc.imsglobal.org/". By appending ".well-known/badgeconnect.json" to the URL we can find the service description which contains all the required information for us to automatically complete the setup for this service (endpoints, client id and secret, image...).

	=== User field mappings ===		=== User field mappings ===

← Older revision		Revision as of 09:27, 17 October 2020
Line 32:		Line 32:
	</code>		</code>

	What is return URL?		Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.

			<code php>
			if (!$client->is_logged_in()) {
			redirect($client->get_login_url());
			}
			</code>

			'''What is return URL?'''

	This is a url that will take you back to the current page. The way OAuth works is that the call to get the OAuth client will check to see if we have a valid session with all of the required scopes. If we don't - the user will be redirected immediately to the OAuth login page. When they have logged in - they are redirected back to the "returnurl" in Moodle which must end up making the same call to get an OAuth client - except this time we have a valid session so the client is returned. The returnurl MUST include the sesskey as one of the parameters.		This is a url that will take you back to the current page. The way OAuth works is that the call to get the OAuth client will check to see if we have a valid session with all of the required scopes. If we don't - the user will be redirected immediately to the OAuth login page. When they have logged in - they are redirected back to the "returnurl" in Moodle which must end up making the same call to get an OAuth client - except this time we have a valid session so the client is returned. The returnurl MUST include the sesskey as one of the parameters.

	What are the scopes?		'''What are the scopes?'''

	These are named "permission grants" which the user is asked to accept. E.g. "email" is a scope which allows Moodle to see the email address for your logged in account. Each of the requested permissions will be displayed to the user with a description of what they mean and the user will have to "grant" Moodle this level of access - or cancel the operation. It is best practice not to request more scopes than are needed at any one time, and to incrementally request additional scopes as they are going to be used by different features in Moodle. For example - when logging into Moodle we only need to request access to the users basic profile and email address. When accessing a repository - we will need to request read/write access to the users files. Each time we create an oauth client class, we list the scopes that we will be using with this instance of the oauth client - if the user has only approved some of the scopes we request - they will be redirected to a consent screen where they approve the additional level of access.		These are named "permission grants" which the user is asked to accept. E.g. "email" is a scope which allows Moodle to see the email address for your logged in account. Each of the requested permissions will be displayed to the user with a description of what they mean and the user will have to "grant" Moodle this level of access - or cancel the operation. It is best practice not to request more scopes than are needed at any one time, and to incrementally request additional scopes as they are going to be used by different features in Moodle. For example - when logging into Moodle we only need to request access to the users basic profile and email address. When accessing a repository - we will need to request read/write access to the users files. Each time we create an oauth client class, we list the scopes that we will be using with this instance of the oauth client - if the user has only approved some of the scopes we request - they will be redirected to a consent screen where they approve the additional level of access.

← Older revision		Revision as of 04:01, 27 March 2017
Line 145:		Line 145:
	}		}
	</code>		</code>

			The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.

← Older revision		Revision as of 03:54, 27 March 2017
Line 109:		Line 109:

	$service->call('delete', $params);		$service->call('delete', $params);
			</code>

			How do I call API functions when the user is not logged in (e.g. from a scheduled task)?

			Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:
			<code php>
			if ($issuer->is_system_account_connected()) {
			// Rock and roll.
			}
	</code>		</code>

OAuth 2 API - Revision history

Mits: ja link

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - " " to ""

Sarjona: Implement issuer

Sarjona: Open Badge Connect API information

Bencellis: /* I setup an OAuth 2 Issuer - how to I use it in code? */

Damyon: /* How do I call API functions when the user is not logged in (e.g. from a scheduled task)? */

Damyon: /* I setup an OAuth 2 Issuer - how to I use it in code? */

Damyon at 03:54, 27 March 2017

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""

Mudrd8mz: Text replacement - "`" to ""`