On this page

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 API reference in the Gloo Edge docs.

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 Google accounts.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: google-auth
  namespace: httpbin
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        appUrl: http://extauth.example.com:8080
        callbackPath: /callback
        clientId: ${CLIENT_ID}
        clientSecretRef:
          name: google
          namespace: httpbin
        issuerUrl: https://accounts.google.com
        scopes:
        - email
        session:
          cookieOptions:
            notSecure: true

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 (glooAuth.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.

  kubectl apply -f - <<EOF
apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: httpbin-test
  namespace: httpbin
spec:
  # Logical expression to specify how to execute multiple auth configs
  booleanExpr: (jwt || oidc) && opa
  # Auth configs
  configs:
  # Auth config for JWT access token validation
  - name: jwt
    oauth2:
      accessTokenValidation:
        jwt:
          remoteJwks: 
            url: <jwks_url>
          issuer: <issuer_url>
        claimsToHeaders:
        - claim: groups
          header: x-groups
        # Optional, provider-specific section
        # such as for distributed claims with Microsoft Entra ID
        azure:
          claimsCachingOptions:
            host: redis.gloo-mesh.svc.cluster.local:6379
          clientId: $EXTAUTH_CLIENT_ID
          clientSecret:
            name: microsoft-extauth
            namespace: gloo-mesh
          tenantId: $EXTAUTH_TENANT_ID      
  # Auth config for authorization code OIDC
  - name: oidc
    oauth2:
      oidcAuthorizationCode:
        appUrl: $APP_URL
        # Optional, provider-specific options such as
        # for Microsoft Entra ID
        azure:
          claimsCachingOptions:
            host: redis.gloo-mesh.svc.cluster.local:6379
          clientId: $EXTAUTH_CLIENT_ID
          clientSecret:
            name: microsoft-extauth
            namespace: gloo-mesh
          tenantId: $EXTAUTH_TENANT_ID
        callbackPath: /callback
        clientId: $HTTPBIN_APP_CLIENT_ID
        clientSecretRef:
          name: microsoft-httpbin
          namespace: gloo-mesh
        issuerUrl: $HTTPBIN_APP_ISSUER_URL
        scopes:
        - $HTTPBIN_APP_SCOPE
        - profile
        - email
        - openid
        session:
          redis:
            cookieName: oidcsession
            options:
              host: redis.gloo-mesh.svc.cluster.local:6379
  # Auth config for OPA
  - name: opa
    opaAuth:
      modules:
      - name: httpbin-rego
        namespace: httpbin
      query: data.test.allow == true
EOF

Review the following table to understand this configuration. For more information, see the API reference in the Gloo Edge docs.

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 guide that uses access token validation.
`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 guide that uses authorization codes.
`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 OPA guide.

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

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.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: google-auth
  namespace: httpbin
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        session:
          cookieOptions:
            notSecure: true
            maxAge: 3600
            path: "/docs"
            domain: "example.com"

Review the following table to understand this configuration. For more information, see the API reference in the Gloo Edge docs.

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 Gloo Gateway to store the OIDC tokens in Redis. Gloo Gateway generates a random session ID for the user’s cookie that is stored client-side.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: google-auth
  namespace: httpbin
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        session:
          redis:
            cookieName: session
            options:
              host: redis.gloo-system.svc.cluster.local:6379

Review the following table to understand this configuration. For more information, see the API reference in the Gloo Edge docs.

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`. The example stores sessions in the default Redis instance that runs in the `gloo-system` namespace.
`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.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: google-auth
  namespace: httpbin
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        logoutPath: /logout
        afterLogoutURL: http://localhost:8080/home/

Review the following table to understand this configuration. For more information, see the API reference in the Gloo Edge docs.

warning

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/`.

Forward the ID token

Configure Gloo Gateway 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.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: google-auth
  namespace: httpbin
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        headers:
          idTokenHeader: "x-token"

Review the following table to understand this configuration. For more information, see the API reference in the Gloo Edge docs.

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

More OAuth features

About link

Basic configuration example link

Boolean expression for multiple OAuth types link

Example boolean expression policy link

Example responses link

Cookies link

Store sessions in Redis link

Logout URL link

Forward the ID token link

About

Basic configuration example

Boolean expression for multiple OAuth types

Example boolean expression policy

Example responses

Cookies

Store sessions in Redis

Logout URL

Forward the ID token