Setup Access Token / OAuth Based Authentication - miniOrange

 Download    Know more

Disclaimer: This document only covers the miniOrange API Authentication Module. It has a paid option that offers advanced functionality - but the community or contributed version of the module works just fine for all major use cases. 

Setup Video:

In OAuth 2.0, the following three parties are involved:

• The user possesses data that is accessed through the API and wants to allow the application to access it.
• The application wants to access the data through the API on the user's behalf.
• The API endpoint controls and enables access to the user's data.

The API will grant access only when it receives a valid access token from the application. How the application obtains an access token is dependent upon the OAuth scheme that is in use.

Pre-requisites: Download and Installation:

• Download & install the Drupal REST & JSON API Authentication module.
• REST UI: This module provides you with a user interface for configuring the REST module. 
• Enable the following Web Services modules from under the Extend section(/admin/modules) of your Drupal site:
  • JSON: API
  • REST UI
  • RESTful Web Services
  • Serialization

Enable the API and assign methods and operations as follows:

• The first step is to enable the API and also assign methods and operations allowed on that particular API. This can be done using the REST UI module, or you can simply modify the config.
• To enable the API using the REST UI module, click the Configure button of the REST UI module (as shown below).

• In our example, we need to enable the /entity/user API. To do this, click the Enable option in front of it.

• Now, as our goal is to retrieve the user information, select the following configs:
  • Method: GET
  • Format: json
  • Authentication provider: rest_api_authentication.
• This will allow the miniOrange REST API Authentication module to authenticate your API. Click the Save Configuration button to continue.

Setup OAuth/Access Token-Based API Authentication:

• In this step, we will configure OAuth/Access Token as the API authentication method. To do this, go to the API Authentication tab of the module (/admin/config/people/rest_api_authentication/auth_settings).
  • Under Basic Configuration, enable the Enable Authentication toggle.
  • Enter the Application Name and select OAuth/Access Token from the Authentication Method section.

• Scroll down to the OAuth Configuration section on the same tab.
  • Optional: Enter the desired expiry duration (in minutes) under Token Expiry Time.
  • Use Access Token Generated By:
    • Rest API Authentication: Click the Generate a new Client ID and Secret button. (Keep the Client ID and Secret handy. You’ll need them later to authenticate the create user API.)
    • OAuth Server: You can also get an access token from the OAuth Server module (after performing SSO) and use it for authentication.
  • Click the Save Configuration button.

• You have successfully configured the OAuth/Access Token Authentication method.

Grant Drupal roles permission to view user information:

• If you require, you can also grant non-admin Drupal roles permission to view user information. You can do so by assigning Drupal roles to the View User Information permission from under the permission section (/admin/people/permissions) of your Drupal site.

That’s it! Now, let’s fetch user information through an API call using OAuth/Access Token for authentication.

Obtain Token from REST API module:

• First, we need to make an API call to obtain an access token. We will then use this token to authenticate the Drupal API to retrieve a user’s information.
• The miniOrange API Authentication module supports two grant types that can be used to obtain an access token:

Password Grant:

• In the Password grant, you can obtain the access token by making a POST request with the user’s Drupal username and password, along with the Client ID issued by the REST API Authentication module.

• You can also refer to the Postman request image below.

Client Credentials grant:

• In the Client Credentials grant, we can obtain the access token by making a POST request containing the Client ID and Client Secret issued by the API Authentication module, along with the user’s Drupal username.

• You can also refer to the Postman request image to see how to obtain an access token from Drupal using the Client Credentials grant.

• A successful response returns the access token along with its expiry time and token type (see the image below).

Error Response:

Error	Description
INVALID_CREDENTIALS	You will get this error when either username or password is incorrect. Example: { "status": "error", "http_code": "401", "error": "INVALID_CREDENTIALS", "error_description": "Invalid username or password." }
INVALID_CLIENT_ID	You will get this error whenever you send an incorrect client ID. Example:{ "status": "error", "http_code": "401", "error": "INVALID_CLIENT_ID", "error_description": "Invalid Client ID." }
INVALID_CLIENT_SECRET	You will get this error whenever you send an incorrect client ID. Example: { "status": "error", "http_code": "401", "error": "INVALID_CLIENT_SECRET", "error_description": "Invalid Client Secret." }
MISSING_USERNAME	You will get this error whenever you have missed a parameter to send in the request. Example: { "status": "error", "http_code": "400", "error": "MISSING_USERNAME", "error_description": "No Username found in request." }

Example:

• Now, let’s retrieve user information using an API call with OAuth/Access Token for authentication.
• For better understanding, let’s use an example of adding OAuth/Access Token-based authentication to the Retrieve User Information API in Drupal.
• Using the received Access Token to authorize the Drupal REST APIs:

• To authenticate with an access token, add the token as a Bearer token in the Authorization header of your request.
• Sample request to retrieve user information using token-based authentication:

• You can also refer to the Postman request for the same:

• A successful response would look something like:

• Error Responses and Possible Solutions:

Error	Description
MISSING_HEADER	You will get this error if you don’t send a Unique header in the API request, or if your server removes it for some reason. Example: { "status": "error", "http_code": 400, "error": "MISSING_HEADER", "error_description": "Missing required unique header. It should contain the application ID." }
INVALID_ACCESS_TOKEN	You will get this error when you have put an invalid Access Token or expired Access Token. Example: { "status": "error", "http_code": "401", "error": "INVALID_ACCESS_TOKEN", "error_description": "Invalid Access Token." }
MISSING_AUTHORIZATION_HEADER	You will get this error whenever you don't send an Authorization Header in the API request or if it was removed by your server due to some reasons. Example: {   "status": "error",   "error": "MISSING_AUTHORIZATION_HEADER",   "error_description": "Authorization header not received." }
INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE	You will get this error when you send the Authorization header but the token type is not Bearer Example: { "status": "error", "http_code": "405", "error": "INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE", "error_description": "Authorization header must be the type of Bearer Token." }
TOKEN_EXPIRED	You will get this error when you send the Authorization header but the access token is expired. Example: { "status' => 'error",  "http_code'=>'401", "error' => 'TOKEN_EXPIRED", "error_description' => 'Invalid request: Token Expired." }

Congratulations! You can now authenticate any calls to your Drupal APIs using OAuth/Access Token-based authentication.

We hope you found this document useful and informative.