bshaffer/oauth2-server-php-docs

documentation for the oauth2-server-php library

OAuth2 Server PHP Documentation

This repository hosts the documentation for the oauth2-server-php library.

All submissions are welcome! To submit a change, fork this repo and send us a pull request.

Setup

Ruby 1.9 is required to build the site.

Get the nanoc gem, plus kramdown for markdown parsing:

bundle install

Compile the src into the output directory by running the following command:

nanoc compile

You can see the available commands with nanoc:

nanoc -h

Nanoc has some nice documentation to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.

Development

Nanoc compiles the site into static files living in ./output. It's smart enough not to try to compile unchanged files:

$ nanoc compile
Loading site data...
Compiling site...
   identical  [0.00s]  output/css/960.css
   identical  [0.00s]  output/css/pygments.css
   identical  [0.00s]  output/css/reset.css
   identical  [0.00s]  output/css/styles.css
   identical  [0.00s]  output/css/uv_active4d.css
      update  [0.28s]  output/index.html

Site compiled in 5.81s.

You can setup whatever you want to view the files. If you have the adsf gem, however (I hope so, it was in the Gemfile), you can start Webrick:

$ nanoc view
$ open http://localhost:3000

Compilation times got you down? Use autocompile!

$ nanoc autocompile

This starts a web server too, so there's no need to run nanoc view. One thing: remember to add trailing slashes to all nanoc links!

Deploy

$ rake publish

Styleguide

Not sure how to structure the docs? Here's what the structure of the API docs should look like:

# API title

## API endpoint title

    [VERB] /path/to/endpoint.json

### Parameters

name
: description

### Input (request json body)

<%= json :field => "sample value" %>

### Response

<%= headers 200, :pagination => true, 'X-Custom-Header' => "value" %>
<%= json :resource_name %>

Note: We're using Kramdown Markdown extensions, such as definition lists.

JSON Responses

We specify the JSON responses in ruby so that we don't have to write them by hand all over the docs. You can render the JSON for a resource like this:

<%= json :issue %>

This looks up GitHub::Resources::ISSUE in lib/resources.rb.

Some actions return arrays. You can modify the JSON by passing a block:

<%= json(:issue) { |hash| [hash] } %>

Terminal blocks

You can specify terminal blocks with pre.terminal elements. It'd be nice if Markdown could do this more cleanly...

<pre class="terminal">
$ curl foobar
....
</pre>

This isn't a curl tutorial though, I'm not sure every API call needs to show how to access it with curl.

oauth2-server-php-docs's Issues

JWT Access Token Payload

I would like to know if it is possible to add additional data to JWT Access Token Payload? For example we would like to include a user's role type in the JWT Access Token Payload. Thanks in advance!

Storing access_token/refresh_token relationship.

It would be nice to able to store the relationship between access_tokens and their refresh_tokens to make revoking tokens and clearing expired tokens cleaner.

However, adding the parameter to RefreshTokenInterface::setRefreshToken would break bwc.

Cron Job

Is there any built in function that we can execute in a CRON job to clean up the databases so we can get rid of old tokens etc and any data that is no longer relevant?

Expired (but brand new) Access tokens

I guess I more leaving this here in case anyone else runs into this problem.

I can't lay my finger on exactly what is causing the problem I'm having, but here is what happens.

From the command line I have the whole thing working just fine, I re-implemented everything as a web call from PHP and the access tokens are expired as soon as I make a call for them.

I'm not sure if I missed part of the set up, or something else, but my solution was to

1. Edit the database and set expires in the oauth.oauth_access_tokens table to a varchar (20) (anything over 10 should work).
2. Edit Pdo.php and comment out the "$expires = date('Y-m-d H:i:s', $expires);" lines, and comment out the line "$token['expires'] = strtotime($token['expires']);".

This removes all the unnecessary (from what I saw, but maybe I missed something) time stamp to time string conversions, and solves my problem.

Hope this helps anyone else that had this issue.

Xauth

Xauth: https://dev.twitter.com/oauth/xauth

Is user credentials grant type related to xauth?

OpenID

Any chances to have a doc on how to use OpenID?

invalid_client

hello, i have followed the cookbook by every step. http://bshaffer.github.io/oauth2-server-php-docs/cookbook/

During [Create a Token Controller] when i give it i try to test the files it returns an error which is as follows:
{
"error": "invalid_client",
"error_description": "Client credentials were not found in the headers or body"
}

