More OAuth features

Review more OAuth features that you can use, such as cookie options, and storing sessions in Redis, and logout path.

About

Review some common options that you might want to use in your OAuth external auth policies for authorization codes. For more information, see the .

Basic
Boolean expression for multiple OAuth types
Cookies
Store sessions in Redis
Logout URL
Forward the ID token

Basic configuration example

The example configuration snippets on this page are based on the following external auth configuration for .

Boolean expression for multiple OAuth types

You can use both authorization code and access token validation types of OAuth2 together by using the booleanExpr setting in your auth config.

Example boolean expression policy

The following example sets up two types of OAuth, a jwt config for access token validation and an oidc config for authorization code. It also includes an opa config that refers to a Rego policy that checks the value of a claim in the access token. By setting the boolean expression (entAuth.booleanExpr: (jwt || oidc) && opa), the request must successfully complete one of those OAuth options. Then, with the token returned from the authentication, the external auth server can use OPA to process the Rego rules to verify that request’s token is authorized before granting access.

This way, you can create modular, reusable auth configs that are only checked when needed. In the example, if the jwt access token validation succeeds, the oidc flow does not start, making the request more efficient.

Review the following table to understand this configuration. For more information, see the .

Setting	Description
`booleanExpr`	Specify how to combine multiple auth configs by using logical operators such as AND (`&&`), OR (`\|\|`), and NOT (`!`). The example sets `(jwt \|\| oidc) && opa`, which requires either the `jwt` or `oidc` auth config to succeed, and then the `opa` config to succeed. To understand the possible outcomes of this expression, see the following tables of expected responses.
`configs.name: jwt`	The auth config section to use to validate access through a provided JWT. The example is named `jwt` and configures a remote JWKS from an issuer, as well as takes certain claims from the JWT to append as headers to the request for subsequent processing by the OPA policy. For more information, refer to the API docs or any .
`configs.name: oidc`	The auth config section to use to validate access through a user-initiated SSO flow. The example is named `oidc` and sets up issuer information such as the issuer app and client ID. For more information, refer to the API docs or any .
`configs.name: opa`	The auth config section for OPA that refers to an Rego policy that you previously created, often through a configmap. The example is named `opa` and refers to an `allow` rule in a `test` package in the `data` of a configmap named `httpbin-rego` in the `httpbin` namespace. For more information, refer to the API docs or any .

Example responses

The following tables show the expected responses for different authentication scenarios that use the example auth config with the (jwt || oidc) && opa boolean expression.

User authentication from a browser-based SSO via authorization code

Scenario	Boolean expression execution	Expected response
JWT not provided User authentication succeeds Claims include required fields per OPA policy	`jwt` returns 401 `oidc` returns 200 `opa` returns 200	✅ 200 Success
JWT not provided User authentication succeeds Claims do NOT include required fields per OPA policy	`jwt` returns 401 `oidc` returns 200 `opa` returns 403	❌ 403 Forbidden
JWT not provided User authentication succeeds No claims returned or claims fail	`jwt` returns 401 `oidc` returns 200 `opa` returns 403	❌ 403 Forbidden
JWT not provided User authentication fails No claims because authentication fails	`jwt` returns 401 `oidc` returns 403 `opa` is skipped	❌ 403 Forbidden

Programmatic access from a JWT via access token validation

Scenario	Boolean expression execution	Expected response
Valid JWT in expected header No user authentication JWT claims include required fields per OPA policy	`jwt` returns 200 `oidc` is skipped `opa` returns 200	✅ 200 Success
Valid JWT in expected header No user authentication JWT claims do NOT include required fields per OPA policy	`jwt` returns 200 `oidc` is skipped `opa` returns 403	❌ 403 Forbidden
JWT not provided No user authentication No claims because no JWT or authentication	`jwt` returns 403 `oidc` returns 403 `opa` is skipped	❌ 403 Forbidden
Expired JWT No user authentication Claims are irrelevant because JWT is expired	`jwt` returns 401 `oidc` is skipped `opa` is skipped	❌ 401 Unauthorized
Expired JWT User authentication fails Claims are irrelevant because authentication fails	`jwt` returns 401 `oidc` returns 401 `opa` is skipped	❌ 401 Unauthorized`*`

* In previous versions, the external auth server returned a generic 403 response. If needed, you can keep this old behavior by setting the following Helm value when you upgrade Solo Enterprise for kgateway: extAuthService.extraEnvs.DONT_MERGE_DENIED_AUTH_RESPONSES.value=true.

Cookies

Store cookies so that your users do not have to authenticate for each subsequent API request. You can customize cookie behavior, such as to change the path, age, or domain.

Review the following table to understand this configuration. For more information, see the .

