OIDC Validation

What it does

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).

Filter Configuration Options

Name	Type	Default	Example	Description	Required
provider	string	n/a	https://accounts.google.com	A url to an identity provider which is used to verify the access token.	true
enforce	boolean	false	false	Whether or not to reject the request if the token is invalid	false
enforceResponseCode	int	403	404	If enforce is true, the status code to return on if a token is invalid	false
accessToken.location	enum[header, cookie, queryString, metadata]	header	header	A location on the incoming request where the filter should look for an access token.	true
accessToken.key	string	n/a	"Authorization"	A key to use to look up the access token in the specified location.	true
accessToken.metadataFilter	string	n/a	"gm.ensure_variables"	The name of the filter to read dynamic metadata from. Required if accessToken.location=metadata	false
userInfo.location	enum[header, cookie, queryString, metadata]	header	header	A location on the incoming request where the filter should set user attributes after the token has been validated.	false
userInfo.key	string	n/a	"Identity"	A key to use when setting user attributes on the incoming request.	false
userInfo.claims	array	n/a	[sub, name, email]	A list of claims to be plucked from the user info object and set in . If no claims are specified, all claims are included	false

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

When the userinfo object is set in cookies, headers, or query strings, it is encoded using url.PathEscape, e.g.:

%7B%22locale%22:%22en%22%2C%22name%22:%22Jane%20Doe%22%2C%22picture%22:%22https:%2F%2Flh3.google.com%2Fa-%2FAAuE7mCvreSfS1y4BWgFmFHrRJWMYXcYRBmRmPMNBM5qPg%22%2C%22sub%22:%22123223497837f61404%22%7D

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 request (to be used by the upstream service), while cookies are set on both the request and response (to be used by the browser).