Skip to content

Commit

Permalink
fix:update docs according to the latest changes in hydra
Browse files Browse the repository at this point in the history
  • Loading branch information
@sgal
sgal committed Mar 25, 2023
1 parent 26f66b9 commit a025d2a
Showing 1 changed file with 98 additions and 80 deletions.
178 changes: 98 additions & 80 deletions docs/hydra/guides/updating-claims-at-refresh.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,36 +27,13 @@ The hook is called before any other logic is executed. If the hook execution fai

## Configuration

You can use hooks feature with the following grant types:

- `authorization_code`
- `client_credentials`
- `refresh_token`
- `jwt-bearer` - see [RFC7523](https://www.rfc-editor.org/rfc/rfc7523)
You can use hooks feature with all grant types.

Use the Ory CLI with following keys to enable this feature:

```shell title="Enable the authorization code hook"
ory patch oauth2-config {project.id} \
--replace "/oauth2/authorization_code_hook=\"https://my-example.app/authorization-code-hook\"" \
--format yaml
```

```shell title="Enable the client credentials token hook"
ory patch oauth2-config {project.id} \
--replace "/oauth2/client_credentials_hook=\"https://my-example.app/client-credentials-hook\"" \
--format yaml
```

```shell title="Enable the refresh token hook"
ory patch oauth2-config {project.id} \
--add "/oauth2/refresh_token_hook=\"https://my-example.app/token-refresh-hook\"" \
--format yaml
```

```shell title="Enable the jwt-bearer token hook"
```shell title="Enable the generic token hook"
ory patch oauth2-config {project.id} \
--replace "/oauth2/jwt_bearer_hook=\"https://my-example.app/jwt-bearer-hook\"" \
--add "/oauth2/token_hook=\"https://my-example.app/token-hook\"" \
--format yaml
```

Expand All @@ -66,99 +43,65 @@ The token hook endpoint must accept the following payload format:

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

:::note

`session` represents the consent session, along with the data that was passed to the
[Accept Consent Request](https://www.ory.sh/docs/hydra/reference/api#operation/acceptConsentRequest) in the `id_token` field.
`requester` is the token request context.
`request` is the token request context.

:::

### Requester payload

For `client_credentials` and `jwt-bearer` grant types, the entire payload that you send to the `/token` endpoint will also be sent
to the configured webhook URL.
For `jwt-bearer` grant type the `assertion` value is also sent to the webhook URL.

Here's the format of the `requester.payload` field for each grant type:
Here's the format of the `request.payload:

```mdx-code-block
<Tabs>
<TabItem value="client_credentials" label="client_credentials" default>
<CodeBlock language="json">{`
{
"grant_type": [
"client_credentials"
],
"audience": ["my-api"],
"scope": ["user:profile:read"]
}
`}</CodeBlock>
</TabItem>
<TabItem value="urn:ietf:params:oauth:client-assertion-type:jwt-bearer" label="urn:ietf:params:oauth:client-assertion-type:jwt-bearer">
<CodeBlock language="json">{`
```json
{
"grant_type": [
"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
],
"assertion": ["eyJhbGciOiJIUzI..."],
"scope": ["user:profile:read"]
"assertion": ["eyJhbGciOiJIUzI..."]
}
`}</CodeBlock>
</TabItem>
</Tabs>
```

:::note

For `authorization_code` and `refresh_token` grant types, the `requester.payload` is always empty.
For `authorization_code` and `refresh_token` grant types, the `request.payload` is always empty.

:::

Expand Down Expand Up @@ -235,3 +178,78 @@ failure of the token update and, as a result, failure of the entire token flow.

If a webhook for `refresh_token` grant type fails with a non-graceful result, the refresh flow will also fail and the supplied
`refresh_token` will remain unused.

## Legacy webhook implementation

There is an old version of the webhook feature built specifically for the `refresh_token` grant type. We recommend using the
generic webhook feature because the old one will soon be deprecated.

Use the Ory CLI with following keys to enable this feature:

```shell title="Enable the refresh token hook"
ory patch oauth2-config {project.id} \
--add "/oauth2/refresh_token_hook=\"https://my-example.app/token-refresh-hook\"" \
--format yaml
```

### Webhook payload

The legacy webhook feature works the same way as the new one, but has a different payload that is sent to the webhook URL.

The `refresh_token` hook endpoint must accept the following payload format:

```json
{
"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

If you enable both legacy and the new webhook features, both will be executed for the `refresh_token` grant type. The results of
both webhooks will be applied onto the session. In case of conflict, result of the new webhook will take priority.

:::

0 comments on commit a025d2a

Please sign in to comment.