Log in an employee

This how-to guides you through the steps required to ensure that only employees authenticated with Entra ID can access your application.

Prerequisites

Before you begin, ensure that you have:

• Familiarized yourselves with the login proxy concepts.
• Exposed your application with an ingress.

Configure your application

Enable the login proxy for Entra ID in your application configuration:

app.yaml

spec:
  azure:
    application:
      enabled: true
    sidecar:
      enabled: true

Login proxy is only available in GCP

Login proxy is only available in GCP clusters, and will not work in on-prem clusters.

See the Nais application reference for the complete specifications with all possible options.

Grant access to 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

app.yaml

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.

Warning

Invalid group identifiers are skipped and will not be granted access to your application. Ensure that they are correct and exist in Entra ID.

All users

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

app.yaml

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:

app.yaml

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.

Handle inbound requests

Now that your application is configured, you will need to handle inbound requests in your application code. As long as the user is authenticated, all requests to your application at the server-side will include the Authorization header with the user's access_token as a Bearer token.

Your application is responsible for verifying that this token is present and valid. To do so, follow these steps:

Handle missing or empty Authorization header

If the Authorization header is missing or empty, the employee is unauthenticated.

Return an appropriate HTTP status code to the frontend, and redirect the employee's user agent to the login endpoint:

https://<ingress>/oauth2/login

Validate token in Authorization header

If the Authorization header is present, validate the JWT Bearer token within. If invalid, redirect the employee to the login endpoint:

https://<ingress>/oauth2/login

To validate a token, you can either:

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

Validate with Texas

Texas is not enabled by default

See the Texas documentation for more information.

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:

Parameter	Example Value	Description
identity_provider	azuread	Always azuread.
token	eyJra...	The access token you wish to validate.

application/jsonapplication/x-www-form-urlencoded

Token request

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

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

Token request

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:

Valid token

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

Claims are copied verbatim from the token to the response.

Which claims are validated by Texas?

Texas only validates the token's signature and its standard claims.

Other claims are included in the response, but are not validated by Texas. Your application must validate these other claims according to your own requirements.

Error response

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

Invalid token

{
    "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.

Libraries for token validation

We recommend using a library in your language of choice to handle all the validation steps described below. Here are some recommended libraries:

• navikt/oasis (JavaScript)
• navikt/token-support (Java / Kotlin)

Validation is also supported by many popular frameworks:

• Ktor (Kotlin)
• Spring Security (Java / Kotlin)

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.

Next steps

The employee is now authenticated and can access your application. You can extract the claims from the subject token found in the Authorization header to assert the user's identity.

However, the token is only valid for your application. To consume other APIs on behalf of the employee, exchange the token for a new token that targets a specific API.

Related pages

Learn how to consume other APIs on behalf of a employee

Entra ID reference

Login proxy reference