Setting	Description
`notSecure`	Set to `true` to use an insecure cookie. Insecure cookies can be used for demos and testing purposes, but are not recommended for production.
`maxAge`	The max age of the cookie in seconds. Leave unset for a default of `30` days (`2592000` seconds). To disable cookie expiry, set to `0`.
`path`	The path of the cookie. If unset, the path defaults to `"/"`. To avoid setting a path, enter `""`. If you use a directory separator, subdirectories are matched as well. For example, `/docs` matches request paths `/docs`, `/docs/`, and `/docs/gloo-mesh/`, but does not match `/`, `/docset/`, or `/en/docs`.
`domain`	The domain to which the cookie is sent. By default, this value is empty and matches only the domain of the originating request, not including subdomains. The default setting works if the originating request and the redirect target of the identity provider (IdP) match. However, you must set this value if the IdP redirects the request to another subdomain. For example, consider the case where the virtual gateway matches requests to `*.example.com`, and the IdP redirects the auth requests to `subdomain.example.com`. If you do not set the `domain` value, requests fail that come in on subdomains like `docs.example.com`. The user is still redirected to the IdP login as expected. However, because the request originates from a different subdomain, the token-bearing cookie is not sent back to the proxy. Therefore, authentication fails. In contrast, if you set `domain` to `example.com`, authentication succeeds because the cookie is sent to any subdomain of `example.com`.

Store sessions in Redis

By default, the OIDC tokens are saved in a secure, client-side cookie. Instead, you can set up Solo Enterprise for kgateway to store the OIDC tokens in Redis. Solo Enterprise for kgateway generates a random session ID for the user’s cookie that is stored client-side.

Review the following table to understand this configuration. For more information, see the .

Setting	Description
`cookieName`	The name of the cookie to set and store the session ID. If unset, the default name is `"__session”`.
`options.host`	The address of the Redis instance to use, in the format `address:port` or `unix://path-to-unix.sock`.
`options.db`	The Redis database to use, indexed to start at `0`. This example does not specify a database, so the default `0` is used.
`options.poolSize`	The maximum number of connections to establish at once. This example does not specify a pool size, so the default of `10` connections per CPU is used.

Logout URL

You can set a logout URL. When users access this URL, their user session and cookie are deleted. If you don’t set up a logout URL, logout functionality is disabled.

Review the following table to understand this configuration. For more information, see the .

Do not set up your app to do anything on the logoutPath path, or you might notice unexpected results!

Setting	Description
`logoutPath`	Enter a path relative to the `appUrl` for users to log out of an OIDC session. When this URL is accessed, the user session information is deleted, and a `200 OK` response is returned.
`afterLogoutURL`	By default, users are returned to the URL that is set in `appURL`. To change this behavior, add a full URL in this field, such as `http://localhost:8080/home/`.

Front channel logout

Front channel logout is a security mechanism that is used in the context of Single Sign-On (SSO) and Identity and Access Management (IAM) systems to ensure that when a user logs out of one app or service, they are also automatically logged out of the Identity Provider (IdP) and therefore all related apps and services in a secure and synchronized manner. Without front channel logout, the user is logged out of the requested app only.

You can add a front channel logout path in the AuthConfig that configures OIDC authorization code for your app as shown in the following example AuthConfig. Note that the frontChannelLogout path must be set in your IdP for your app. It must also be different from the logoutPath that you set to log out of your app.

The way you configure a front channel logout path depends on the IdP that you use. For more information, see the documentation for your IdP.

apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: oauth-keycloak
  namespace: gloo-system
spec:
  configs:
    - oauth2:
        oidcAuthorizationCode:
          appUrl: "http://portal.example.com"
          callbackPath: /v1/login
          logoutPath: /v1/logout
          frontChannelLogout:
            path: /front_channel_logout
          clientId: $KEYCLOAK_CLIENT
          clientSecretRef:
            name: oauth-keycloak
            namespace: gloo-system
          issuerUrl: "$KEYCLOAK_URL/realms/$REALM"
          session:
            failOnFetchFailure: true
            cookie:
              allowRefreshing: true
          scopes:
          - openid
          headers:
            idTokenHeader: id_token

When the user goes to the configured logoutPath, a request is sent to the IdP to log the user out of the app. Because you also set a frontChannelLogout path that matches the setting in the IdP, the IdP initiates the logout from every app that the user is currently logged in to.

Forward the ID token

Configure Solo Enterprise for kgateway to forward the ID token to the destination in a header after successful authentication. For example, your app might need the ID token for further processing.

Review the following table to understand this configuration. For more information, see the .

Setting	Description
`idTokenHeader`	The header name to use to forward the ID token. This example sets the header name to `x-token`.

Authorization code Keycloak as an IdP