Skip to content

Access Policy

Pre-authorization

For proper scoping of tokens when performing calls between clients, one must either:

  1. Request a token for a specific client ID using the client using the OAuth 2.0 client credentials flow (service-to-service calls).
  2. Exchange a token containing an end-user context using the OAuth 2.0 On-Behalf-Of flow (service-to-service calls on behalf of an end-user).

Azure AD will enforce authorization for both flows. In other words, you must pre-authorize any consumer clients for your application.

Clients that should receive and validate access tokens from other clients should pre-authorize said clients.

This is declared by specifying spec.accessPolicy.inbound.rules[]:

spec:
  accessPolicy:
    inbound:
      rules:
        - application: app-a

        - application: app-b
          namespace: other-namespace

        - application: app-c
          namespace: other-namespace
          cluster: other-cluster

Danger

  • These rules are eventually consistent, which means it might take a few minutes to propagate throughout Azure AD.
  • Any client referred to must already exist in Azure AD in order to be assigned the access policy permissions.
  • If you're pre-authorizing a client provisioned through aad-iac, ensure that you've read the legacy section.
  • Clients defined in the Spec that do not exist in Azure AD at deploy time will be skipped. If a non-existing client is created at a later time, we'll attempt to automatically force a resynchronization.

The above configuration will pre-authorize the Azure AD clients belonging to:

  • application app-a running in the same namespace and same cluster as your application
  • application app-b running in the namespace other-namespace in the same cluster
  • application app-c running in the namespace other-namespace in the cluster other-cluster

The default permissions will grant consumer clients the role access_as_application, which will only appear in tokens acquired with the client credentials flow (i.e. service-to-service requests).

If you require more fine-grained access control, see Fine-Grained Access Control.

Fine-Grained Access Control

You may define custom permissions for your client in Azure AD. These can be granted to consumer clients individually as an extension of the access policy definitions described above.

When granted to a consumer, the permissions will appear in their respective claims in tokens targeted to your application. Your application can then use these claims to implement custom authorization logic. Note that it is your application's responsibility to authorize or reject requests based on the permissions present in the token.

Warning

Custom permissions only apply in the context of your own application as an API provider. They are not global permissions.

These permissions only appear in tokens when all the following conditions are met:

  1. The token is acquired by a consumer of your application.
  2. The consumer has been granted a custom permission in your access policy definition.
  3. The target audience is your application.

Custom Scopes

A scope only applies to tokens acquired using the OAuth 2.0 On-Behalf-Of flow (service-to-service calls on behalf of an end-user).

Example configuration

spec:
  accessPolicy:
    inbound:
      rules:
        - application: app-a
          namespace: other-namespace
          cluster: other-cluster
          permissions:
            scopes:
              - "custom-scope"

The above configuration grants the application app-a the scope custom-scope.

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": "custom-scope defaultaccess",
    "sub": "6OC...",
    "tid": "623...",
    "uti": "i03...",
    "ver": "2.0"
}

Info

Any custom scopes granted will appear as a space separated string in the scp claim.

All clients defined in the access policy will by default have the scope defaultaccess.

Custom Roles

A role only applies to tokens acquired using the using the OAuth 2.0 client credentials flow (service-to-service calls).

Example configuration

spec:
  accessPolicy:
    inbound:
      rules:
        - application: app-a
          namespace: other-namespace
          cluster: other-cluster
          permissions:
            roles:
              - "custom-role"

The above configuration grants the application app-a the role custom-role.

Example decoded client credentials token 
{
  "aud": "8a5...",
  "iss": "https://login.microsoftonline.com/.../v2.0",
  "iat": 1624957347,
  "nbf": 1624957347,
  "exp": 1624961247,
  "aio": "E2Z...",
  "azp": "e37...",
  "azpacr": "1",
  "oid": "933...",
  "rh": "0.AS...",
  "roles": [
    "access_as_application",
    "custom-role"
  ],
  "sub": "933...",
  "tid": "623...",
  "uti": "kbG...",
  "ver": "2.0"
}

Info

Any custom roles granted will appear in the roles claim, which is an array of strings.

All clients defined in the access policy will by default have the role access_as_application.

Groups

Sometimes it is desirable to restrict access to your application to smaller groups of users. This can be done by explicitly declaring which Azure AD groups are allowed to access the application:

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 will be skipped.

Azure AD will now only allow sign-ins and token exchanges with the on-behalf-of flow if a given user is a direct member of at least one of the groups declared.

This also controls the groups claim for a user token.

Users

By default, only direct members of groups that are explicitly assigned to your application are allowed to access the application. If no groups are assigned, then no end-users will have access to your application.

If you want to allow all users in the Azure AD tenant to access your application, you must explicitly enable this:

spec:
  azure:
    application:
      enabled: true
      allowAllUsers: true

This applies for your application if it does at least one of the following:

Last update: 2023-01-02
Created: 2021-07-08