Skip to content

Using Postman to Test Authentication Flows

In some cases it helps to look at the authorization calls directly to verify that an installation is working properly or to troubleshoot problems. We will showcase how to use Postman (https://www.postman.com/) to send web requests to the TCG Authorization Server to test authentication and authorization calls. Other API clients such as Insomnia will work similarly (https://insomnia.rest/).

This section is intended for developers or person familiar with HTTP. Experience with API clients such as Postman is highly recommended.

For the following samples we assume that the authorization service is hosted on https://auth.contoso.com.

Requesting the Open ID Connect discovery document

The discovery document contains Open ID Connect configuration and is used by many client libraries to configure the endpoints that will be used to request authorization, tokens or certificates.

  1. Create a new request
  2. Use the HTTP GET method, set the URL to https://auth.contoso.com/.well-known/openid-configuration

The response will be the discovery document. You can of course also use a browser and just paste a url adjusted to your authorization service host.

{
  "issuer": "https://auth.contoso.com/",
  "authorization_endpoint": "https://auth.contoso.com/connect/authorize",
  "token_endpoint": "https://auth.contoso.com/connect/token",
  ...
}

Obtaining an Token via Grant Type Client Credentials

Client credentials are used by the Primuss resource services. They expect that on the Authorization Server a confidential client is configured, along with the permissions Interactive Activities, Unattended Activities and Process Monitor.

  1. Create a new request
  2. Use the http POST method, set the URL to https://auth.contoso.com/connect/token
  3. Do not use parameters, leave the Authorization as No Auth
  4. The body is x-www-form-urlencoded
  5. Set the following values:
    1. client_id: your_confidential_client_id
    2. client_secret: your_client_secret
    3. grant_type: client_credentials
    4. scope: openid interactive unattended procmon

The response, if successful, looks like

{
    "access_token": "8fpSK01eKQfOlsz0FcfDUZW17QZettDmu-j2CuXZwK4",
    "token_type": "Bearer",
    "expires_in": 3599,
    "id_token": "<a signed JWT>"
}

Obtaining a Token via the Authorization Code Flow

The authorization code flow is a 2-step procedure that makes it possible that the web client that requires access to a resource can be authorized to retrieve an access token. The authorization happens by the user authenticating to the Authorization Server, potentially entering his user credentials.

By using this flow, the web client does not ever get access to user credentials, making this the current de-facto standard for authenticating users across the web. The authorization code flow requires a code challenge that depends on calculating the hash (usually SHA256) of a client-side generate code_verifier.

To test this flow, you need a registered client for the Authorization Code flow, with any redirect URI (in this example we use http://localhost/signin-oidc) and the permission Interactive Activities.

  1. Create a new GET request to https://auth.contoso.com/connect/userinfo
  2. Go to the Authorization Tab below the URL input
  3. Select Type OAuth 2.0
  4. In Configure New Token, configure:
    1. Grant Type: Authorization Code (With PKCE)
    2. Callback URL: https://localhost/signin-oidc (but do not select Authorize using browser)
    3. Auth URL: https://auth.contoso.com/connect/authorize
    4. Access Token URL: https://auth.contoso.com/connect/token
    5. Client ID: your_public_client_id
    6. Client Secret: leave empty
    7. Code Challenge Method: SHA-256
    8. Scope: offline_access openid interactive profile
    9. State: 1234
  5. Click Get New Access Token
  6. A dialog opens and expects you to log into the Authorization Server. Log in.
  7. The Token Details show your access token, your id token (due to scope openid) and your refresh token (due to scope offline_access)
    1. copy your refresh token.
  8. Click Use Token

Now send the GET request to the userinfo endpoint and retrieve information about the roles and scopes that are applied to your user.

Obtaining a Token via Grant Type Refresh Token

If you do not yet have a refresh token, perform the steps in the Authorization Code Flow example and copy the refresh token once your login was successful.

  1. Create a new POST reuqest to https://auth.contoso.com/connect/token
  2. Go to the Body tab, select x-www-form-urlencoded
  3. Enter the following keys and values:
    1. client_id: your_public_client_id
    2. grant_type: refresh_token
    3. refresh_token: YY4DaZOBufXw3nZlRYog1WVmb3eKMJeLIL2GmqbmBrQ (actually, the refresh_token you copied earlier)
  4. Send the request

The response contains a new access and refresh token, tells you the new token expiration (in 60 minutes), the granted scopes and the id token with user information that is used by the client application to display information about you.

{
    "access_token": "y3tNjPxk6KZaWtumRZnYSzQqex_WELVBfxV4tM-WkYE",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "openid offline_access interactive profile",
    "id_token": "<a signed JWT>",
    "refresh_token": "HWj-2ejYlFlU5HjKZagY0GTe_XJZ5JoTzqZ2yuqNb8k"
}

Important The issuer of the ID token must be verified and must match the authority URL.