Last updated 28 April 2015. Created on 9 March 2013.
Edited by pjcdawkins, bojanz, Jaypan. Log in to edit this page.

This is a documentation page for the OAuth2 Server module.


OAuth 2.0 is the next evolution of the OAuth protocol which was originally created in late 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.


Long story short: If you're implementing an API, you'll most likely need an authorization solution. OAuth and OAuth 2 are such solutions.

For a brief overview of what OAuth2 is and how it works, see the following article:

For another, more detailed tutorial, see:

Getting started

1. Download the library from GitHub

Place it in your libraries folder (for example, sites/all/libraries/oauth2-server-php).
If installed, the Libraries API is used to locate the libraries folder, otherwise "sites/all/libraries" is assumed.

$ cd sites/all/libraries
$ git clone --branch master
Cloning into oauth2-server-php...
remote: Counting objects: 1807, done.
remote: Compressing objects: 100% (576/576), done.
remote: Total 1807 (delta 1074), reused 1752 (delta 1026)
Receiving objects: 100% (1807/1807), 278.33 KiB | 147 KiB/s, done.
Resolving deltas: 100% (1074/1074), done.

You then need to check out a stable version of the library. In the module release notes you can see which versions of the library are supported. For instance, run:

git checkout v1.7.0

to checkout v1.7.0 of the library, which works with the module version 7.x-1.2.

2. Enable the module

Go to admin/modules and enable the OAuth2 Server module.

The OAuth2 Server entry in admin/modules

3. Check library status

The admin/reports/status page should report the OAuth2 server library as available.

The OAuth2 Server entry in admin/reports/status

3. Create a server

Go to admin/structure/oauth2-servers and create a server.
Leave the default values in settings, they will be explained later.

An example OAuth2 server

4. Create a scope

Click the "scopes" link, and you will be taken to the scopes listing page.
Make sure you have at least one scope.

The OAuth2 Server scopes listing page

The module automatically creates a "basic" scope for you, set as the default.
A default scope is granted if no scope is specified during authorization.
If no default scope exists, then the client will be forced to specify a scope during authorization.

From the spec:

If the client omits the scope parameter when requesting
authorization, the authorization server MUST either process the
request using a pre-defined default value or fail the request
indicating an invalid scope.

Note that the choice of the default scope can be affected by modules implementing hook_oauth2_server_default_scope(). If no implementation of hook_oauth2_server_default_scope() returns a default scope, the one specified in the UI is used.
See oauth2_server.api.php for more information on this hook.

4a. Translate the scope

The scope description is shown on the authorization form to the end user (see screenshot on the bottom of the page).
If the i18n_string module is enabled (part of the Internationalization package) a "translate" link is present on the scope listing, allowing the description to be translated into other languages.

A scope translation page

5. Create a client

A client is an application requesting authorization from the resource owner (logged-in user on your website).

An oauth2_server client edit form

The Client ID and Client Secret can be thought of as the client username and password. The client id is considered public information while the client secret must be kept private at all cost.

The Redirect url must match the redirect_url param sent during authorization.
Important: Since OAuth2 requires SSL, the url MUST start with https.

"Automatically authorize this client" is an option that can be given to trusted clients, and will cause the authorization request to be automatically completed, without prompting the user for approval through the authorization form.

6. Give permission for using the OAuth2 Server

In admin/people/permissions, in section OAuth2 Server, check the permission Use OAuth2 Server (Use OAuth2 Server for authorization.) for anonymous users.

7. You are now ready to handle authorization requests.

A sample authorization form.

See oauth2_server.test for example client implementation code using drupal_http_request().

Looking for support? Visit the forums, or join #drupal-support in IRC.


andrezstar’s picture

Where are we able to "handle authorization requests"?
Cannot find any "auth request" button


bojanz’s picture

The authorization form is displayed on oauth2/authorize, at the start of the oauth2 authorization process.

muhaha03’s picture

I want to use google oauth playground to test it.
I can't find the auth and token endpoint in the doc.
Here it is for the one who need this.

Authorization endpoint:
Token endpoint:
Redirect URls:

But I get the result below. Is it correct?
GET /oauthplayground/?error=invalid_request&error_description=The+state+parameter+is+required HTTP/1.1

muhaha03’s picture

Is it possible to separate the oauth server to another dedicated server or VM ?
How to define the scope? There are only machine-readable name and description form inputs.

Vincents’s picture

I have downloaded and configured oauth2_server-7.x-1.1. After enabling the module unable to create scope and client and getting "The character encoding of the HTML document was not declared. The document will render with garbled text in some browser configurations if the document contains characters from outside the US-ASCII range. The character encoding of the page must be declared in the document or in the transfer protocol." Error

I have explore the code and found page call back "entity_ui_get_bundle_add_form" not present in "" also not available anywhere in the respective folder.

I dont know if it require any other supportive module or not i have added "xautoload" and "entityreference" as well (since this is a require modules for oauth2_server-7.x-1.1)

Please respond to this and guide me what i need to do further.

Thanks in advance

grigorym’s picture

It does look like we need proper version of Entity API module. I had an old-ish entity 1.1-something version, which had no entity_ui_get_bundle_add_form function. After installing version entity-1.6, I was able to create scope.

mike.hatch’s picture

I have configured both the Oauth2 Server and the restws module on my Drupal server (v7). I can make rest requests using the basic auth module (provided as part of the restws module), and I have successfully created an access_token using the Oauth2 Server. However, when I try to access resources via restws (such as /node/1.json) I consistently get 403 forbidden messages. Exactly what format does the Oauth2 client request need to take? I've tried the Authorization header (both Base64 and non-base64 encoded, the spec is unclear), the query string approach (?access_token=), and none work. Are there specific permissions that I need to set under admin/people/permissions? Thanks!

Note: I have also simply tried to make requests to regular pages using the token, and they all fail with a 403 response, so this doesn't seem to have anything to do with the restws module.

pranil_kochar’s picture

"/drupal/entity/oauth2_server_authorization_code" i have used this REST api to generate the authorization code and i am able to generate it . But how to go further ? even this api dose not demand any request property , how this can be possible?? and i have also generated server token using the REST api "entity/oauth2_server_token" but this token is of no use. can any one explain me how to do it on DRUPAL 8.4