TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-01-12 10:43:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: better distinct JWT Profile grant and assertion (#4201)

Browse Source 
docs: update JWT Profile grant
This commit is contained in:
Livio Spring 2022-08-16 14:49:37 +02:00 committed by GitHub
parent 44fc2efbb7
commit 9c37f39d43
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/docs/apis/openidoauth/authn-methods.md
View File

@ -15,7 +15,7 @@ Given the client_id `78366401571920522@amce` and client_secret `veryweaksecret!`
## JWT with Private Key ## 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 JWT
| Claim | Example | Description | | Claim | Example | Description |
|:------|:------------------------------|:----------------------------------------------------------------------------------------------------------------| |:------|:---------------------------|:----------------------------------------------------------------------------------------------------------------|
| aud | `"{your_domain}"` | String or Array of intended audiences MUST include ZITADEL's issuing domain | | aud | `"{your_domain}"` | String or Array of intended audiences MUST include ZITADEL's issuing domain |
| exp | `1605183582` | Unix timestamp of the expiry | | 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 | | 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 | | 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 | | sub | `"78366401571920522@acme"` | The subject ID of the application, normally the `clientID` from the json key file |
```JSON ```JSON
{ {

30
docs/docs/apis/openidoauth/endpoints.md
View File

@ -86,7 +86,7 @@ no additional parameters required
| Parameter | Description | | Parameter | Description |
| ------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id_token_hint | Valid `id_token` (of an existing session) used to identity the subject. **SHOULD** be provided when using prompt `none`. | | 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 | | 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**. | | 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. <br />no prompt: the user will have to choose a session if more than one session exists<br />`none`: user must be authenticated without interaction, an error is returned otherwise <br />`login`: user must reauthenticate / provide a user name <br />`select_account`: user is prompted to select one of the existing sessions or create a new one <br />`create`: the registration form will be displayed to the user directly | | prompt | If the Auth Server prompts the user for (re)authentication. <br />no prompt: the user will have to choose a session if more than one session exists<br />`none`: user must be authenticated without interaction, an error is returned otherwise <br />`login`: user must reauthenticate / provide a user name <br />`select_account`: user is prompted to select one of the existing sessions or create a new one <br />`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. 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 | 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` |
</TabItem> </TabItem>
</Tabs> </Tabs>
@ -223,11 +223,11 @@ Send a client assertion as JWT for us to validate the signature against the regi
#### Required request Parameters #### Required request Parameters
| Parameter | Description | | Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | ---------- |-------------------------------------------------------------------------------------------------------------------------|
| grant_type | Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` | | 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) | | 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` | | scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` |
```BASH ```BASH
curl --request POST \ 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. 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 | 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` |
</TabItem> </TabItem>
</Tabs> </Tabs>
@ -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. 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 | 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 ```BASH
curl --request POST \ curl --request POST \

2
docs/docs/guides/integrate/access-zitadel-apis.md
View File

@ -31,7 +31,7 @@ Make sure you have a Service User with a Key. (For more detailed informations ab
## Authenticating a service user ## 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. 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 ### Request an OAuth token, with audience for ZITADEL

2
docs/docs/guides/integrate/serviceusers.md
View File

@ -16,7 +16,7 @@ import UserDescription from '../../concepts/structure/_user_description.mdx';
## Authenticating a service user ## 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: You need to follow these steps to authenticate a service user and receive a access token: