Build a new connector with Postman

4. Authentication with OAuth 2.0

OAuth 2.0 is a protocol that lets Digital Assistant request authorization to access private details in external applications without needing a user's password. Postman connectors that make requests to services which require authentication must first authorize with the application via OAuth 2.0.

In this example, we will authenticate with Gitlab via OAuth 2.0's Web application flow, enabling us to create API requests to Gitlab as a logged-in user.

In Postman connectors, authorization is managed at a Collection level. To edit the Collection, hover on the collection and click the three dots to open the More actions menu, then select Edit.

Configuring the authorization

Every time a request is made to the Gitlab API, an OAuth token is sent alongside the request to verify that the request has been made by a logged in user and to return the correct data.

This token must be generated prior to sending the request. To do so, we must provide Postman with details for Digital Assistant, as well as authentication details from service we're connecting to.

The Digital Assistant OAuth2 token manager uses Postman variables to access these details. To create the required variables, navigate to the Variables tab.

The details shown are required for all Authorization Code grant type OAuth tokens, but their values will differ between external applications. Ensure you consult the API documentation of the service you're connecting to.

The following details are required to generate an OAuth token. Some values have been provided for authentication with Github's service.

_AccessCodeServiceEndpoint
External application URL where the user can authenticate
Value for Gitlab: https://gitlab.com/oauth/authorize
_AccessTokenServiceEndpoint
External application URL which generates access tokens
Value for Gitlab: https://gitlab.com/oauth/token
_ClientId
Digital Assistant's unique identifier to the external application
_ClientSecret
Digital Assistant's unique identifier to the external application
_Scopes
Describes the level of access Digital Assistant needs to the external application
Value for Gitlab: api

To generate _ClientId and _ClientSecret values for Gitlab, register a new application for Digital Assistant in Gitlab OAuth Applications with the Redirect URI https://app.adenin.com/oauth2connector/returnUrl. Digital Assistant requires access to the api scope.

When complete, your Variables tab should look as below.

Generating a token

In order to generate the OAuth token from the details entered, navigate to the Authorization tab and select OAuth 2.0 as the Type. In the panel on the right, click Get New Access Token.

In the modal that opens, complete the form using the variables we defined previously. Set the Callback URL to https://app.adenin.com/oauth2connector/returnUrl and the State to dev.

OAuth specification advises sending a static State parameter with each request to an OAuth authorization service. For development purposes, a static value is acceptable. In a production environment, Digital Assistant sends a unique value with each request and validates it against the one in the redirect request for enhanced security.

To request the token, click Request Token. A window will open, prompting you to log in to the GitLab account you want to use with Digital Assistant. Enter your GitLab credentials and click Sign in to continue.

You will then be prompted to authorize Digital Assistant to use your account. The scope of access will be confirmed in this prompt. Select Authorize to continue.

Once Gitlab has issued your OAuth token, the details of the token will be displayed. Select Use Token to use this OAuth token with your Postman collection.

Finally, select Update to save your changes.

Configuring the request

To test our OAuth connection to Gitlab, we will create a request to the Gitlab API to get information from the version endpoint.

To do so, create a new request in the working Collection and set the request URL to https://gitlab.com/api/v4/version. Leave the request type as GET.

To make the request, click Send. If a user has successfully authenticated, a 200 OK response will be received with some JSON in the response body.