OIDC Validation

The oidc-validation filter handles bearer token (aka access token) validation. It can be configured to check for bearer tokens in headers, cookies, or query parameters. If it finds a token, it validates the token with the provided IdP and sets the desired user attributes into a configurable header. If the token is invalid, it strips it from the request so that it can be dealt with upstream. If enforce is set to true, the request will be rejected with a 403 (configurable).

Access tokens

An access token is an opaque primary key that allows the bearer of the token to retrieve information from an identity provider on behalf of a user. This filter validates legitimacy of a token by making a request to the identity provider’s userinfo endpoint with the token in an Authorization header. If the request is successful, that means the token is valid.

Note that the access token must have a scope of openid to be used with this filter.

Setting user attributes

When an access token is generated, “scopes” are defined. These scopes define what resources will be available when the token is used to access protected endpoints. Each scope returns a set of user attributes, which are called claims.

Validating an access token against an identity provider’s userinfo endpoint returns an object containing these claims. This filter allows you to optionally persist them after a successful validation. To tell the filter to save claims, specify a userInfo block with a location and key. This will save the whole object in a header with a key of Identity:

userInfo:
    location: header
    key: "Identity"

Because a userinfo object is potentially very large, it is recommended that you specify the exact claims you want persisted in the request:

userInfo:
    location: header
    key: "Identity"
    claims:
        - sub
        - picture
        - name
        - locale

Dynamic metadata

If user info is only intended to be used in the filter chain, it is recommended to use dynamic metadata. Dynamic metadata is a way to share data between filters in the same filter chain.

Here is an example of setting dynamic metadata:

userInfo:
    location: metadata
    key: "userinfo"
    claims:
        - sub
        - picture
        - name
        - locale

This will put sub, picture, name, and locale into a dynamic metadata struct using the gm.oidc-validation namespace with a key of metadata. Here’s an example from the api proxy logs:

dynamicMetadata: filter_metadata {
  key: "gm.oidc-validation"
  value {
    fields {
      key: "userinfo"
      value {
        struct_value {
          fields {
            key: "locale"
            value {
              string_value: "en"
            }
          }
          fields {
            key: "name"
            value {
              string_value: "Jane Doe"
            }
          }
          fields {
            key: "picture"
            value {
              string_value: "https://lh3.googleusercontent.com/a-/AOh14GgU-VFsadfasdfcz2H-yv0iXTvngT7256RpGYpg2"
            }
          }
          fields {
            key: "sub"
            value {
              string_value: "10184666432509641"
            }
          }
        }
      }
    }
  }
}

Note on setting claims in cookies

The filter is able to store claims in headers, query parameters, or cookies. However it should be noted that cookie persistence behaves slightly differently since there is a browser involved. Headers and query parameters are set on the equest (to be used by the upstream service), while cookies are set on both the request and response (to be used by the browser).

Per-Route configuration

{
  "enforce": <bool>,
  "enforceResponseCode": <int>,
  "userInfoClaims": [string],
  "overwriteClaims": <bool>
}

If overwriteClaims is set to true, the claims provided in userInfoClaims will overwrite the userInfo.Claims for that route, otherwise they will be appended.