Authentication

Authentication is handled by the Azure API Management layer. Prior to calling the public API, you have to obtain a security token from the platform's IdP (Azure Active Directory) using the OAuth2 client credentials flow. The credentials are a service account created in the Configuration Portal.

The following drawing explains how authentication works for the public API and how the user information flows into the backend. The first thing to note is that the token handling and verification is done in Azure API Management. Any downstream services, such as Back-end for Front-end (BFFs) and individual micro services, are not concerned with token handling but rely on the API Management to carry out that work and to instruct them what user is connecting.

To avoid confusion, the following example invokes a command in the backend which results in a long running process. That is the reason why the API returns 202/Accepted. The BFF can also make the call synchronous to the outside world by issuing the command and waiting on a corresponding completed event or more often send a query to internal service over HTTP before returning to the caller. In that case, the API will return 200/OK.

To retrieve the security token, the following information is required:

The URL that you need to call is different per clients, since it requires the guid that refers to the tenant active directory in which the application registration is stored. The URL is:
https://login.microsoftonline.com/[tenantid]/oauth2/v2.0/token

Alternatively, instead of using a client_secret, it is possible to use certificate authentication. The process for obtaining a token is slightly different. First, you need to upload a certificate for the Application registration .

For generating a certificate refer to:
https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-self-signed-certificate#create-and-export-your-public-certificate.

Once a valid certificate is generated and uploaded, you need to generate a proof of possession token, refer to:
https://learn.microsoft.com/en-us/graph/application-rollkey-prooftoken.

The token can then be requested with the following parameters:

  • client_assertion_type: This is default set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • client_id See: Application registration
  • client_assertion: This is the generated proof of possession token.
  • scope: Will be supplied during the hand-over of the environment by five°degrees.
  • grant_type: This is default set to client_credentials.