Usage¶

Use Cases¶

An Azure AD client allows your application to leverage Azure AD for authentication and/or authorization. The following sections will describe the recommended flows and grants to be used for applications running on the platform.

OpenID Connect Authorization Code Flow¶

This flow is used for sign-in and authentication of end users (NAV employees only) with single-sign on (SSO).

See Microsoft identity platform and OAuth 2.0 authorization code flow.

We generally recommend that you use the sidecar instead of implementing this yourselves.

OAuth 2.0 On-Behalf-Of Grant¶

This grant is used for machine-to-machine requests chains initiated by an end user. The end user's identity and permissions should be propagated through each service/web API.

Prerequisites¶

Your resource server / API and any downstream API that your API consumes have enabled Azure AD.
Your resource server has been pre-authorized by the downstream API.

Steps¶

Your resource server receives an access token in a request from a consumer with aud (audience) claim equal to your own client ID.
- This token contains the end user context, e.g. from the Authorization Code Flow or from a previous resource server that has also performed the On-Behalf-Of grant.
Your resource server requests a new token from Azure AD that is scoped to the downstream API that should be consumed.
- The scope parameter in the request should thus be api://<cluster>.<namespace>.<app-name>/.default
- The token returned from Azure AD will have an aud claim with a value equal to the client ID of the downstream API. Your resource server does not need to validate this token.
Your resource server performs the request to the downstream API by using the token as a Bearer token.
The downstream API validates the token and returns a response.
Repeat step 2 and 3 for each unique API that your application consumes.
The downstream API(s) may continue the call chain starting from step 1.

See Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow.

OAuth 2.0 Client Credentials Grant¶

This grant is used for pure machine-to-machine authentication, i.e. interactions without an end user involved.

Prerequisites¶

Your client and any downstream API that your client consumes have enabled Azure AD.
Your client has been pre-authorized by the downstream API.

Steps¶

Your resource server requests a new token from Azure AD that is scoped to the downstream API that should be consumed.
- The scope parameter in the request should thus be api://<cluster>.<namespace>.<app-name>/.default
- The token returned from Azure AD will have an aud (audience) claim with a value equal to the client ID of the downstream API. Your client does not need to validate this token.
Your resource server performs the request to the downstream API by using the token as a Bearer token.
The downstream API validates the token and returns a response.
Repeat step 1 and 2 for each unique API that your application consumes.
The downstream API(s) may continue the call chain by starting from step 1.

See Microsoft identity platform and the OAuth 2.0 client credentials flow.

Client Authentication¶

In order to fetch tokens from Azure AD, your application must authenticate itself. This can be done using either a client secret or a client assertion.

Client Secret¶

See client secret for details.

For Azure AD specifics, consult their documentation:

Client Assertion¶

See client assertion for details.

For Azure AD specifics, consult their documentation:

Runtime Variables & Credentials¶

The following environment variables and files (under the directory /var/run/secrets/nais.io/azure) are available at runtime:

`AZURE_APP_CLIENT_ID`¶

Note

Client ID that uniquely identifies the application in Azure AD.

Example value: e89006c5-7193-4ca3-8e26-d0990d9d981f

`AZURE_APP_CLIENT_SECRET`¶

Note

Client secret for the application in Azure AD for client authentication.

Example value: b5S0Bgg1OF17Ptpy4_uvUg-m.I~KU_.5RR

`AZURE_APP_JWKS`¶

Note

A private JWK Set (JWKS). This set is just a wrapper around a single key, i.e. AZURE_APP_JWK and will only contain one key at all times.

Example value:

{
  "keys": [
    {
        "use": "sig",
        "kty": "RSA",
        "kid": "jXDxKRE6a4jogcc4HgkDq3uVgQ0",
        "n": "xQ3chFsz...",
        "e": "AQAB",
        "d": "C0BVXQFQ...",
        "p": "9TGEF_Vk...",
        "q": "zb0yTkgqO...",
        "dp": "7YcKcCtJ...",
        "dq": "sXxLHp9A...",
        "qi": "QCW5VQjO...",
        "x5c": [
          "MIID8jCC..."
        ],
        "x5t": "jXDxKRE6a4jogcc4HgkDq3uVgQ0",
        "x5t#S256": "AH2gbUvjZYmSQXZ6-YIRxM2YYrLiZYW8NywowyGcxp0"
    }
  ]
}

