# 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](https://github.com/fkooman/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](http://www.getcomposer.org).

    <?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](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());
    }