I have used hurl.it to test the http Authorization

I have also attached the images of the request

Kindly guide me through this.

Add Laravel Cookbook

Add Laravel Cookbook Article

@julien-c has expressed interest in doing this

The crypto token validation docs are wrong

see bshaffer/oauth2-server-php#317:

The docs specify that you should base64_decode the signature before passing it to openssl_verify.
This will fail because the signature is not base64 encoded, it is "url safe base64 encoded", so the decode needs to be Jwt::urlSafeB64Decode, or its contents:

    $b64 = str_replace(array('-', '_'), array('+', '/'), $b64);
    return base64_decode($b64);

Note on Implicit Grant Type Security

Moving bshaffer/oauth2-server-php#81 to here

From @bojanz:

The implicit flow is less secure than the authorization code flow, neither the spec or any other resources attempt to hide that.

A potential problem revolves around mistakenly using OAuth2 not just for authorization, but for authentication as well.
An attack is described in http://homakov.blogspot.com/2012/08/oauth2-one-accesstoken-to-rule-them-all.html
and can be resolved by implementing an additional call to validate the access token after it has been received (send the token and a client id, get a status
and a list of scopes back).

I think it would make sense to have a note in the README about this.

As the people providing the library (and Drupal integration in my case), we are responsible if people shoot themselves in the foot with it.

Another related resource: http://homakov.blogspot.com/2013/03/oauth1-oauth2-oauth.html>

Rename JWT Claims

see bshaffer/oauth2-server-php#460

We need to rename the claims in the docs to be consistent with the latest version of the library:

http://bshaffer.github.io/oauth2-server-php-docs/overview/jwt-access-tokens/

Increase lifetime of Authorize code time

Hi,'

how do we configure, Authorize code life time for 1 month...

always_issue_new_refresh_token does not work in OAuth2\Server constructor

Hi,

first: I love your library, it's really easy to create an OAuth2 token controller and application!

I found a small problem: In the docs it says that I can give the config setting 'always_issue_new_refresh_token' to the OAuth\Server constructor, see here:
http://bshaffer.github.io/oauth2-server-php-docs/grant-types/refresh-token/

However, both of these configuration options can be sent in when the server is created using the server's configuration array:

$server = new OAuth2\Server($storage, array(
  'always_issue_new_refresh_token' => true,
  'refresh_token_lifetime'         => 2419200,
));

For me this does not work, and as far as I can see it is not supported in the code. This setting has to be done in the RefreshToken-constructor.

Now there are 2 solutions: correct the docs, or implement this feature. I don't know which is better.

Michael

Composer website link wrong

The link pointing to the Composer website has a typo in the target URL. It must be getcomposer.org instead of getcomposer.php.

User credentials grant incompatible with the oauth_clients table constraints

from @jgoux

Hello,
I want to implement the User credentials grant with your library (which is excellent :D)
I have an issue with the constraints set on the oauth_clients table.
In the doc, you give this query to create the oauth_clients table :

CREATE TABLE oauth_clients (client_id VARCHAR(80) NOT NULL, client_secret VARCHAR(80) NOT NULL, redirect_uri VARCHAR(2000) NOT NULL, grant_types VARCHAR(80), scope VARCHAR(100), user_id VARCHAR(80), CONSTRAINT client_id_pk PRIMARY KEY (client_id));

As my client is public, I don't need to associate a client_secret to it, and as I want to use the User credentials grant, I don't need to set a redirect_uri either.
So maybe client_secret and redirect_uri don't need the NOT NULL constraint by default.

Add Doctrine2 Cookbook

Add a Doctrine2 article to the cookbook

Add links to blogs for oauth explanation

http://blog.tankist.de/blog/2013/07/16/oauth2-explained-part-1-principles-and-terminology/

304 Response from Token handler

I am using the User Credentials (aka, grant_type of password) to gain an access token. It does effectively validate both that the user's username and password are correct as well as validate that the client_id. If the user validations fail than an error message such as the following is returned:

 Status Code: 400
 {"error":"invalid_grant","error_description":"Invalid username and password combination"}

if the client_id is invalid I get something along the lines of:

