User and Identity Setup

AI Gateway accepts a verified JWT as the caller’s identity. Choose one of these identity setups:

• Use a PPC user when your deployment uses PPC authentication.
• Configure an external identity provider (IdP) when callers authenticate through an issuer such as Keycloak or Microsoft Entra ID.

Regardless of issuer, send the identity JWT to the gateway in the x-user-auth request header. The gateway validates it against the configured IdP trust registry.

PPC User Setup

Before client applications can call the gateway with a PPC-issued identity, the PPC role must grant gateway access and the user must be assigned that role.

1. Set the PPC URL and obtain an authentication token

1. Set the PPC URL using the following command:

export PPC_URL="https://<PPC_FQDN>"

2. Obtain an authentication token.

2. Add the gateway permission to the PPC role, preserving any permissions the role already requires.

curl -sS -X PUT "${PPC_URL}/pty/v1/auth/roles" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<PPC_ROLE>",
    "description": "Role for AI Gateway access",
    "permissions": ["can_create_token", "ai_gateway_access"]
  }'

3. Create a PPC user

curl -sS -X POST "${PPC_URL}/pty/v1/auth/users" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "<USERNAME>",
    "email": "<USER_EMAIL>",
    "firstName": "<FIRST_NAME>",
    "lastName": "<LAST_NAME>",
    "password": "<INITIAL_PASSWORD>",
    "roles": ["<PPC_ROLE>"]
  }'

Replace all placeholders with values for your PPC deployment. Use your organization’s password policy and secure credential-handling process.

Verify in the PPC administration interface that the role includes ai_gateway_access and that the new user is assigned that role. Then obtain the user’s identity JWT through your configured identity flow and test a request using the x-user-auth header as shown in Connecting to the Gateway.

External IdP Setup

The gateway trusts external issuers through an IdP registry file, idp.yaml. For each request, it reads the JWT from the header named by FG_PRINCIPAL_TOKEN_HEADER (default: x-user-auth), selects the issuer by the token’s iss claim, verifies the signature, and checks the configured issuer, audience, and expiration before mapping claims to the principal context.

Set the following gateway environment variables:

Example idp.yaml for an issuer with a JWKS endpoint:

issuers:
  - iss: "<IDP_ISSUER_URL>"
    idp: keycloak
    jwks_url: "<IDP_JWKS_URL>"
    audience: "<EXPECTED_AUDIENCE>"
    # Optional overrides for non-standard claim names:
    # user_id_claim: sub
    # roles_claim: realm_access.roles

Set iss to the exact issuer value in the JWT. Prefer jwks_url, which supports signing-key rotation. The gateway has claim-mapping defaults for keycloak, entra, and generic; override them only when the issuer uses non-standard claims. Supply a valid issuer-specific token to verify the configuration using the Connecting to the Gateway instructions.