`AZURE_APP_JWK`¶

Note

Private JWK containing an RSA key belonging to your client. Used to sign client assertions during client authentication.

Example value:

{
  "use": "sig",
  "kty": "RSA",
  "kid": "jXDxKRE6a4jogcc4HgkDq3uVgQ0",
  "n": "xQ3chFsz...",
  "e": "AQAB",
  "d": "C0BVXQFQ...",
  "p": "9TGEF_Vk...",
  "q": "zb0yTkgqO...",
  "dp": "7YcKcCtJ...",
  "dq": "sXxLHp9A...",
  "qi": "QCW5VQjO...",
  "x5c": [
    "MIID8jCC..."
  ],
  "x5t": "jXDxKRE6a4jogcc4HgkDq3uVgQ0",
  "x5t#S256": "AH2gbUvjZYmSQXZ6-YIRxM2YYrLiZYW8NywowyGcxp0"
}

`AZURE_APP_PRE_AUTHORIZED_APPS`¶

Note

A JSON string. List of names and client IDs for the valid (i.e. those that exist in Azure AD) applications defined in spec.accessPolicy.inbound.rules[]

Example value:

[
  {
    "name": "dev-gcp:othernamespace:app-a",
    "clientId": "381ce452-1d49-49df-9e7e-990ef0328d6c"
  },
  {
    "name": "dev-gcp:aura:app-b",
    "clientId": "048eb0e8-e18a-473a-a87d-dfede7c65d84"
  }
]

`AZURE_APP_TENANT_ID`¶

Note

The tenant ID for which the Azure AD client resides in.

Example value: 77678b69-1daf-47b6-9072-771d270ac800

`AZURE_APP_WELL_KNOWN_URL`¶

Note

The well-known URL for the OIDC metadata discovery document for the Azure AD tenant that the client is registered in.

Example value: https://login.microsoftonline.com/77678b69-1daf-47b6-9072-771d270ac800/v2.0/.well-known/openid-configuration

`AZURE_OPENID_CONFIG_ISSUER`¶

Note

issuer from the metadata discovery document.

Example value: https://login.microsoftonline.com/77678b69-1daf-47b6-9072-771d270ac800/v2.0

`AZURE_OPENID_CONFIG_JWKS_URI`¶

Note

jwks_uri from the metadata discovery document.

Example value: https://login.microsoftonline.com/77678b69-1daf-47b6-9072-771d270ac800/discovery/v2.0/keys

`AZURE_OPENID_CONFIG_TOKEN_ENDPOINT`¶

Note

token_endpoint from the metadata discovery document.

Example value: https://login.microsoftonline.com/77678b69-1daf-47b6-9072-771d270ac800/oauth2/v2.0/token

Last update: 2023-04-17
Created: 2021-07-08

Usage¶

Use Cases¶

OpenID Connect Authorization Code Flow¶

OAuth 2.0 On-Behalf-Of Grant¶

Prerequisites¶

Steps¶

OAuth 2.0 Client Credentials Grant¶

Prerequisites¶

Steps¶

Client Authentication¶

Client Secret¶

Client Assertion¶

Runtime Variables & Credentials¶

AZURE_APP_CLIENT_ID¶

AZURE_APP_CLIENT_SECRET¶

AZURE_APP_JWKS¶

AZURE_APP_JWK¶

AZURE_APP_PRE_AUTHORIZED_APPS¶

AZURE_APP_TENANT_ID¶

AZURE_APP_WELL_KNOWN_URL¶

AZURE_OPENID_CONFIG_ISSUER¶

AZURE_OPENID_CONFIG_JWKS_URI¶

AZURE_OPENID_CONFIG_TOKEN_ENDPOINT¶

`AZURE_APP_CLIENT_ID`¶

`AZURE_APP_CLIENT_SECRET`¶

`AZURE_APP_JWKS`¶

`AZURE_APP_JWK`¶

`AZURE_APP_PRE_AUTHORIZED_APPS`¶

`AZURE_APP_TENANT_ID`¶

`AZURE_APP_WELL_KNOWN_URL`¶

`AZURE_OPENID_CONFIG_ISSUER`¶

`AZURE_OPENID_CONFIG_JWKS_URI`¶

`AZURE_OPENID_CONFIG_TOKEN_ENDPOINT`¶