OAuth 2 logo
League logo

Simple OAuth is an implementation of the OAuth 2.0 Authorization Framework RFC. Using OAuth 2.0 Bearer Token is very easy. See how you can get the basics working in less than 5 minutes! This project is focused in simplicity of use and flexibility. When deciding which project to use, also consider other projects like OAuth, an OAuth 1 implementation that doesn't rely on you having https in your production server.

Based on League\OAuth2

This module uses the fantastic PHP library OAuth 2.0 Server from The League of Extraordinary Packages. This library has become the de-facto standard for modern PHP applications and is thoroughly tested.

Quick demo (Password Grant)

  1. Install the module using Composer: composer config repositories.drupal composer https://packages.drupal.org/8 && composer require drupal/simple_oauth:2.x-dev. You can use any other installation method, as long as you install the OAuth2 Server composer package.
  2. Generate a pair of keys to encrypt the tokens. And store them outside of your document root for security reasons.
openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout > public.key
  1. Save the path to your keys in: /admin/config/people/simple_oauth.
  2. Go to REST UI and enable the oauth2 authentication in your resource.
  3. Create a Client Application by going to: /admin/config/people/simple_oauth/oauth2_client/add.
  4. Create a token with your credentials by making a POST request to /oauth/token. See the documentation about what fields your request should contain.
  5. (Not shown) Permissions are set to only allow to view nodes via REST with the authenticated user.
  6. Request a node via REST without authentication and watch it fail.
  7. Request a node via REST with the header Authorization: Bearer {YOUR_TOKEN} and watch it succeed.

Only local images are allowed.

Video tutorials

Watch a detailed explanation on how to use this module in the video tutorials.

My token has expired!

First, that is a good thing. Tokens are like cash, if you have it you can use it. You don't need to prove that token belongs to you, so don't let anyone steal your token. In order to lower the risk tokens should expire fairly quickly. If your token expires in 120s then it will be only usable during that window.

What do I do if my token was expired?

Along with your access token, an authentication token is created. It's called the refresh token . It's a longer lived token, that it's associated to an access token and can be used to create a replica of your expired access token. You can then use that new access token normally. To use your refresh token you will need to make use of the Refresh Token Grant. That will return a JSON document with the new token and a new refresh token. That URL can only be accessed with your refresh token, even if your access token is still valid.

What do I do if my refresh token was also expired, or I don't have a refresh token?

Then you will need to generate a new token from scratch. You can avoid this by refreshing your access token before your refresh token expires. This way you avoid the need to require the user to prove their identity to Drupal to create a new token. Another way to mitigate this is to use longer expiration times in your tokens. This will work, but the the recommendation is to refresh your token in time.


Check the official documentation on the Bearer Token Usage. And turn on SSL!.

Supporting organizations: 
Development and maintenance

Project Information