Hacker's ramblings

Postman. Not the guy delivering letters to your mailbox, the software which makes API-development much easier.

With APIs, there are number of authentication mechanisms. All kinds of passwords and keys are used to make sure I'm allowed to make the request. Also, modern authentication mechanisms include OAuth 2.0, OpenID Connect and such. Postman does support OAuth 2.0 out-of-the-box. For those less informed, here is a brief description by Auth0:

OAuth 2.0, which stands for “Open Authorization”, is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user.

For the record, OAuth 2.0 is a good protocol. Getting a JWT and making subsequent requests with it is among many things secure & sensible. If you didn't guess it by this far, yes, there is a glitch. RFC 6749 states following in subsection 4.3.2. Access Token Request:

The client makes a request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body:

grant_type REQUIRED.

    Value MUST be set to "password".

username REQUIRED.
    The resource owner username.

password REQUIRED.
    The resource owner password.

Since 1999 when RFC 2617 was written, we kinda have grown out of sending URL-encoded payloads as form responses. Today, it is 20s and JSON is the way to go. This is the glitch I mentioned, computer says: NO! Spec doesn't state "you may use JSON if you prefer to use it". I do. Many others do too. As Postman is per spec, they don't support JSON-encoded request bodies in OAuth 2.0 in their boxed authentication code. They do support all of the bells/whistles OAuth 2.0 has, but only per-spec.

Again, Postman is a good product, it does support freedom in form of a Pre-request script. I chose to exercise my freedom and crafted a plan is to following:

1. Write couple lines of JavaScript to be run as Postman Pre-request script to handle authentication
2. Script will be run for every request.
   • It is possible to override this mechanism by writing a per-request pre-request script, in which case the collection one will be ignored.
   • Per-request script can be as short as "return" to do a no-op.
3. Required authentication credential in form of JWT is stored into Postman collection variables and is generally available for authenticating any request in the collection
4. Pre-request script needs to be smart:
   • It will contain logic to determine if any further steps to execute an authentication is required or already existing token can be used to save time and resources.
   • We don't want to flood the authentication provider by requesting a JWT for everey single time. They might get angry and kick us out if we're too greedy.
5. Script is capable of reading the required authentication credentials for username and password from Postman environment.
   • NOTE! Credentials are not read from Collection, from Environment.
   • These credentials will be exhcnaged into a token. The token will be used for actual authentication.
6. Authentication protocol used is OAuth 2.0 ish, using JSON-body and expecting a JSON-response.
7. That's it. Done!

This is my Postman request-collection with the pre-request script:

Further, I have collection variables and the environment (the name I have for this environment is Production):

Here is one request using the pre-request -script from collection:

There isn't much setup needed. It just inherits the authorization setting from collection. Simple!

Full script I have is as follows:

const authTokenCollectionVariableName = "AuthToken";

// Verify, an OAUTH access token exists
if (pm.collectionVariables.get(authTokenCollectionVariableName)) {
    const tokStr = atob(pm.collectionVariables.get(authTokenCollectionVariableName).split('.')[1]);
    const tok = JSON.parse(tokStr);
    const expiry = new Date(tok.exp * 1000);
    const now = new Date();
    console.log(`Expiry: ${expiry}`);
    if (expiry > now) {
        console.log(`Auth - DEBUG: Has existing token. It is still valid. No need to renew.`);
        return;
    }
    console.log(`Auth - DEBUG: Has existing token. Renewing expired one.`);
} else {
    console.log(`Auth - DEBUG: No existing token found. Requesting one.`);
}

// Refresh the access token and set it into environment variable
pm.sendRequest({
    url: pm.collectionVariables.get("Account_API_BaseURL") + "/api/authenticate",
    method: 'POST',
    header: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            username: pm.environment.get("User"),
            password: pm.environment.get("Password")
        })
    }
}, (error, response) => {
    pm.expect(error).to.equal(null);
    pm.expect(response).to.have.property('code', 200);
    pm.collectionVariables.set(authTokenCollectionVariableName, response.json().accessToken);
    console.log(`Auth - INFO: Saved token ok.`);
});

To repeat: This script will run only inside Postman as embedded script. If you just whip up a random JavaScript environment, it most certainly will not have a pm-object in it and if it does, you cannot do all those fancy things I'm doing there.

Now the problem is solved. My requests run as smoothly and effortlessy as they would run with 100% per-RFC OAuth 2.0.