Status Code: 404
{"error" : "invalid_client","error_description::"client_id does not exist"}

I may tweak and change the error messages a bit but that part is working. The part that I think is behaving incorrectly is the success scenario. In the "step-by-step" guide it is indicated that the response should look something like:

{"access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35","expires_in":3600,"token_type":"bearer","scope":null}

Instead I just get a HTTP status code of 304 - Not Modified and nothing in the body of the message (as is standard for a 304).

My code is as follows:

 $request = OAuth2_Request::createFromGlobals();
 $request->request['grant_type']='password'; 
 $response = new OAuth2_Response();
 $server = new OAuth2_Server(static::$storage);
 $server->addGrantType(new OAuth2_GrantType_AuthorizationCode(static::$storage));
 $server->addGrantType(new OAuth2_GrantType_ClientCredentials(static::$storage));
 $server->addGrantType(new OAuth2_GrantType_UserCredentials(static::$storage));

 $server->handleTokenRequest(static::$request,static::$response)->send();
 die();

Also of note, my storage object's getAuthorizationCode() is never called. Finally, I am using the v0.9 from Composer which I believe is the latest.

Access Token Expiry

I am considering having applications allowed to use the "client credentials" workflow (aka, internal apps) have no expiry. In looking at the code it looks like the expiry timeframe is set at the "server" level (on construction) rather than on a workflow basis. Anyway, my questions are:

1. Is there a way to change Expiry behaviour by workflow type?
2. Is there a way to turn off expiry for certain workflow types?
3. Are there any strong reasons NOT to allow for an non-expiring policy for "client credentials"?

Ken

Slim framework cookbook

Hello,
I'm trying to implement oauth2-server (with the client credentials flow) with Slim framework.
Would it be possible to add a working example to the cookbook ? I don't know where to begin...

Public Client

Hi, do I understand correctly that I cannot use authorisation code as grant type without using client credentials? What I was trying to do, is to send a user to a webpage from my standalone app ( plugin actually ), then redirect him back with authorisation code, then use this auth code to receive access_token + refresh_token, and use the latter two to access my API. But I noticed that I need to send client_id and client_secret which is inappropriate for an app because it can be hacked? One solution would be to use implicit authorisation, but then I can't use refresh tokens and have to set access_token lifetime to quite long period of time. On the other hand, I can create a unique client id for each user and pass client id + secret during the redirect. This way, each user has its own client and people can't hack my own admin client so to speak.
Which way do you think is better and why? Many thanks. Sorry if it's not an appropriate place to ask such a question.

Unsupported operand types

In an attempt to get a simple test of the "Resource Owner Password" workflow working I ran into an Unsupported operand types PHP error in the AuthorizeController.php (line 74):

$clientData += array('redirect_uri' => null); // this should be set.  We should create ClientData interface

I haven't dug deeply into this as I'm not sure how deep the rabbit hole goes but I did put a debug line in right before to check what my "query" string is in the request and I get the following:

[query] => Array
    (
        [grant_type] => client_credentials
        [redirect_uri] => http://fake.url.com
        [username] => testclient
        [password] => testpass
        [client_id] => 1
    )

This is what I was expecting it to send so I'm at a loss. I'm hoping that I'm doing something obviously wrong and someone can quickly point me to the fault. It might also be a bug? I don't know at this stage.

Better Grant Type docs

The grant types section should:

1. include a table of contents (for each grant type)
   • possibly have their own pages?
2. Expand on the creation of a server for each grant type (code examples)
3. Include a complete list of configuration options for each grant type
4. Diagrams or workflows if applicable

Cookbook Authorize Redirect

http://localhost/authorize.php?response_type=code&client_id=testclient&state=xyz must include &redirect_uri= plus a URL.

If not, and you set redirect_uri in oauth_clients, you get this fatal error:
Uncaught exception 'PDOException' with message 'SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'redirect_uri' cannot be null'.

See also bshaffer/oauth2-server-php#163.

Add Symfony1.4 Cookbook

Add a Symfony 1.4 article to the cookbook

Password GrantType

I'm building an angular webapp, which will communicate with an API and oAuth2 authentication service. The webapps source code is viewable, so I don't want to store the client_secret in the code, this site:

http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified#password

suggests I should be able to send a request (in theory) using the granttype "password", but without the client secret, therefore protecting it from sniffing. However the library insists the client_secret is required.

If the above article is wrong what methods do you recommend for authenticating a pure JS app against the api, without using a server?

Thanks in advance!
Ben

P.S. The documentation has come on leaps and bounds recently :) thanks!

