How to Access OAuth Protected Resources Using Postman

To access an OAuth 2.0 protected resource, you need to provide an access token to access it.  For example, in the new implementation of Oracle Event Hub Cloud Service, Kafka brokers are OAuth 2.0 protected resources.

In this article, we will demonstrate how to obtain an access token of "bearer" type using Postman.

OAuth 2.0

OAuth enables clients to access protected resources by obtaining an access token, which is defined in "The OAuth 2.0 Authorization Framework" as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly.

There are different access token types.  For example,

• bearer
• mac

Each access token type specifies the additional attributes (if any) sent to the client together with the "access_token" response parameter. It also defines the HTTP authentication method used to include the access token when making a protected resource request.

For example, in this article, you will learn how to retrieve a bearer token using Postman, in which the generated HTTP response will look like below:

{
    "access_token": "eyJ4NXQjUzI1Ni <snipped> M8Ei_VoT0kjc",
    "token_type": "Bearer",
    "expires_in": 3600
}

To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.

Postman

Postman is a Google Chrome app for interacting with HTTP APIs. It presents you with a friendly GUI for constructing requests and reading responses. To download it, click on this link.  Note that Postman has been moved from a Chrome App to a Native App after this article has been written.^[7]

You can generate code snippets (see above diagram; however, a better alternative is to export/import a collection) using Postman for sharing purpose.  For example, we will use the following snippets for illustration in this article.

POST /oauth2/v1/token HTTP/1.1
Host: psmdemo2.identity.cxxxx1.oxxxxdev.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic MDlCRjg0RjYzQTlENEY4MjlCOTM2REFERDVGNzk3NTlfQVBQSUQ6NzY1NDQxMjUtNDE4ZC00YzlmLTg2MzUtNTFmMjRhMjFjYjMw
Cache-Control: no-cache
Postman-Token: 55cfed4b-509c-5a6f-a415-8542d04fc7ad

grant_type=password&username=xxxxx@oracle.com&password=welcome1&scope=https://09XX11X11X9D4F829B936DADD5F79759.uscom-central-1.cxxxx1.oxxxxdev.com:443/psmdemo2-mytopicresource

Generating Bearer Token

To access OAuth protected resources, you need to retrieve an access token first.  In this example, we will demonstrate with the access token of bearer type.

Based on shared code snippets above, it tells us to send a HTTP POST request to the following URL:

https://psmdemo2.identity.cxxxx1.oxxxxdev.com/oauth2/v1/token

which is composed from the following information in the snippets:

POST /oauth2/v1/token HTTP/1.1
Host: psmdemo2.identity.cxxxx1.oxxxxdev.com

Note that we have used https instead of http in the URL.

For the Authorization, we have specified "Basic Auth" type with an Username and a Password and, in the snippets, it shows as below:

Authorization: Basic MDlCRjg0RjYzQTlENEY4MjlCOTM2REFERDVGNzk3NTlfQVBQSUQ6NzY1NDQxMjUtNDE4ZC00YzlmLTg2MzUtNTFmMjRhMjFjYjMw

In the "Header" part, we have specified two headers in addition to the "Authorization" header using "Bulk Edit" mode:

Content-Type:application/x-www-form-urlencoded
Accept:application/json
Authorization:Basic MDlCRjg0RjYzQTlENEY4MjlCOTM2REFERDVGNzk3NTlfQVBQSUQ6NzY1NDQxMjUtNDE4ZC00YzlmLTg2MzUtNTFmMjRhMjFjYjMw


In the "Body" part, we have copied the last line from the code snippets to it in raw mode:

grant_type=password&username=xxxxx@oracle.com&password=welcome1&scope=https://09XX11X11X9D4F829B936DADD5F79759.uscom-central-1.cxxxx1.oxxxxdev.com:443/psmdemo2-mytopicresource

Note that the above body part is specifically to the Oracle Identity Cloud Service (IDCS) implementation.  Similarly, the "Authorization" part requires us to specify "Client ID" and "Client Secret" as username and password, which are also IDCS-specific.

How to Use Bearer Token

To access OAuth protected resources, you specify retrieved access token in the "Header" of subsequent HTTP requests with the following format:

Authorization:Bearer eyJ4NXQjUzI1Ni <snipped> M8Ei_VoT0kjc

Note that this access token will expire in one hour as noted in the HTTP response:

"expires_in": 3600

Summary

From this article, we have demonstrated that:

• What a Bearer Token is
• What an access token looks like
• How to share a code snippet
• We have shown to reverse-engineer from the shared code snippets to the final setup in Postman is not straightforward.  For example, the code snippet doesn't tell us:
• What the "Username" and "Password" to be used.  For example, we need to know that it requires the "Client ID" and "Client Secret" of application to be used in this case.
• Therefore, if you share the code snippets with co-workers, you also need to add further annotations to allow them to reproduce the HTTP requests to be sent. 

References

1. The OAuth 2.0 Authorization Framework: Bearer Token Usage
2. What are Bearer Tokens and token_type in OAuth 2?
3. Apache Kafka in the Cloud --- Oracle Event Hub Cloud Service
4. Postman documentation
5. Exporting and Importing Postman data
6. Understanding Login Authentication
7. Move from the Postman Chrome App to Postman Native Apps