Skip to content

Auth Code Authorization Flow

Reference

https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow

Tldr

  1. Prerequisite: a registered App in Microsoft Entra that has the correct permissions. Get the client_id, the client_secret, the redirect_uri and the scope from the app

  2. in the browser, call 

    https://login.microsoftonline.com/common/oauth2/authorize?client_id={{client_id}}&response_type=code&redirect_uri={{redirect_uri}}&response_mode=query

    replacing client_id and redirect_uriaccording to your App. You will receive an authorization code.

  3. in postman, POST

    https://login.microsoftonline.com/{{tenant}}/oauth2/v2.0/token

    providing the following form data:
    oauth-authorize-postman.png
    The scopes are:

    1. for azure: https://management.azure.com/.default offline_access
    2. for Power BI: https://analysis.windows.net/powerbi/api/.default offline_access
    3. for BC, the scope is: https://api.businesscentral.dynamics.com/.default

  4. the grant_type is authorization_code

  5. copy the access_token and the refresh_token. Store the refresh_token in departments/delivery/knowledge-base/azure/key-vault/key-vault

For OAuth2, we have the following elements:

  1. an API. In this case, we are using two APIs:
  2. Power BI REST API

  3. Azure Admin API

  4. an App, consisting of

  5. a Client ID (aka as Application ID)
  6. a set of the maximum allowed Permissions against the APIs which a client can ask for. These permissions are identified through the Scope.
  7. a Secret, making sure that the authentication server knows that a request is indeed coming from the App (and not from some other app pretending to be your app)

We created all these elements in the previous section.

In this section, we use the Entra App to elements to authenticate a user against the Microsoft Identity Platform. Once authenticated, we get a Token that we can use to access the permitted functions of the API.

We have the following participants:

  1. the Client

  2. the Authorization Server

Note that the Authorization Server is not the same as the API.

There are the following steps:

  1. Request Authorization Code

  2. Get Access Token and Refresh Token for the first time (from Authorization Code)

  3. Get Access Token for subsequent times (from Refresh Token)

authorization-flow.png

Under normal circumstances, you will do this once per API. However, if you want to debug in Postman while you have your function running already, you want to authorize your user twice against the same API. You will then have two independent sequences of Access- / Refresh-Tokens. Then, since you need to authenticate against two different APIs, you will need to do this 4 times.

1. Request Authorization Code

In this step, we will make a call against the Authorization Server, as a logged-in user. The Authorization Server verifies our identity and returns a Code.

Find the client_id in your App:

client-id.png

Find the redirect_uri under Authentication:

redirect-uri-lookup.png

Follow these steps:

  1. in a text editor, assemble your Authorization URL by replacing the client_id and the redirect_uri in the following URL:
    https://login.microsoftonline.com/common/oauth2/authorize?client_id={client_id}&response_type=code&redirect_uri=https://localhost:44300/&response_mode=query&respones_type=code&prompt=consent
    NOTE: if you changed the permissions on the app, you need to prompt for consent again:
    https://login.microsoftonline.com/common/oauth2/authorize?client_id={{client_id}}&response_type=code&redirect_uri={{redirect_uri}}&response_mode=query& prompt=consent
    However, this might need admin consent again.

  2. copy and paste it into the address bar of a browser and hit enter

  3. you will be redirected to a "Hmmmm... can't reach this page"
    hmmm.png

  4. copy the URL from the address bar into a text editor

  5. copy the code section of the URL
    code-section.png

Note: In an earlier step, you Granted Admin Consent. What this means is that all users of your tenant automatically grant access to the App for the permissions defined. If you didn't Grant Admin Consent, the authentication server would list the Permissions and the user (you) would have to explicitly grant consent to these permissions.
grant-permission-request.png

2. Get Access Token for the first time (from Authorization Code)

With the code from the previous section, you can now assemble your token request.

Token Request elements

The easiest is to use Postman. You will need the following elements:

get-access-token.png

  1. the tenant_id: get it from Azure AD
    ![[tenant_id.png]

  2. the client_id: see above

  3. the client_secret: you (hopefully) wrote it down when you created the Client Secret
    secret-id-value.png

  4. the code: you received it from the previous step

  5. the redirect_uri: dito

  6. the scope: see below

The Scope

The scope defines a couple of things, namely:

  1. the permissions requested

  2. the specific flavour of authorization

You cannot share an access token for multiple APIs. For this reason, we need to run the authorization flow twice, once for each API. The scope then depends on which API you are using:

  1. for the Power BI REST API, use https://analysis.windows.net/powerbi/api/.default offline_access

  2. for the Azure Management API, use https://management.azure.com/.default offline_access

There are three elements in the scope:

  1. the URL of the API, e.g. https://analysis.windows.net/powerbi/api/. You will find it under API permissions:
    api-url-powerbi.png

  2. the permissions requested: in our case, we request .default, translating into all the permissions defined in the API permissions of the App. We could, however, also request only a limited set of permissions.

  3. the flavour of the authentications sequence. In our case, we request offline_access, meaning that we will get a Refresh Token together with the Access Token.

Request the Token

  1. In Postman, define all the elements described above

  2. Run the request as a POST request agains https://login.microsoftonline.com/{{tenant}}/oauth2/v2.0/token

  3. Receive the Access Token and the Refresh Token

Note that for convenience, we automatically save the tokens to the Postman Collection, using a Postman-Test. This is a trick, and a bit confusing, as we are not really running a test. We are merely using the Postman Test facility as a post-execution script that saves the variables in the collection.

postman-tests.png

Note also the expires_in. As explained above, the Access Token is short-lived (4385 seconds in our example). Once expired, you will need the Refresh Token, which is also delivered in the response, thanks to the offline_access requested.

3. Get Access Token for subsequent times (from Refresh Token)

With the Access Token received in the previous section, you are now ready to use the APIs until the Access Token expires. You will see how to do this in the next section.

Once the Access Token expires, you will need to get a new Access Token using the Refresh Token.

The request to do so is almost the same as when you got the first Access Token from the Code. The difference is:

  1. instead of sending the Code, you send the Refresh Token.

  2. the grant_type is refresh_token

refresh-access-token.png

Again, we are storing the Access Token and the Refresh Token as Postman Collection Variables.

collection-variables.png

Checklist

If you have successfully followed the steps in this chapter, you have:

  • an Access Token for the Power BI REST API
  • a Refresh Token for the Power BI REST API
  • an Access Token for the Azure Management API
  • a Refresh Token for the Azure Management API