Introduction

This is a library to implement an OAuth 2.0 resource server (RS). The library can be used by any service that wants to accept OAuth 2.0 bearer tokens.

It is compatible with and was tested with php-oauth.

License

Licensed under the Apache License, Version 2.0;

http://www.apache.org/licenses/LICENSE-2.0

API

Using the library is straightforward, you can install it in your project using Composer.

<?php
require_once 'vendor/autoload.php';

use fkooman\oauth\rs\RemoteResourceServer;

$config = array(
    "introspectionEndpoint" => "http://localhost/php-oauth/introspect.php",
);
$rs = new RemoteResourceServer($config);
$introspection = $rs->verifyAndHandleRequest();

header("Content-Type: text/plain");
echo $introspection->getSub();  // resourceOwnerId

Only the introspectionEndpoint configuration parameter needs to be set.

• introspectionEndpoint (REQUIRED) specify the location at which to verify the OAuth token;
• realm (OPTIONAL) specify the "realm" of the RS that is used when returning errors to the client using the WWW-Authenticate header. Default value is Resource Server;

Verify Tokens

If you write a simple piece of software that does not use any framework for handling HTTP requests and responses you can use the following method to handle all communication with the client by itself:

verifyAndHandleRequest()

This will extract the Bearer Authorization header or access_token query parameter, verify it at the introspection endpoint and inform the client directly about any problems.

If you use a HTTP framework an other method is available to help you verify tokens:

verifyRequest(array $requestHeaders, array $queryParameters)

You can specify an array with request headers and an array with query parameters. You can just feed the library all request headers and query parameters as only the relevant Authorization and/or access_token query parameter are evaluated. If the client provides both an Authorization header and an access_token query parameter an error will be returned as it is not allowed to specify both methods simultaneously.

Retrieve Resource Owner Information

After the verifyRequest(), or any of the other verify functions, some methods may be available to retrieve information about the resource owner and client assuming the verification was successful and the token introspection endpoint provides this information to the resource server.

• getResourceOwnerId() (the unique resource owner identifier)
• getScope() (the scope granted to the client accessing this resource)
• getEntitlement() (the entitlement the resource owner has when accessing this resource)
• getExt() (get additional data set by the authentication plugin. For instance the SspResourceOwner class uses this to store the SAML attributes obtained from the identity provider)

Note that the getEntitlement() and getExt() methods are not supported by all authorization servers and is a proprietary extension to https://github.com/fkooman/php-oauth. There are more methods that can help with implementing a resource server more efficiently, see the TokenIntrospection class documentation.

Exceptions

The library will return exceptions when using the verifyRequest method, you can catch these exceptions and send the appropriate response to the client using your own (HTTP) framework.

The exception provides some helper methods to help with constructing a response for the client:

• getResponseCode()
• getAuthenticateHeader()
• setRealm($realm)
• getContent()

The getResponseCode() method will get you the (integer) HTTP response code to send to the client. The method setRealm($realm) allows you to set the "realm" that will be part of the WWW-Authenticate header you can retrieve with the getAuthenticateHeader() method. The getContent() method gives you a JSON formatted response you can send back to the client, this is OPTIONAL.

Here is an example on how to use this library with your own exception handling:

<?php
require_once 'vendor/autoload.php';

use fkooman\oauth\rs\RemoteResourceServer;
use fkooman\oauth\rs\RemoteResourceServerException;

$config = array(
    "introspectionEndpoint" => "http://localhost/php-oauth/introspect.php",
);

try {
    $rs = new RemoteResourceServer($config);
    $introspection = $rs->verifyRequest(apache_request_headers(), $_GET);
    header("Content-Type: text/plain");
    echo $introspection->getSub();
} catch (RemoteResourceServerException $e) {
    $e->setRealm("Foo");
    header("HTTP/1.1 " . $e->getResponseCode());
    if (NULL !== $e->getAuthenticateHeader()) {
        // for "internal_server_error" responses no WWW-Authenticate header is set
        header("WWW-Authenticate: " . $e->getAuthenticateHeader());
    }
    header("Content-Type: application/json");
    die($e->getContent());
}