Last updated September 25, 2014. Created on March 9, 2013.
Edited by 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.

This will checkout the stable version of the library.
Each version of the module is pegged against a specific tag, which you can see in the module release notes, and checkout here.
For instance:

git checkout v1.5

to checkout v1.5, against which 7.x-1.1 is pegged.

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.

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