Missing SQL table examples

from bshaffer/oauth2-server-php#461:

Schema for jti_table and public_key_table implemented by PDO storage is missing.

http://bshaffer.github.io/oauth2-server-php-docs/cookbook/

Install Issue with yajl/json_gem

In the last commit, you removed the Gemfile, on purpose? Once the Gemfile is put back into place and after the bundle install/update, I'm getting:

LoadError: cannot load such file -- yajl/json_gem

Now I don't know much about Ruby, but I want to contribute to the docs, so know a quick and dirty fix?

Better Visibility for User Credentials Grant Type

From bshaffer/oauth2-server-php#459:

Hello,

Great work on this, very educational and helpful. Many thanks.

Here:
http://bshaffer.github.io/oauth2-server-php-docs/cookbook/

The server.php code should probably also include:
// Add the "password" grant type (this is where the oauth magic happens)
$server->addGrantType(new OAuth2\GrantType\UserCredentials($storage));

This is also important for people trying the demo app later.

Add a link to the demo app from the user credentials docs page, and add a link to the other grant types from the walkthrough page.

Add Docs for "Public Client"

show how UserCredentials and AuthorizationCode grant types can be used without client_secret for Public Clients

Access Token request - incomplete?

Hei,

First of all my compliments on this great library (I'm running the v1.3 branch locally).

I am wondering if there are more (documented) details about user identification?
I'm implementing the flow described in http://openid.net/specs/openid-connect-basic-1_0.html for a (local) fictive client (RP).
After having reached step 2.1.6, I am making an access token request to the token end point, with the parameters:

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
(see http://openid.net/specs/openid-connect-basic-1_0.html#TokenRequest)

I'm expecting the result shown here:
http://openid.net/specs/openid-connect-basic-1_0.html#TokenOK

But I'm getting a json response with the claims:
access_token, expires_in, token_type, scope, refresh_token (question on the side: "scope" is not defined in http://openid.net/specs/openid-connect-basic-1_0.html#TokenOK - is this correct?)

The claim id_token is missing.
Am I doing something wrong? Do I have to implement this myself, and if so, where?

Also: the UserInfo endpoint is missing. Again, do I have to implement this myself?
It would be great with a little bit more details on this (documentation?).

Thanks for a response.
Keep up the good work :)

Document User Credentials setup for Authorisation of a new user

I have a iOS native app that I am trying to implement the full cycle of user's authorisation. That is:

1. First Authorisation using a username and password via an authorise.php
2. Returned token via token.php
3. redirect.php , I thought step 1 was enough to grant a users, how is this used in a native user and password setup?

The User Credentials documentation doesn't show what code is setup in what file.

Include instructions on running this on a built-in PHP server

The Walkthrough should include instructions on how to run this using a built-in PHP server (i.e. php -S localhost:9000)

Add Wordpress OAuth2 Plugin to Cookbook

See the Wordpress OAuth2 Plugin and add it to the cookbook, specifically the Wordpressdb Storage Adapter

Picking up token in HTTP Header

I remember seeing reference to a configuration option that would allow the access_token to be passed in the header of the message rather than the default of appending to the URL as a GET variable. I can't, however, find that reference anywhere.

Hoping you can point me to how best to achieve this goal.

JWT scope attributes should be separated by space

According to the JWT OAuth2 spec the scope attribute is a list of space separated values, instead of comma as mentioned in the docs .

Grant type sample tables

There is an open issue with the library requesting table definitions for a grant type. #170

Would it be a good idea to add a sample table to the grant types page. The issue with this is it obviously depends on the storage adapter you are using, so maybe even a new page all together covering the storage adapters and hoe to use them with the different grants?

Improve OpenID Documentation

Please add to the openID documentation, that you musst add a new grant type

$config['use_openid_connect'] = true;
$config['issuer'] = 'brentertainment.com';
$server = new OAuth2\Server($config);
$server->addGrantType(new OAuth2\OpenID\GrantType\AuthorizationCode($storage));

Docs are wrong on validateAuthorizeRequest

from bshaffer/oauth2-server-php#231

I've just upgraded from an older version of this library to the latest on my server. Most everything seems to be working fine, however, I cannot seem to get the validateAuthorizeRequest function to return an array of client data as it did before.

public function displayAuth()
    {
        # validate the authorize request
        $request = OAuth2\Request::createFromGlobals();
        $response = new OAuth2\Response();
        if (!$clientdata = $this->server->validateAuthorizeRequest($request, $response)) {
            $response->send();
            die;
        }

        # display an authorization form
        if (empty($_POST)) {
            return View::make("layouts.api")->nest("child", "api.auth", array("status" => "form", "client" => $clientdata));
        }

    }

I'm using a Laravel controller to route API functions - it's constructed in the following manner.

class OAuthController extends BaseController {

    protected $server, $storage;

    public function __construct()
    {
        # register the autoloader
        require_once('/fake/path/to/oauth2-server/src/OAuth2/Autoloader.php');
        OAuth2\Autoloader::register();

        $storage = new OAuth2\Storage\Pdo([connection info array]);

        # Pass a storage object or array of storage objects to the OAuth2 server class
        $server = new OAuth2\Server($storage);

        # set up scopes
        $memory = new OAuth2\Storage\Memory(array(
            'default_scope' => 'profile',
            'supported_scopes' => array(
                'profile',
                'email',
                'sensitive'
            )
        ));
        $server->setScopeUtil(new OAuth2\Scope($memory));

        $this->server = $server;
        $this->storage = $storage;
    }

[other stuff here]

A quick var_dump() on the client variable returns bool(true). However, the documentation states that validateAuthorizeRequest returns false or an array of client data. Has this changed?

Document OpenID Connect

Document OpenID Connect integration

Add Docs for "use_crypto_tokens" Option

Document the "use_crypto_tokens" option, which makes adding crypto tokens much easier

cookbook misses id_token column

Following http://bshaffer.github.io/oauth2-server-php-docs/cookbook/ the step at
Create_an_Authorize_Controller
fails, until you run
ALTER TABLE oauth_authorization_codes ADD COLUMN id_token VARCHAR(80);
[not sure about 80 as size]
Be sure to update the CREATE TABLE at the start of the cookbook.
Note that you must display errors in php.ini, to see the problem (or view log).

Missing definition of PluginOAuthClientTable class from doctrine cookbook

Some of classes in Doctrine Cookbook extends PluginOAuthClientTable, but definition of this class is missing.

Table DDL statements in the cookbook doc and Pdo.php out of sync

From bshaffer/oauth2-server-php#463:

Good afternoon,

Just noticed that the DDL statements on the following page http://bshaffer.github.io/oauth2-server-php-docs/cookbook/ are not in sync with the OAuth2/Storage/Pdo.php function getBuildSql.

E.g. user table has more fields in Pdo.php than in the cookbook.

Token can not be sent as JSON

Hi there,

I think the token can not be sent as JSON.
Is that right?

Greetings
Tim

Add note regarding CSRF protection to documentation/step-by-step walkthrough

The /authorize implementation described in the step-by-step walkthrough allows for CSRF, where an attacker would be able to forge a request bypassing the authorization form.

It would be great if a note could be added so that future developers are aware of this. An example implementation would also be incredibly useful.

See bshaffer/oauth2-server-php#270

access token expire time

in database expire time is inserted 4 hours back. if time is 16:20:43 then there time inserted 12:03:47. please explain me how its work?

openssl_verify returns 0

Hi I was able to successfully generate the JWT token and got the access token, following the code in https://bshaffer.github.io/oauth2-server-php-docs/overview/jwt-access-tokens/, openssl_verify keeps on returning 0 instead of 1, and I was not able to var_dump the jwt payload in the end.

Sql Fields Missing

Hello,
Using the table scheme outlined: https://github.com/bshaffer/oauth2-server-php-docs/blob/master/content/cookbook/index.md#mysql--sqlite--postgresql--ms-sql-server causes an error.

It would appear supported_scopes and default_scope is missing from oauth_clients. I stumbled across this following the step-by-step walkthrough exactly.

Are there any more fields missing that you know of?

W

JWT Bearer Grant type not validating scope

I have managed to add scope on the jwt bearer grant type but it won't validate the scope like other grant types are doing by default.

$jwt = generateJWT($private_key, $client_id, $user_id, $scope, $audience, $expires, $nbf);

{
access_token: "30dd4b59463766d4704a3d2242f6e8b40145b79c",
expires_in: 3600,
token_type: "Bearer",
scope: "unknown_scope"
}

unknow_scope is not supported and other grant type validate that except for jwt bearer