Skip to content

Configuration

Spec

See the complete specification in the NAIS manifest.

Getting started

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; if omitted:
      # - false if claims.groups is defined
      # - true otherwise
      allowAllUsers: true

      # optional, defaults shown
      singlePageApplication: false

  # optional, only relevant if your application should receive 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 

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

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
      allowAllUsers: true
      claims:
        groups:
          - id: "<object ID of group in Azure AD>"

Warning

Ensure that you include the allowAllUsers field and set the value to your desired behaviour.

If undefined, the default behaviour will only allow access to users in the defined groups.

Warning

Ensure that the object ID for the group is valid, and that the group actually exists in Azure AD.

Non-existing groups 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"
}

Access Policy

See access policy.