A crypto utility library for Postman

Postman-util-lib is a JavaScript library bundle to squeeze Postman script allowing you to easy use lot of cryptography method from Pre-request Script and Tests tabs in Postman.

Features

Setup in less than 5 min.
Straight use for JWT signature and validation.
OpenID Connect client_secret_jwt and private_key_jwt implementation.
PCKE challenge generation
All jsrsasign methods exposed in the library.

Installation

Well in fact this is not a installation but to use the library inside Postman you just need to put the library bundle content located here

https://joolfe.github.io/postman-util-lib/dist/bundle.js

In a Postman global variable, so can be reference from all your Collections/Request.

You have two options:

Automatic Setup (Recommended)

Just download the example postman collection in your computer and import the collection into your Postman app, execute the GET request called “Lib install” and that’s all! If request respond with a 200 OK the library will be store in a global variable called pmlib_code

Manual Setup

If you can’t import the example postman collection or simply you want to do the process by your selve, don’t worry is also very easy .

Navigate to the bundle url in your web browser and copy the content of the page.
In your Postman app open the “Manage Environments” screen clicking in the cogs icon located in the top right corner of the principal postman screen.
Once in “MANAGE ENVIRONMENTS” screen click on the “Globals” button. You will see a list of defined global variables.
Create a new variable in the table, choose a name (for example pmlib_code) and put in the first column, paste the bundle text in “INITIAL VALUE” column, and save using the button on the bottom.
That’s all

Don’t forget the variable name, will be used in the next section about “How to use it” the library.

Usage

Postman use a Sandbox to execute the JavaScript code, this means that you cannot import libraries as usually, the only allowed method is using the function eval(), I know I know is not a good practice but is the only way . So to make the library available to be used in a Pre-request Script or Tests script you just need to do:

eval( pm.globals.get('pmlib_code') )

The name of the variable that you get from globals scopes should be the same as you have choose in the installation step. When execute this code a new variable called pmlib will be created and will be available in the scope of the tab where you have execute this code.

Note: Don’t mismatch the variable name where you have put the library code with the name of the variable created after do the installation, this last name pmlib is static inside the library and you cannot change by yourself.

Now that library is loaded you can use it just referencing to pmlib, for example to obtain a PKCE challenge just put this code:

const challenge = pmlib.pkceChallenge()
console.log(challenge)

If you open the Postman console you will see something like this:

console-log

You can test exactly this code just using the example postman collection and run the Request called “Lib use example”.

Available Methods

pmlib.pkceChallenge()

Generate a “S256” Proof Key for Code Exchange (PKCE) as described in RFC7636, return an object like:

{
    code_challenge: "JT4SVOGg1mUhv8QNz3_PIYdgEJxy6tUyx9qAR_GWbPE",
    code_challenge_method: "S256",
    code_verifier: "ATT6CIewaFJnsachPeUfqD-5r7xj4g5MHE0qvDDP2T4"
}

Create and sign a JWT with the provided data

jwk: (Object, String) A jwk key to sign the jwt
payload: (Object) The jwt payload claims.
header: (Object) The jwt additional headers claims.
exp: (Number) The expiration time in seconds, default value 10min (600seg)
alg: (String) The algorithm used to sign the jwt, default value ‘RS256’

pmlib.jwtVerify(jwt, pubKey, algorithm = DEFAULT_ALG)

Verify that a JWT is valid (time) and correctly signed and return the parsed value, in case of not valid jwt the method will throw and Error.

jwt: (String) The jwt in string format to be verified.
pubKey: (String or Object) Public key string to verify the signature. A string for PEM format or an Object for JWK key.
algorithm: (String) Jwt should be signed with this algorithm. Default value ‘RS256’

In case of success the method returns an object like:

{
    header: {
        alg: "RS256"
        typ: "JWT"
    },
    payload: {
        aud: "http://audience.test.com"
        client_id: "bb2d95df-ae2e-4f22-a6ab-958d3591f1cf"
        exp: 4574525775
        iat: 1574525770
        iss: "bb2d95df-ae2e-4f22-a6ab-958d3591f1cf"
        jti: "NlkcfrbJwSvZrvtFDVrjP"
        nbf: 1574525770
    }
}

pmlib.sha256(string)

Return the hash of the passed value in sha256

string: (String) The value to be hashed to sha256.

pmlib.clientAssertPrivateKey(jwk, clientID, aud, exp = 600, alg = DEFAULT_ALG)

Generate a signed jwt for use ‘private_key_jwt’ client authentication as describe in Section 9 of OIDC

jwk: (String, Object) A jwk key to sign the jwt
clientID: (String) The client_id of the OAuth Client.
aud: (String) The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience.
exp: (Number) The expiration time in seconds, default value 10min (600seg)
alg: (String) The algorithm used to sign the jwt, default value ‘RS256’

pmlib.clientAssertSecret(secret, clientID, aud, exp = 600, alg = DEFAULT_ALG_H)

Generate a signed jwt for use ‘client_secret_jwt’ client authentication as describe in Section 9 of OIDC

secret: (String) A client secret to sign the JWT
clientID: (String) The client_id of the OAuth Client.
aud: (String) The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience.
exp: (Number) The expiration time in seconds, default value 10min (600seg)
alg: (String) The algorithm used to sign the jwt, default value ‘RS256’

pmlib.rs.*

The library expose all the method of jsrsasign in the object rs, so you can use all the method described in the API documentation.

For example:

const base64String = pmlib.rs.stob64u('My amazing string')

Postman collection

To use the automatic install method and also for test the library there exist a ready to use collection in the repo, in this location, you just need to download and import.

The collection is provided in two Postman versions:

Version 2: PostmanUtilityLibv2.postman_collection.json
Version 2.1: PostmanUtilityLibv21.postman_collection.json

Inside the collection you will find the next requests:

Lib install: A GET request to download the library source and put into a global variable. Is the automatic installation.
Lib use example: In the “script” tabs you will find examples about how to use the library.

postman-util-lib

A crypto utility library to be used from Postman Pre-request and Tests script tabs.