Skip to main content

Grant Types in ZITADEL

For a list of supported or unsupported Grant Types please have a look at the table below.

Grant TypeSupported
Authorization Codeyes
Authorization Code with PKCEyes
Client Credentialsyes
Device Authorizationyes
Implicityes
JSON Web Token (JWT) Profileyes
Refresh Tokenyes
Resource Owner Password Credentialsno
Security Assertion Markup Language (SAML) 2.0 Profileno
Token Exchangeyes

Authorization Code​

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.1

Proof Key for Code Exchange​

Link to spec. Proof Key for Code Exchange by OAuth Public Clients

Implicit​

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.2

Client Credentials​

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.4

Refresh Token​

Link to spec. The OAuth 2.0 Authorization Framework Section 1.5

JSON Web Token (JWT) Profile​

Link to spec. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants

Using JWTs as Authorization Grants​

Our service user work with the JWT profile to authenticate them against ZITADEL.

  1. Create or use an existing service user
  2. Create a new key and download it
  3. Generate a JWT with the structure below and sign it with the downloaded key
  4. Send the JWT Base64 encoded to ZITADEL's token endpoint
  5. Use the received access token

Key JSON

KeyExampleDescription
type"serviceaccount"The type of account, right now only serviceaccount is valid
keyId"81693565968772648"This is unique ID of the key
key"-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----"The private key generated by ZITADEL, this can not be regenerated!
userId78366401571647008The service users ID, this is the same as the subject from tokens
{
    "type": "serviceaccount",
    "keyId": "81693565968772648",
    "key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
    "userId": "78366401571647008"
}

JWT

ClaimExampleDescription
aud"https://$CUSTOM-DOMAIN"String or Array of intended audiences MUST include ZITADEL's issuing domain
exp1605183582Unix timestamp of the expiry
iat1605179982Unix timestamp of the creation singing time of the JWT, MUST NOT be older than 1h
iss"77479219772321307"String which represents the requesting party (owner of the key), normally the userId from the json key file
sub"77479219772321307"The subject ID of the service user, normally the userId from the json key file
{
    "iss": "77479219772321307",
    "sub": "77479219772321307",
    "aud": "https://$CUSTOM-DOMAIN",
    "exp": 1605183582,
    "iat": 1605179982
}

To identify your key, it is necessary that you provide a JWT with a kid header claim representing your keyId from the Key JSON:

{
  "alg": "RS256",
  "kid": "81693565968772648"
}

See JWT Profile Grant on Token Endpoint for usage.

Using JWTs for Client Authentication​

See how to build a JWT for client authentication from the downloaded key.

Find out how to use it on the token endpoint or the introspection endpoint.

Token Exchange​

Link to spec. OAuth 2.0 Token Exchange

Device Authorization​

Link to spec. OAuth 2.0 Device Authorization Grant

Security Assertion Markup Language (SAML) 2.0 Profile​

Link to spec. Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants

Not Supported Grant Types​

Resource Owner Password Credentials​

Due to growing security concerns we do not support this grant type. With OAuth 2.1 it looks like this grant will be removed.

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.3