From 9c37f39d43bbb6c8c9ca01c79409f59b43335259 Mon Sep 17 00:00:00 2001 From: Livio Spring Date: Tue, 16 Aug 2022 14:49:37 +0200 Subject: [PATCH] docs: better distinct JWT Profile grant and assertion (#4201) docs: update JWT Profile grant --- docs/docs/apis/openidoauth/authn-methods.md | 16 +++++----- docs/docs/apis/openidoauth/endpoints.md | 30 +++++++++---------- .../guides/integrate/access-zitadel-apis.md | 2 +- docs/docs/guides/integrate/serviceusers.md | 2 +- 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/docs/apis/openidoauth/authn-methods.md b/docs/docs/apis/openidoauth/authn-methods.md index 7defdfba75..fdcd0ce71e 100644 --- a/docs/docs/apis/openidoauth/authn-methods.md +++ b/docs/docs/apis/openidoauth/authn-methods.md @@ -15,7 +15,7 @@ Given the client_id `78366401571920522@amce` and client_secret `veryweaksecret!` ## JWT with Private Key -When using `private_key_jwt` for token or introspection endpoints, provide a JWT as assertion generated with the following structure and signed with a downloaded key: +When using `private_key_jwt` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`) for token or introspection endpoints, provide a JWT as assertion generated with the following structure and signed with a downloaded key: --- @@ -43,13 +43,13 @@ Key JSON JWT -| Claim | Example | Description | -|:------|:------------------------------|:----------------------------------------------------------------------------------------------------------------| -| aud | `"{your_domain}"` | String or Array of intended audiences MUST include ZITADEL's issuing domain | -| exp | `1605183582` | Unix timestamp of the expiry | -| iat | `1605179982` | Unix timestamp of the creation singing time of the JWT, MUST NOT be older than 1h | -| iss | `"78366401571920522@acme"` | String which represents the requesting party (owner of the key), normally the `clientID` from the json key file | -| sub | `"78366401571920522@acme"` | The subject ID of the application, normally the `clientID` from the json key file | +| Claim | Example | Description | +|:------|:---------------------------|:----------------------------------------------------------------------------------------------------------------| +| aud | `"{your_domain}"` | String or Array of intended audiences MUST include ZITADEL's issuing domain | +| exp | `1605183582` | Unix timestamp of the expiry | +| iat | `1605179982` | Unix timestamp of the creation singing time of the JWT, MUST NOT be older than 1h | +| iss | `"78366401571920522@acme"` | String which represents the requesting party (owner of the key), normally the `clientID` from the json key file | +| sub | `"78366401571920522@acme"` | The subject ID of the application, normally the `clientID` from the json key file | ```JSON { diff --git a/docs/docs/apis/openidoauth/endpoints.md b/docs/docs/apis/openidoauth/endpoints.md index 11fb875df4..d23aa46c15 100644 --- a/docs/docs/apis/openidoauth/endpoints.md +++ b/docs/docs/apis/openidoauth/endpoints.md @@ -86,7 +86,7 @@ no additional parameters required | Parameter | Description | | ------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id_token_hint | Valid `id_token` (of an existing session) used to identity the subject. **SHOULD** be provided when using prompt `none`. | -| login_hint | A valid logon name of a user. Will be used for username inputs or preselecting a user on `select_account`. Be sure to encode the hint correctly using url encoding (especially when using `+` or alike in the loginname) | +| login_hint | A valid logon name of a user. Will be used for username inputs or preselecting a user on `select_account`. Be sure to encode the hint correctly using url encoding (especially when using `+` or alike in the loginname) | | max_age | Seconds since the last active successful authentication of the user | | nonce | Random string value to associate the client session with the ID Token and for replay attacks mitigation. **MUST** be provided when using **implicit flow**. | | prompt | If the Auth Server prompts the user for (re)authentication.
no prompt: the user will have to choose a session if more than one session exists
`none`: user must be authenticated without interaction, an error is returned otherwise
`login`: user must reauthenticate / provide a user name
`select_account`: user is prompted to select one of the existing sessions or create a new one
`create`: the registration form will be displayed to the user directly | @@ -200,10 +200,10 @@ Send your `code_verifier` for us to recompute the `code_challenge` of the author Send a client assertion as JWT for us to validate the signature against the registered public key. -| Parameter | Description | -| --------------------- | --------------------------------------------------------------------------------------------------------------- | +| Parameter | Description | +| --------------------- |--------------------------------------------------------------------------------------------------------------| | client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#jwt-with-private-key) | -| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | +| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | @@ -223,11 +223,11 @@ Send a client assertion as JWT for us to validate the signature against the regi #### Required request Parameters -| Parameter | Description | -| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| grant_type | Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` | -| assertion | JWT built and signed according to [Using JWTs for Authorization Grants](grant-types#using-jwts-as-authorization-grants) | -| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` | +| Parameter | Description | +| ---------- |-------------------------------------------------------------------------------------------------------------------------| +| grant_type | Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` | +| assertion | JWT built and signed according to [Using JWTs for Authorization Grants](grant-types#using-jwts-as-authorization-grants) | +| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` | ```BASH curl --request POST \ @@ -296,10 +296,10 @@ Send your `client_id` as parameter in the body. No authentication is required. Send a `client_assertion` as JWT for us to validate the signature against the registered public key. -| Parameter | Description | -| --------------------- | --------------------------------------------------------------------------------------------------------------- | +| Parameter | Description | +| --------------------- |--------------------------------------------------------------------------------------------------------------| | client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#jwt-with-private-key) | -| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | +| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | @@ -480,10 +480,10 @@ Send your `client_id` as parameters in the body: Send a `client_assertion` as JWT for ZITADEL to verify the signature against the registered public key. -| Parameter | Description | -| --------------------- | ----------------------------------------------------------------------------------------------------------- | +| Parameter | Description | +| --------------------- |---------------------------------------------------------------------------------------------------------------| | client_assertion | JWT created and signed according to [Using JWTs for Client Authentication](authn-methods#client-secret-basic) | -| client_assertion_type | must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | +| client_assertion_type | must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | ```BASH curl --request POST \ diff --git a/docs/docs/guides/integrate/access-zitadel-apis.md b/docs/docs/guides/integrate/access-zitadel-apis.md index 7689efd55b..8ce854806b 100644 --- a/docs/docs/guides/integrate/access-zitadel-apis.md +++ b/docs/docs/guides/integrate/access-zitadel-apis.md @@ -31,7 +31,7 @@ Make sure you have a Service User with a Key. (For more detailed informations ab ## Authenticating a service user -In ZITADEL we use the `private_jwt` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication. +In ZITADEL we use the `urn:ietf:params:oauth:grant-type:jwt-bearer` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication. This is already described in the [Service User](serviceusers.md), so make sure you follow this guide. ### Request an OAuth token, with audience for ZITADEL diff --git a/docs/docs/guides/integrate/serviceusers.md b/docs/docs/guides/integrate/serviceusers.md index c0a28408b5..e778d859bf 100644 --- a/docs/docs/guides/integrate/serviceusers.md +++ b/docs/docs/guides/integrate/serviceusers.md @@ -16,7 +16,7 @@ import UserDescription from '../../concepts/structure/_user_description.mdx'; ## Authenticating a service user -In ZITADEL we use the `private_jwt` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication. +In ZITADEL we use the `urn:ietf:params:oauth:grant-type:jwt-bearer` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication. You need to follow these steps to authenticate a service user and receive a access token: