Access Policy¶

Pre-authorization¶

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

Request a token for a specific client ID using the client using the OAuth 2.0 client credentials flow (service-to-service calls).
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:

The token is acquired by a consumer of your application.
The consumer has been granted a custom permission in your access policy definition.
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.

Users¶

By default, all users within the tenant are allowed to log in to your application. This behaviour is toggleable:

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

Groups¶

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

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

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

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.

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.

Last update: 2022-02-10
Created: 2021-07-08