Introduction

Before integrating your OAuth / OpenID Connect (OIDC) protected endpoints into a complex application setup I recommend to first test the configuration parameters with an external tool to verify that everything works as expected. This approach can also help to avoid extremely long trial and error phases together with (mostly external) administrators managing OAuth server configurations.

[In my personal experience, it can take up to 10 months to receive a working configuration from a customer or the provider that works for the customer because there seem to be almost no experts in setting up OAuth server configurations].

Personally I would recommend that the provider of the server first proves with an external tool that the required endpoint(s) are working properly and also that the tokens have the structure and information that your application requires.

This article shows you how to use Postman to manually test an OAuth 2 protected endpoint for retrieving user information from Microsoft Azure AD. For querying the endpoint, you need to first request and retrieve a “Bearer” token - in our example it means that you need to login with your user credentials first.

I am using Azure AD as provider for the login and the endpoint because it’s by far the most requested system (like 85%) for me at work but you can of course use the steps outlined in this article also with other OAuth / OIDC providers.

How to retrieve OpenID Connect parameters

The OIDC protocol specification requires that the server provides a public URL where you can look up some of the most basic configuration parameters, the “provider configuration information”. This of course does not include parameters that need to remain secret to the public.

The format of the URL has to be like

 https://example.com/.well-known/openid-configuration 

In the case of Azure AD, the URL looks like

 https://login.microsoftonline.com/your-tenant-name-or-id/v2.0/.well-known/openid-configuration 

You can retrieve all needed configuration options from this URL except “Client ID” (Azure AD: “Application ID”), “Client Secret” and the Callback URL(s) - you can get these from Azure Portal or the administration interface of your server product.

Create a new request in Postman

Either select an existing “collection” (a folder where you place your request) in Postman or create a new one, then select “Add request” from the context menu.

  • Make sure a GET request is selected
  • Enter the “userinfo” URL (OIDC)

    https://graph.microsoft.com/oidc/userinfo

We can only request the information provided by this URL if we pass along a valid OAuth token we receive after authenticating with Azure AD.

To get the token, select the “Authorization” tab and from the “TYPE” select box, choose “OAuth 2.0”.

You then will see new options for this choice in the center of the screen, click on the button “Get New Access Token”.

This will show you a dialog where you need to fill in the parameters for the token. Type in a meaningful name (you might re-use it later) and make sure Authorization Code is selected as “Grant Type” and Client Authentication has the default selection “Send as Basic Auth Header”.

Parameter Source Azure AD style example
Callback URL App config in Azure Portal http://localhost:8080/dev
Auth URL authorization_endpoint https://login.microsoftonline.com/{tenant-id}/oauth2/authorize
Access Token URL token_endpoint https://login.microsoftonline.com/{tenant-id}/oauth2/token
Client ID Application ID Azure Portal a7c5d78a-3f51-3298-95f6-1da823fc297c
Client Secret Azure Portal on creation of app A=X:5G]z3odNzX?6vKGlzqqrt5:BzSS]
Scope scopes_supported / Azure Portal openid email profile
State random number 471108153322

When all properties are ready, click on the Request Token button.

If there is no cookie available you are asked to login to Azure AD with your user account. When everything goes well, the result will contain one or more tokens to be used to query the “userinfo”-URL with Postman.

Scroll down to the bottom of the resulting dialog and click on the Use Token button.

Then you put the token into the request header by clicking on Preview Request.

Navigate to the Headers tab (which now has a green number) and expand Temporary Headers - there you can see that the Bearer token has been added to the GET request.

Execute the request and examine the result

Click on the blue Send button to execute the request. The body on the bottom of the screen must show the 200 status, otherwise you have to check what went wrong.

Look at the result of your request and check if the content is as needed by your application. Mostly the values of the scope parameter together with the permissions on Azure AD define how the result will look like.

Tips and tricks

  • In the Authorization tab you can remove cookies if needed (for a fresh Azure AD login or a login with a different user account).
  • To inspect what happened and for debugging, you can use the Postman Console => Menu View => Show Postman Console

Additional resources