Skip to main content

Updating claims at token refresh

The Hydra OAuth2 and OpenID Connect server comes with a mechanism that allows updating id_token and access_token when a registered client sends a token refresh request. The flow is realized by calling the defined refresh token hook endpoint which returns updated data.

If the data provided by the webhook is different from the data the client sends, the webhook overwrites the session data with a new set.

note

The hook is called before any other logic is executed. If the hook execution fails, the entire token refresh flow fails and the refresh_token remains unused.

Configuration​

To enable the token refresh webhook, configure the oauth2.refresh_token_hook key in the Hydra configuration:

oauth2:
  refresh_token_hook: https://my-example.app/token-refresh-hook

If you're running Hydra locally, you can set this value by exporting the refresh token hook endpoint URL as an environment variable. Run this command:

export OAUTH2_REFRESH_TOKEN_HOOK=value

Webhook configuration​

The refresh token hook endpoint must accept the following payload format:

{
  "subject": "foo",
  "client_id": "bar",
  "session": {
    "id_token": {
      "id_token_claims": {
        "jti": "jti",
        "iss": "http://localhost:4444/",
        "sub": "foo",
        "aud": ["bar"],
        "iat": 1234567,
        "exp": 1234567,
        "rat": 1234567,
        "auth_time": 1234567,
        "nonce": "",
        "at_hash": "",
        "acr": "1",
        "amr": [],
        "c_hash": "",
        "ext": {}
      },
      "headers": {
        "extra": {
          "kid": "key-id"
        }
      },
      "username": "username",
      "subject": "foo",
      "expires_at": 1234567
    },
    "extra": {},
    "client_id": "bar",
    "consent_challenge": "",
    "exclude_not_before_claim": false,
    "allowed_top_level_claims": [],
    "kid": "key-id"
  },
  "requester": {
    "client_id": "bar",
    "granted_scopes": ["openid", "offline"],
    "granted_audience": [],
    "grant_types": ["refresh_token"]
  },
  "granted_scopes": ["openid", "offline"],
  "granted_audience": []
}
note

session represents the consent session, along with the data that was passed to the Accept Consent Request in the id_token field. requester is the token request context.

To update the data, the webhook must return a 200 OK response and the updated session data in the following format:

{
  "session": {
    "access_token": {
      "foo": "bar"
    },
    "id_token": {
      "bar": "baz"
    }
  }
}
note

The token subject is never overridden.

Updated tokens​

The following examples show fragments of tokens issued after refreshing:


{
  "aud": [
    "my_client"
  ],
  "auth_time": 1647427485,
  "bar": "baz",
  "iss": "http://ory.hydra.example/",
  "sub": "foo@bar.com"
}

Rejecting token refresh​

To gracefully reject token contents update, the hook must return a 403 Forbidden response. Any other response results in a failure of the token update and, as a result, failure of the entire token refresh flow.