REST API Authentication using External Identity Provider

Last updated on

20 February 2024

If you are looking to protect/restrict access to your Drupal REST APIs using your Identity provider, then you should go for the External Identity Provider Authentication method.

Drupal API Authentication using an External Identity Provider involves the use of tokens received from third-party providers like Google, Azure AD, Keycloak, Okta, Gitlab, etc. for accessing Drupal rest APIs securely.

In this method, you need to configure the module with the User Info Endpoint provided by your Identity Provider and the username attribute from your Identity Provider and you will be able to authenticate all the Drupal API Requests using the token provided by your provider. Drupal REST API Module verifies the received user credentials against the Drupal user account.

Download Know more

Setup Video:

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:
- REST UI
- RESTful Web Services
- Serialization

Steps to setup API Authentication using External Application/Identity Provider:

For better understanding, we will be taking an example of adding External Identity Provider based authentication to the Create User API for Drupal.
Please note that the /entity/user API of Drupal is used to create a user in Drupal.

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 on the Configure button of the REST UI module(as shown below)

Considering our example, we have to enable the /entity/user API present under the User. Enable this API by clicking on the Enable option in front of it.

Now, as our goal is to create a user in drupal, select the following configs:
- Method: POST
- Format: json
- Authentication provider: rest_api_authentication.
Selecting rest_api_authentication will allow the miniOrange REST API Authentication module to authenticate your API. Click on the Save Configuration button to continue.

Drupal REST API Authentication module configuration:

In this step, we will set up External Identity Provider as an API Authentication
method. In order to do so, please navigate to the API Authentication tab of the REST API Authentication Module (/admin/config/people/rest_api_authentication/auth_settings)
- Select the Enable Authentication checkbox and click on Save Settings.
- Below the Save Settings button, select the External Identity Provider radio button.
- In the User Info Endpoint text field, enter the user info endpoint of your Identity Provider so the module can fetch the user’s information using the provided token.
- Also, in the Username Attribute enter the attribute key/name of your Identity Provider in which the external provider is sending the username.

Grant Drupal roles permission to create a user in Drupal:

If you require, you can also grant non-admin Drupal roles permission to create a user in Drupal. You can do so by assigning Drupal roles to the Administer users permission from under the permission section (/admin/people/permissions) of your Drupal site.

That’s it!!!

Now let’s try to create a user in Drupal through an API call using an External Identity Provider for authentication.

Examples:

To create a user in Drupal you have to make a POST request along with the Token received from your identity provider.

Request: POST <your_drupal_base_url>/entity/user?_format=json
Header: Token: <Token_receievd_from_external_identity_provider>
Accept: application/json
Content-Type: application/json

Body: {
       "name": [
               {"value": "<username>"}
           ],
       "mail": [
               {"value": "<email>"}
           ],
        "pass":[
                {"value": "<password>"}
            ],
       "status":[
                {"value": "1"}
            ]
}

CURL Request Format-

curl --location --request POST ‘<your_drupal_base_url>/entity/user?_format=json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Token: <Token_receievd_from_external_identity_proider> \
--data-raw ' {
"name": [
{"value": "Username"}
],
"mail": [
{"value": "email"}
],
"pass":[
{"value": "Password"}
],
"status":[
{"value": "1"}
]
}'

You can also refer to the image of the Postman request added below:

A successful response returns the user information that you have created. (please refer to the image below)

If you receive any error in response then you can refer to the below table for the error description and possible solutions.

Error Response:

Error	Description
INVALID_USER_INFO_ENDPOINT	You will get this error whenever you provide the incorrect user info URL in the module configuration. Example: { "status": "error", "error": "INVALID_USER_INFO_ENDPOINT", "error_description": "Could not authenticate the token from your Provider. Please check your configurations." }
INVALID_USERNAME_ATTRIBUTE	You will get this error whenever you provide the incorrect username attribute in the module configuration or if there is an error while trying to retrieve the username. Example: { "status": "error", "error": "INVALID_USERNAME_ATTRIBUTE", "error_description": "Invalid request: Could not get user information." }
INVALID_TOKEN	You will get this error whenever the token provided by you is incorrect or missing from the header Example: { "status": "error", "error": "INVALID_TOKEN", "error_description": "Invalid request: Token Not Found.." }