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

  • Any client referred to must already exist in Azure AD in order to be assigned the access policy permissions.
  • Be aware of dependency order when deploying your applications for the first time in each cluster with provisioning enabled.
  • 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.
  • Assignments will not be automatically retried.

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.

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.

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.

Groups

By default, all users within the tenant is allowed to log in to your application.

For some use cases, it is desirable to restrict access to smaller groups of users.

This can be done by explicitly declaring which groups are allowed to access the application:

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

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, which will only contain groups that are both explicitly assigned to the application and which the user is a direct member of.