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 beapi://<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.
- The
- 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 beapi://<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.
- The
- 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:
- OAuth 2.0 Client Credentials Grant
- OAuth 2.0 On-Behalf-Of Flow
- OpenID Connect Authorization Code Grant
Client Assertion¶
See client assertion for details.
For Azure AD specifics, consult their documentation:
- OAuth 2.0 Client Credentials Grant
- OAuth 2.0 On-Behalf-Of Flow
- OpenID Connect Authorization Code Grant
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:
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
Created: 2021-07-08