OAuth2lib v12 Installation Guide


Download the code of oauth2lib v12 here or by command line with SVN: 

 svn checkout https://forja.rediris.es/svn/oauth2lib

Package Structure

  • PAPI_oauth2_client directory: Client Application example with PAPI configuration.
  • SAML_oauth2_client directory: Client Application example with SAML configuration.
  • oauth_as directory: OAuth2 Authorization Server code.
  • oauth_server directory: OAuth2 Resource Server code.
  • oauth_client directory: OAuth2 Client code.

To implement one of the elements above you must include in your PHP library directory the oauth2lib code (directories: 'oauth_as', 'oauth_server' and 'oauth_client_directory').

OAuth Client

Structure

Note: The configuration file must be named as described in the previous steps: clientConfig.xml.


Configuration

Step1: Instantiate the OAuth class.

In your application code, you must create an OAuth object. 
$client = new OAuth($dir);
Where $dir will be the absolute path to the directory where is located your configuration file. For example: 
$client = new OAuth(dirname(__FILE__)."/own_config/");
Note: The default path is the 'config' directory that we could find in the oauth_client directory.

Step2: Configure the parameters of the OAuth Client class

We load the default configuration parameters with the clientConfig.xml file. This file must be configured as we described in the clientConfig documentation.

We can modify this parameters dynamically with the OAuth class, too. These are defined in the client's documentation and are the following:

  • Authorization Server
    • PUBLIC setAs($url_as): void
  • Resource Server
    • PUBLIC setRs($url_rs): void
  • Scope
    • PUBLIC setScope($scope): void
  • Assertion Type: Type of the assertion (Defined by the constants PAPI or SAML2). By default PAPI.
    • PUBLIC setPAPIAssertionType(): void
    • PUBLIC setSAML2AssertionType(): void
  • Error Type: Error type. Defined by the constants HTML or JSON. By default HTML.
    • PUBLIC setHTMLErrorResponse(): void
    • PUBLIC setJSONErrorResponse(): void
  • Request type: Type of request that the Client makes to the Resource Server (Defined by the constants HEADER, GET or BODY). By default HEADER.
    • PUBLIC setBODYResourceRequest(): void
    • PUBLIC setGETResourceRequest(): void
    • PUBLIC setHEADERResourceRequest(): void
  • Client Secret and Client ID: Defined in the constructor of the OAuth Class
    • OAuth __construct ([ $file = ""])

The dynamic configuration will be made with these methods. For example:

$as="https://oauth-server.rediris.es/oauth2_12/oauth_as/tokenEndpoint.php";
$rs="https://oauth-server.rediris.es/oauth2_12/oauth_server/serverEndpoint.php";
$client->setAs($as);
$client->setRs($rs);
$client->setGETResourceRequest();
$client->setJSONErrorResponse();
$client->setSAML2AssertionType();

Step3: Start the authorization flow

$dev = $client->doOAuthFlow($assertion)

Where $assertion will be the specific assertion for an user. It could be an PAPI assertion or a SAML2 assertion.

In the case of a PAPI assertion, we send in $assertion the information stored in $_SESSION['userdata'], obtained with the phpPoA. For more information about phpPoA, see its web page

In the SAML2 case, we send in $assertion the result of call the method $as->getAttributes(); of SimpleSAMLphp. For more information about SimpleSAMLphp, see its web page


Step4: Getting the resource (or the error)

if(!$dev){
	echo $client->getError();
}else{
	echo $client->getResource();
}

We get the resource with the method getResource().

To know if exists an error, we must check if the result of the doOAuthFlow method returns FALSE or not.

To know which error has happened, we can use the getError() method, that returns a string with the information.


Step5: Formatting the resource

To show the resources to the user, you must implement a class to visualize them properly.

For example, in the use case example, we've implemented a method that gets the resource, an xml string, and format it properly, to show the information in a readable way.

We can format the resources in different ways depending on the scope of the resource, thanks to the method returnResource() of the OAuth class. This function, given an OAuthClient object, formats the corresponding response depending on the scope of the request.

In order to format a Response we must do the following steps:

Step 5.1: Formatting the resource

To format a resource you must to develop a Class that implements the interface IFormattingResource. An example of this type of class is the DefaultFormattingResource.

Step 5.2: Register the format to an specific Scope

To register the format, you must configure the format responses by scopes in the clientConfig.xml.


OAuth Authorization Server

Structure

Note: The configuration files must be named as described in the previous steps: policies.xml, errors.xml, serverKeys.xml and clientKeys.xml.

Configuration

Step1: Configuring the file serverKeys.xml

The Authorization Server has to know the Servers that are going to read its tokens. To define this, we use the serverKeys.xml file. The correct configuration of this archive is defined in the section of the documentation.

Step2: Configuring the file clientKeys.xml

The Authorization Server has to know with whose Clients are communicating. To define this, we use the keys.xml file. The correct configuration of this archive is defined in the section of the documentation.

Step3: Configuring the file policies.xml

The Authorization Server has to know which assertions are valid ones. To define the authorization policy, we use the policies.xml file. The correct configuration of this archive is defined in the section of the Policy's Documentation.

Step4: Endpoint

With the current code organization, the Token Endpoint that we must give to the Client App will be accessible in the php file: tokenEndpoint.php. In this step you will need to change the directory where your configuration is located, for example:

$config_dir = dirname(__FILE__)."/own_config/";
$as = new oauthAS($config_dir);

OAuth Resource Server

Structure

Note: The configuration files must be named as described in the previous steps: asKeys.xml, errors.xml and resourceClasses.xml.

Configuration

Step1: Configuring the file asKeys.xml

The Resource Server has to know with whose Authorization Servers are communicating. To define this, we use the asKeys.xml file. The correct configuration of this archive is defined in the section of the documentation.

Step2: To get the resources

To get the resources from the server, you must develop a class to get them.

This class must implement the IServerResource interface. For more information see the example class inside the library and its documentation.

Step3: Configuring the file resourceClasses.xml

To get the correct resources for each request, you must configure with scope is related to which resource.

To define this, we use the resourceClasses.xml file. The correct configuration of this archive is defined in the section of the documentation.

Step4: Endpoint

With the current code organization, the Server Endpoint that we must give to the Client App will be accessible in the php file: serverEndpoint.php. In this step you will need to change the directory where your configuration is located, for example:

$config_dir = dirname(__FILE__)."/own_config/";
$rs = new oauthRS($config_dir);