Saturday, June 24, 2017

How to Access OAuth Protected Resources Using Postman

To access an OAuth 2.0 protected resource, you need to provide a bearer token to get access to 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,

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 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, you can click on this link.

You can generate code snippets 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
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Cache-Control: no-cache
Postman-Token: 55cfed4b-509c-5a6f-a415-8542d04fc7ad


Generating Bearer Token

To access OAuth protected resources, you need to retrieve an access token first.  In our 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:

which is composed from the following information in the snippet:

POST /oauth2/v1/token HTTP/1.1

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

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


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


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


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


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:
      • How to really setup the "Authorization" header because the shared snippet only shows the encrypted username and password.
      • What the "Username" and "Password" to be used.  For example, we need to know that it requires "Client ID" and "Client Secret" 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.