Secure your API with Entra ID¶

This how-to guides you through the steps required to secure your API using Entra ID:

Grant access to consumers¶

Depending on who your consumers are, you must grant access to either applications, users, or both.

Applications¶

By default, no applications have access to your API. You must explicitly grant access to consumer applications.

spec:
  azure:
    application:
      enabled: true
  accessPolicy:
    inbound:
      rules:
        - application: app-a

        - application: app-b
          namespace: other-namespace

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

The above configuration authorizes the following applications:

• 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

Users¶

By default, no users have access to your application. You must explicitly grant access to either specific groups, all users, or both.

Groups¶

To only allow access for users that belong to a specific set of groups, you must do two things:

• specify the group identifiers. To find your group's identifier, see finding the group identifier.
• set the allowAllUsers property to false

spec:
  azure:
    application:
      enabled: true
      allowAllUsers: false
      claims:
        groups:
          - id: "<group identifier>"

Entra ID will deny logins and on-behalf-of token requests for users that aren't direct members of the specified groups. Transitive membership through nested groups is not supported.

The groups claim in JWTs will include matching groups identifiers that the user is a direct member of.

All users¶

To allow all users to access your application, set the allowAllUsers property to true:

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

This is assigns a set of extra groups to the application, which covers all users in the Entra ID tenant. The groups claim in JWTs will also include the extra groups that the user is a direct member of.

Groups and all users¶

If you want to implement custom group-based authorization logic in your application, combine the above two configurations:

spec:
  azure:
    application:
      enabled: true
      allowAllUsers: true
      claims:
        groups:
          - id: "<group identifier>"

This has the following effects:

• All users are allowed to access your application, i.e. through logins or on-behalf-of token requests.
• The groups claim in JWTs will include matching groups identifiers that the user is a direct member of. This also includes the extra groups added by the allowAllUsers property.

Now that you have granted access to your consumers, they can now acquire tokens that target your application, either:

• on behalf of an employee, or
• as an application

You will need to validate these tokens in your application.

Validate tokens¶

Verify incoming requests from consumers by validating the JWT Bearer token in the Authorization header.

To validate a token, you can either:

• validate tokens with Texas, or
• validate JWTs manually in your application

Validate with Texas¶

Send a HTTP POST request to the endpoint found in the NAIS_TOKEN_INTROSPECTION_ENDPOINT environment variable. The request must have a Content-Type header set to either:

• application/json or
• application/x-www-form-urlencoded

The body of the request should contain the following parameters:

POST ${NAIS_TOKEN_INTROSPECTION_ENDPOINT} HTTP/1.1
Content-Type: application/json

{
    "identity_provider": "azuread",
    "token": "eyJra..."
}

POST ${NAIS_TOKEN_INTROSPECTION_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

identity_provider=azuread&
token=eyJra...

The response is always a HTTP 200 OK response with a JSON body.

It always contains the active field, which is a boolean value that indicates whether the token is valid or not.

Success response¶

If the token is valid, the response will additionally contain all the token's claims:

{
    "active": true,
    "exp": 1730980893,
    "iat": 1730977293,
    ...
}

Claims are copied verbatim from the token to the response.

Error response¶

If the token is invalid, the only additional field in the response is the error field:

{
    "active": false,
    "error": "token is expired"
}

The error field contains a human-readable error message that describes why the token is invalid.

Validate JWT manually¶

Validating a JWT involves a number of steps. These steps are outlined and described below in a language- and framework-agnostic way.

To validate the token, start by validating the signature and standard time-related claims.

Additionally, perform the following validations:

Issuer Validation

Validate that the iss claim has a value that is equal to either:

1. the AZURE_OPENID_CONFIG_ISSUER environment variable, or
2. the issuer property from the metadata discovery document. The document is found at the endpoint pointed to by the AZURE_APP_WELL_KNOWN_URL environment variable.

Audience Validation

Validate that the aud claim is equal to the AZURE_APP_CLIENT_ID environment variable.

Signature Validation

Validate that the token is signed with a public key published at the JWKS endpoint. This endpoint URI can be found in one of two ways:

1. the AZURE_OPENID_CONFIG_JWKS_URI environment variable, or
2. the jwks_uri property from the metadata discovery document. The document is found at the endpoint pointed to by the AZURE_APP_WELL_KNOWN_URL environment variable.

Claims Validation

Other claims may be present in the token. Validation of these claims is optional.