OAuth2 and OpenID Connect

OAuth2 and OpenID Connect are both pervasive technologies in modern identity systems. While verification of JSON web tokens issued by these systems is documented in the policy reference, the policy examples below aim to cover some other common use cases.

Metadata discovery

Rather than storing endpoints and other metadata as part of policy data, the authorization server metadata endpoint may be queried for this data.

  1. package oidc
  3. issuers = {"https://issuer1.example.com", "https://issuer2.example.com"}
  5. metadata_discovery(issuer) = http.send({
  6.     "url": concat("", issuers[issuer], "/.well-known/openid-configuration",
  7.     "method": "GET",
  8.     "force_cache": true,
  9.     "force_cache_duration_seconds": 86400 # Cache response for 24 hours
  10. }).body
  12. claims := jwt.decode(input.token)[1]
  13. metadata = metadata_discovery(claims.iss)
  15. jwks_endpoint := metadata.jwks_uri
  16. token_endpoint := metadata.token_endpoint

Token verification using JWKS endpoint

Below example uses the keys published at the JWKS endpoint of the authorization server for token verification.

  1. package oidc
  3. jwks_request(url) = http.send({
  4.     "url": url,
  5.     "method": "GET",
  6.     "force_cache": true,
  7.     "force_cache_duration_seconds": 3600 # Cache response for an hour
  8. })
  10. jwks = jwks_request("https://authorization-server.example.com/jwks").body
  12. verified = io.jwt.verify_rs256(input.token, json.marshal(jwks))

Key rotation

Use the keys published at the JWKS endpoint of the authorization server for token verification, with key rotation taken into account.

  1. package oidc
  3. jwks_request(url) = http.send({
  4.     "url": url,
  5.     "method": "GET",
  6.     "force_cache": true,
  7.     "force_cache_duration_seconds": 3600
  8. })
  10. jwt_unverified := io.jwt.decode(input.token)
  11. jwt_header := jwt_unverified[0]
  13. jwks = jwks_cached {
  14.     jwks_cached := jwks_request("https://authorization-server.example.com/jwks").body
  15.     jwt_header.kid == jwks_cached.keys[_].kid
  16. } else = jwks_rotated {
  17.     # Add query param to second request to avoid both getting the same cache key
  18.     jwks_rotated := jwks_request("https://authorization-server.example.com/jwks?r=1").body
  19. }
  21. jwt_verified = jwt_unverified {
  22.     io.jwt.verify_rs256(input.token, json.marshal(jwks))
  23. }
  25. claims_verified := jwt_verified[1]

Token retrieval

Programmatically obtain an OAuth2 access token following the client credentials or resource owner password credential flow.

  1. package oauth2
  3. token = t {
  4.     response := http.send({
  5.         "url": "https://authorization-server.example.com/token",
  6.         "method": "POST",
  7.         "headers": {
  8.             "Content-Type": "application/x-www-form-urlencoded",
  9.             "Authorization": concat(" ", [
  10.                 "Basic",
  11.                 base64.encode(sprintf("%v:%v", [client_id, client_secret]))
  12.             ]),
  13.         },
  14.         # To use the resource owner password credentials flow, change grant_type
  15.         # to "password" and add username and password parameters to the body
  16.         "raw_body": "grant_type=client_credentials",
  17.         "force_cache": true,
  18.         "force_cache_duration_seconds": 3595, # Given an `expires_in` value of 3600
  19.     })
  20.     response.status_code == 200
  22.     t := response.body.access_token
  23. }