For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Enable browser-based OpenID Connect authentication with encrypted session cookies.

Attaches to:

OIDC browser authentication provides built-in OpenID Connect login for browser-based clients. By default, unauthenticated browser navigation requests are redirected to the identity provider’s login page, and unauthenticated fetch requests receive a 401 Unauthorized response. Additionally, you can send browser navigation requests to a local login page before the identity provider flow starts, and add a local logout endpoint that clears the gateway session. After successful authentication, the user’s session is maintained with encrypted cookies. To let non-browser clients call the same routes, the policy can also accept bearer tokens.

The OIDC policy uses the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange) for secure browser-based authentication without requiring a separate proxy like oauth2-proxy.

About

The following diagram shows the OIDC browser authentication flow between the browser, agentgateway, and identity provider.

    sequenceDiagram
    autonumber
    participant Browser
    participant AGW as Agentgateway
    participant IdP as Identity Provider

    Browser->>AGW: Request protected resource
    AGW->>AGW: No valid session cookie found
    AGW->>Browser: 302 Redirect to IdP login<br/>(with PKCE code_challenge)
    Browser->>IdP: Follow redirect to login page
    IdP->>Browser: Display login form
    Browser->>IdP: Submit credentials
    IdP->>Browser: 302 Redirect to redirectURI<br/>(with authorization code)
    Browser->>AGW: GET /oauth/callback?code=...
    AGW->>IdP: Exchange code for ID token<br/>(with PKCE code_verifier)
    IdP->>AGW: Return ID token
    AGW->>AGW: Validate ID token with JWKS
    AGW->>Browser: Set encrypted session cookie<br/>and redirect to original resource
    Browser->>AGW: Request with session cookie
    AGW->>AGW: Decrypt and validate cookie
    AGW->>Browser: Return protected resource
  

• Steps 1-3: Unauthenticated request. When a browser navigation arrives without a valid session cookie, the gateway redirects the user to the identity provider’s login page.
• Steps 4-6: Login. The user authenticates with the identity provider.
• Steps 7-8: Callback. After login, the identity provider redirects back to the redirectURI with an authorization code.
• Steps 9-11: Token exchange. The gateway exchanges the authorization code for an ID token using PKCE.
• Steps 12-15: Session cookie. The gateway sets an encrypted session cookie containing the ID token claims. Subsequent requests use this cookie.

Navigation and fetch requests

The gateway reads the Sec-Fetch-Mode request header that browsers send to tell a page navigation apart from a script request.

• Requests with Sec-Fetch-Mode set to cors, no-cors, same-origin, or websocket, such as fetch() calls, receive 401 Unauthorized instead of a redirect to the identity provider.
• If you set login.redirect, the 401 response also includes a Location header with that page, so that your application can send the user there. For more information, see Custom login page and logout.
• Requests without a Sec-Fetch-Mode header, such as curl requests, are treated as navigation requests and redirected.

The permissive value of the credentials field changes these rules. Unauthenticated requests that are not navigations continue to the next policies instead of receiving a 401 response. A request without a Sec-Fetch-Mode header counts as a navigation only when its Accept header includes text/html. For more information, see Bearer tokens for API clients.

Session cookies

Review the following details about session cookies.

• Session cookies are encrypted and tamper-proof.
• Session cookie payloads are compressed only when the result is smaller. Compression helps ID tokens with large claim sets fit in browser cookie limits.
• Session cookies written before compression continue to decode.
• A protected response can include its own cookies and the OIDC session cookie.
• The gateway always requests the openid scope to obtain an ID token.
• A session cookie lasts 7 days by default. To change the lifetime, set sessionTtl to a duration such as 12h. The session never outlives the expiry of the ID token.
• If the identity provider returns a refresh token, a separate encrypted cookie stores it. The browser session refreshes when the ID token expires. Add the offline_access scope when your provider requires that scope to issue refresh tokens.
• The refresh response must include a new ID token for the same sub claim. If the provider omits the ID token, the user must sign in again. If the provider returns an ID token for a different subject, the user must sign in again.
• The gateway uses PKCE automatically to protect against authorization code interception.

Configuration

Add the oidc policy to a route to protect it with browser-based OIDC authentication.

Agentgateway requires the OIDC_COOKIE_SECRET environment variable to encrypt session cookies when an oidc policy is configured. Set it to a random value before you start the gateway, such as in the following example.

export OIDC_COOKIE_SECRET="$(python3 -c 'import os; print(os.urandom(32).hex())')"

You can configure the oidc policy in the UI or in your configuration file.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  policies:
    oidc:
      issuer: http://localhost:7080/realms/agentgateway
      clientId: agentgateway-browser
      clientSecret: agentgateway-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    oidc:
      issuer: http://localhost:7080/realms/agentgateway
      clientId: agentgateway-browser
      clientSecret: agentgateway-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
routes:
- backends:
  - host: localhost:18080
  matches:
  - path:
      pathPrefix: /
  policies:
    oidc:
      issuer: http://localhost:7080/realms/agentgateway
      clientId: agentgateway-browser
      clientSecret: agentgateway-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email

Keycloak example

