Skip to content

Configuration

Spec

See the complete specification in the NAIS manifest.

spec:
  azure:
    application:
      enabled: true

      # optional, enum of {trygdeetaten.no, nav.no}
      # defaults to trygdeetaten.no in dev-* clusters, nav.no in production
      tenant: nav.no

      # optional, generated defaults shown
      replyURLs: 
        - "https://my-app.dev.nav.no/oauth2/callback"

      # optional
      claims:
        extra:
          - "NAVident"
          - "azp_name"
        groups:
          - id: "<object ID of Azure AD group>"

      # optional, defaults shown:
      allowAllUsers: false

      # optional, defaults shown
      singlePageApplication: false

  # optional, only relevant if your application receives requests from consumers
  accessPolicy:
    inbound:
      rules:
        - application: app-a
          namespace: othernamespace
          cluster: dev-fss
          permissions:
            roles:
              - "custom-role"
            scopes:
              - "custom-scope"
        - application: app-b

  # required for on-premises only
  webproxy: true

Access Policy

Warning

Users are not granted access by default. You must explicitly grant access to users.

Applications are also not granted access by default. You must explicitly grant applications access by pre-authorizing them.

See access policy for further details.

Accessing external hosts

Azure AD is a third-party service outside of our clusters, which is not reachable by default like most third-party services.

Google Cloud Platform (GCP)

The following outbound external hosts are automatically added when enabling this feature:

  • login.microsoftonline.com
  • graph.microsoft.com

You do not need to specify these explicitly.

On-premises

You must enable and use webproxy for external communication.

Reply URLs

A redirect URI, or reply URL, is the location that the authorization server will send the user to once the app has been successfully authorized, and granted an authorization code or access token. The code or token is contained in the redirect URI or reply token so it's important that you register the correct location as part of the app registration process.

-- Microsoft's documentation on reply URLs

Defaults

If you have not specified any reply URLs, we will automatically generate a reply URL for each ingress specified using this formula:

spec.ingresses[n] + "/oauth2/callback"
Example

In other words, this:

spec:
  ingresses:
    - "https://my.application.dev.nav.no"
    - "https://my.application.dev.nav.no/subpath"
  azure:
    application:
      enabled: true

will generate a spec equivalent to this:

spec:
  ingresses:
    - "https://my.application.dev.nav.no"
    - "https://my.application.dev.nav.no/subpath"
  azure:
    application:
      enabled: true
      replyURLs:
        - "https://my.application.dev.nav.no/oauth2/callback"
        - "https://my.application.dev.nav.no/subpath/oauth2/callback"

Overriding explicitly

You may set reply URLs manually by specifying spec.azure.application.replyURLs[]:

Example 
spec:
  azure:
    application:
      enabled: true
      replyURLs:
        - "https://my.application.dev.nav.no/oauth2/callback"
        - "https://my.application.dev.nav.no/subpath/oauth2/callback"

Doing so will replace all of the default auto-generated reply URLs.

Danger

If you do override the reply URLs, make sure that you specify all the URLs that should be registered for the Azure AD client.

Ensure that these URLs conform to the restrictions and limitations of reply URLs as specified by Microsoft.

Tenants

To explicitly target a specific tenant, add a spec.azure.application.tenant to your nais.yaml:

spec:
  azure:
    application:
      enabled: true
      
      # enum of {trygdeetaten.no, nav.no}
      tenant: trygdeetaten.no

Single-Page Application

Azure AD supports the OAuth 2.0 Auth Code Flow with PKCE for logins from client-side/browser single-page-applications.

However, the support for this must be explicitly enabled to avoid issues with CORS:

spec:
  azure:
    application:
      enabled: true
      singlePageApplication: true

Claims

JWTs contain claims about the principal that the token represents.

The claims below are additional claims that are specific to Azure AD. They are opt-in and not included by default. These additional claims only affect tokens that are acquired where your application is the intended audience (i.e. scoped to your application).

Groups

The groups claim in user tokens is by default omitted due to potential issues with the token's size when used in cookies.

Sometimes however, it is desirable to check for group membership for a given user's token. Start by defining all Azure AD group IDs that should appear in user tokens:

spec:
  azure:
    application:
      enabled: true
      claims:
        groups:
          - id: "<object ID of group in Azure AD>"

Warning

Ensure that the object ID for the group actually exists in Azure AD for your environment.

Non-existing groups (object IDs) will be skipped.

Now all user tokens acquired for your application will include the groups claim.

The claim will only contain groups that are both explicitly assigned to the application and which the user is a direct member of.

Example decoded on-behalf-of token 
{
    "aud": "8a5...",
    "iss": "https://login.microsoftonline.com/.../v2.0",
    "iat": 1624957183,
    "nbf": 1624957183,
    "exp": 1624961081,
    "aio": "AXQ...",
    "azp": "e37...",
    "azpacr": "1",
    "groups": [
        "2d7..."
    ],
    "name": "Navnesen, Navn",
    "oid": "15c...",
    "preferred_username": "Navn.Navnesen@nav.no",
    "rh": "0.AS...",
    "scp": "defaultaccess",
    "sub": "6OC...",
    "tid": "623...",
    "uti": "i03...",
    "ver": "2.0"
}

If you wish to also restrict sign-ins and token exchanges with the on-behalf-of flow to users in these groups, see the groups section in access policy.

Extra

The Azure AD tenants in NAV have defined some non-standard claims that are available for inclusion in tokens.

These are opt-in by default, and you may selectively include any (or all) of these as needed.

The value of the NAVident claim maps to an internal identifier for the employees in NAV. This claim thus only applies in flows where a user is involved i.e., either the sign-in or on-behalf-of flows.

spec:
  azure:
    application:
      enabled: true
      claims:
        extra:
          - NAVident
Example decoded on-behalf-of token 
{
    "aud": "8a5...",
    "iss": "https://login.microsoftonline.com/.../v2.0",
    "iat": 1624957183,
    "nbf": 1624957183,
    "exp": 1624961081,
    "aio": "AXQ...",
    "azp": "e37...",
    "azpacr": "1",
    "groups": [
        "2d7..."
    ],
    "name": "Navnesen, Navn",
    "oid": "15c...",
    "preferred_username": "Navn.Navnesen@nav.no",
    "rh": "0.AS...",
    "scp": "defaultaccess",
    "sub": "6OC...",
    "tid": "623...",
    "uti": "i03...",
    "ver": "2.0",
    "NAVident": "Z123456"
}

azp_name

The azp_name claim will return the name of the consumer application that requested the token. This claim applies to both the client credentials flow and the on-behalf-of flow.

spec:
  azure:
    application:
      enabled: true
      claims:
        extra:
          - azp_name
Example decoded on-behalf-of token 
{
    "aud": "8a5...",
    "iss": "https://login.microsoftonline.com/.../v2.0",
    "iat": 1624957183,
    "nbf": 1624957183,
    "exp": 1624961081,
    "aio": "AXQ...",
    "azp": "e37...",
    "azpacr": "1",
    "groups": [
        "2d7..."
    ],
    "name": "Navnesen, Navn",
    "oid": "15c...",
    "preferred_username": "Navn.Navnesen@nav.no",
    "rh": "0.AS...",
    "scp": "defaultaccess",
    "sub": "6OC...",
    "tid": "623...",
    "uti": "i03...",
    "ver": "2.0",
    "azp_name": "dev-gcp:some-team:some-consumer"
}
Last update: 2023-03-08
Created: 2021-07-08