Configure policies¶

Policies allow you to use different profiles based on different selectors.

Policy Configuration¶

Setting	Description	Required	Examples
`name`	The name of the policy.	Yes	`my-policy`
`authentication`	The authentication configuration for the policy.	Yes	See Authentication Configuration below
`profiles`	The profiles which may be selected by the policy and the necessary selectors.	Yes	See Profile Configuration below

JWT (JSON Web Token) Authentication Configuration¶

This section contains the base configuration for using the JWT selectors to choose a profile.

It is optional if you are not using JWT selectors.

Setting	Description	Required	Examples
`jwtSigningKeyFile`	The path to the JWT signing key file.	Yes
`jwtSigningKeyType`	The type of the JWT signing key.	Yes	`ES256`
`insecureAllowUnverifiedJWT`	Note, this option set to `true` is only recommended in production environments when JWT signature verification has been delegated to a proxy such as NGINX and mTLS is enabled	No	`false`

When using JWT for Authentication, provide a JWT signed with one of the supported algorithms (for example, RS256, ES256) using the corresponding private key. Ensure the public key is available in the file specified by auth.JWTSigningKeyFile and formatted correctly for the chosen algorithm. The JWT must contain valid claims, which will be verified against the provided key before authentication succeeds.

Note

We recommend authenticating clients using NGINX Ingress Controller. See the Expose with NGINX Ingress Controller guide.

Profile Configuration¶

Setting	Description	Required	Examples
`name`	The name of the profile. This should map to a `name` field under the top-level profiles object.	Yes	`admin-group`
`selector`	The selector to use for the profile. See Configure selectors general guidance on selectors and Use JWTs and request headers for profile selection below for detailed examples of selector use in the policy context.	No	If there is a Selector of type `jwt` then an `authentication` configuration is required.

Use JWTs and request headers for profile selection¶

Your policies can select different profiles based on the request, either using the request headers or JWT claims.

The profile selection logic depends on selectors. It is important to understand Selector logic and ordering when using header and JWT-based routing in the policy.

Select profiles with JWTs¶

You can configure your policies to use JWTs included in the Authorization header of your HTTP request (with or without bearer) to select the appropriate profile based on the JWT claims.

To use JWTs, you need to update the policies section in your aigw.yaml configuration file with the following settings:

policies:
  - name: <policy-name>
    authentication:
      jwtSigningKeyFile: <path-to-jwt-public-key-file>
      jwtSigningKeyType: <jwt-signing-key-type>

Then configure the profiles under your policy to use the jwt selector type to select the appropriate profile.

Example¶

The following configuration uses a JWT to select the appropriate profile based on the aud claim in the JWT token:

policies:
  - name: my-policy
    authentication:
      jwtSigningKeyFile: .certs/jwtES256.key
      jwtSigningKeyType: ES256.key

    profiles:
      - name: admin-group
        selector:
          type: jwt
          key: aud
          values:
            - admin.aud

      - name: user-group
        selector:
          type: jwt
          key: aud
          values:
            - user.aud

profiles:
  - name: admin-group
    # truncated

  - name: user-group
    # truncated

AI Gateway will return a 401 Unauthorized error if the JWT fails to validate or the JWT is malformed. If no matching profiles are found, a 404 Not Found error will be returned.

Expected JWT Behavior¶

Other than the aud field within the body, AI Gateway looks for and validates against the exp claim, following the RFC 7519 requirements. These are the only fields that AI Gateway currently considers and can be defined as either an array of strings or a single string:

{"aud": "single.string.example"}

{"aud": ["array", "of", "strings.example"]}

Select profiles with request headers¶

You can configure your policies to use HTTP request headers to select the appropriate profile.

To select a profile based on request headers, configure the policy to use the header selector type and the name of the header as the key:

policies:
  - name: <policy-name>

    profiles:
      - name: <profile-name>
        selector:
          type: header
          key: <header-name>
          values:
            - <header-value>

Example¶

policies:
  - name: my-policy

    profiles:
      - name: admin-group
        selector:
          type: header
          key: X-User-Role-Token
          values:
            - admin

      - name: user-group
        selector:
          type: header
          key: X-User-Role-Token
          values:
            - user

Previous Next