Review the following example for a Keycloak IdP.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  policies:
    oidc:
      issuer: http://keycloak.example.com/realms/myrealm
      clientId: agentgateway-browser
      clientSecret: my-client-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    oidc:
      issuer: http://keycloak.example.com/realms/myrealm
      clientId: agentgateway-browser
      clientSecret: my-client-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
routes:
- backends:
  - host: localhost:18080
  matches:
  - path:
      pathPrefix: /
  policies:
    oidc:
      issuer: http://keycloak.example.com/realms/myrealm
      clientId: agentgateway-browser
      clientSecret: my-client-secret
      redirectURI: http://localhost:3000/oauth/callback
      scopes:
      - profile
      - email

frontendPolicies:
  accessLog:
    add:
      user.id: jwt.sub
      user.email: jwt.email
binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTP
    routes:
    - name: app
      matches:
      - path:
          pathPrefix: /
      backends:
      - host: localhost:18080
      policies:
        oidc:
          issuer: http://localhost:7080/realms/agentgateway
          clientId: agentgateway-browser
          clientSecret: agentgateway-secret
          redirectURI: http://localhost:3000/oauth/callback
          scopes:
          - profile
          - email

Custom login page and logout

Use login to show your application’s sign-in page before the identity provider flow, and logout to add a sign-out control that clears the gateway session. You can configure either block independently. The following example enables both; see Fields for defaults and path requirements.

policies:
  oidc:
    issuer: http://localhost:7080/realms/agentgateway
    clientId: agentgateway-browser
    clientSecret: agentgateway-secret
    redirectURI: http://localhost:3000/oauth/callback
    login:
      path: /auth/login
      redirect: /login
    logout:
      path: /auth/logout
      redirect: /login

For this example, serve /login and its assets on public routes that bypass OIDC. On that page, link to /auth/login and preserve the returnTo query parameter. For example, /login?returnTo=%2Fapp uses /auth/login?returnTo=%2Fapp as its sign-in link.

Use a same-origin POST form for logout, such as the following example.

<form method="post" action="/auth/logout">
  <button type="submit">Sign out</button>
</form>

Bearer tokens for API clients

By default, an OIDC policy accepts only the browser session that its login flow creates. Set the credentials field to let non-browser clients, such as a CLI or a script, call the same routes. Use one of the following values.

Accept ID tokens from the OIDC provider

Use sessionOrBearer when your API clients can get an ID token from the same identity provider and client as your browser users.

1. Add credentials: sessionOrBearer to the oidc policy.

   policies:
     oidc:
       issuer: http://localhost:7080/realms/agentgateway
       clientId: agentgateway-browser
       clientSecret: agentgateway-secret
       redirectURI: http://localhost:3000/oauth/callback
       credentials: sessionOrBearer

2. Get an ID token for the clientId from your identity provider, and send the token in the Authorization header. The policy checks the token signature against its JWKS, and checks that the token is not expired. The iss claim must match issuer and the aud claim must include clientId. Access tokens usually have a different audience, so send the ID token, not an access token.

   curl -i http://localhost:3000/ -H "Authorization: Bearer $ID_TOKEN"

The policy handles each request according to its Authorization header.

Pass API clients to other authentication policies

Use permissive when browsers log in with OIDC, but API clients use other credentials. Examples are tokens from another issuer, API keys, and MCP authentication. In permissive mode, the OIDC policy handles requests as follows.

• A browser session or a valid ID token authenticates the request, as with sessionOrBearer.
• An invalid or unrecognized bearer token is not rejected. The policy leaves the Authorization header in place for a later policy to validate.
• A browser navigation without a session starts the login flow, as with the other values. A request is a navigation when its Sec-Fetch-Mode header is navigate. If the request has no Sec-Fetch-Mode header, the Accept header decides: a request that accepts text/html is a navigation.
• Any other request without a session continues to the next policies unauthenticated. The OIDC policy does not send a 401 response, so curl requests without an Accept: text/html header are not redirected to log in.

The following example accepts browser sessions through OIDC and CLI tokens from a second issuer through jwtAuth. The jwtAuth policy uses its default optional mode, which validates a token when one is present. The authorization rule rejects requests that neither policy authenticated with a 403 Forbidden response.

policies:
  oidc:
    issuer: http://localhost:7080/realms/agentgateway
    clientId: agentgateway-browser
    clientSecret: agentgateway-secret
    redirectURI: http://localhost:3000/oauth/callback
    credentials: permissive
  jwtAuth:
    issuer: https://cli.example.com
    audiences: [my-app-cli]
    jwks:
      url: https://cli.example.com/.well-known/jwks.json
  authorization:
    rules:
    - allow: has(jwt.sub)

Fields

All login and logout endpoint and redirect values must be safe local paths. The built-in UI manages its own /ui/login, /api/auth/login, and /api/auth/logout endpoints and rejects login or logout under ui.policies.oidc.

Access log enrichment

After setting up OIDC browser authentication, you can use JWT claims from the OIDC session in access logs. Add a frontend policy such as the following example.

frontendPolicies:
  accessLog:
    add:
      user.id: jwt.sub
      user.email: jwt.email

Learn more

• Keycloak integration
• Auth0 integration
• MCP authentication for MCP-specific OAuth flows