mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-17 19:05:13 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
This commit is contained in:
co-authored by
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -0,0 +1,58 @@
|
||||
import PKCE from "./authmethods/_pkce.mdx";
|
||||
import Basic from "./authmethods/_basic.mdx";
|
||||
import Implicit from "./authmethods/_implicit.mdx";
|
||||
import PKCENative from "./authmethods/_pkcenative.mdx";
|
||||
import JWTPrivateKey from "./authmethods/_jwtpk.mdx";
|
||||
|
||||
export default function AuthMethods(props) {
|
||||
const { Tab, Tabs } = props.components || {};
|
||||
return props.selected == "web" ? (
|
||||
<div>
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{ label: "PKCE", value: "pkce" },
|
||||
{ label: "Basic Auth", value: "basic" },
|
||||
{ label: "JWT with Private Key", value: "jwtpk" },
|
||||
]}
|
||||
>
|
||||
<Tab value="pkce">
|
||||
<PKCE components={props.components} />
|
||||
</Tab>
|
||||
<Tab value="basic">
|
||||
<Basic components={props.components} />
|
||||
</Tab>
|
||||
<Tab value="jwtpk">
|
||||
<JWTPrivateKey components={props.components} />
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</div>
|
||||
) : props.selected == "native" ? (
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[{ label: "PKCE", value: "pkce" }]}
|
||||
>
|
||||
<Tab value="pkce">
|
||||
<PKCE components={props.components} Native />
|
||||
</Tab>
|
||||
</Tabs>
|
||||
) : props.selected == "spa" ? (
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{ label: "PKCE", value: "pkce" },
|
||||
{ label: "Implicit", value: "implicit" },
|
||||
]}
|
||||
>
|
||||
<Tab value="pkce">
|
||||
<PKCE components={props.components} />
|
||||
</Tab>
|
||||
<Tab value="implicit">
|
||||
<Implicit components={props.components} />
|
||||
</Tab>
|
||||
</Tabs>
|
||||
) : null;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Authentication Methods
|
||||
---
|
||||
|
||||
import AuthMethods from './_authmethods.mdx';
|
||||
|
||||
ZITADEL supports various authentication methods for OIDC clients.
|
||||
|
||||
<AuthMethods components={props.components} />
|
||||
@@ -0,0 +1,69 @@
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
|
||||
## Auth Request
|
||||
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
on /authorize with at least the following parameters:
|
||||
|
||||
- `client_id`: this tells the authorization server which application it is, copy from Management Console
|
||||
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
||||
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
||||
- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
|
||||
|
||||
We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
|
||||
the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
|
||||
|
||||
You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
|
||||
|
||||
Try out the request in our [OIDC Authentication Request Playground](https://zitadel.com/playgrounds/oidc?auth_method=Client%20Secret%20Basic).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization-endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
|
||||
callback endpoint you provided by the `redirect_uri`.
|
||||
|
||||
<Callout>
|
||||
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
|
||||
the error will be display directly to the user on the auth server.
|
||||
</Callout>
|
||||
|
||||
Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
|
||||
You will need this `code` in the token request.
|
||||
|
||||
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
||||
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
||||
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
||||
|
||||
## Token request
|
||||
|
||||
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
||||
|
||||
- code: the code that was issued from the authorization request
|
||||
- grant_type: must be `authorization_code`
|
||||
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
||||
|
||||
Depending on your authentication method you'll need additional headers and parameters:
|
||||
|
||||
Send your `client_id` and `client_secret` as Basic Auth Header. Note that OAuth2 requires client_id and client_secret to be form url encoded.
|
||||
So check [Client Secret Basic Auth Method](/apis/openidoauth/authn-methods#client-secret-basic) on how to build it correctly.
|
||||
|
||||
```curl
|
||||
curl --request POST \
|
||||
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
|
||||
--header 'Authorization: Basic ${basic}' \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data grant_type=authorization_code \
|
||||
--data code=${code} \
|
||||
--data redirect_uri=${redirect_uri}
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
<Callout type="warn" title="Security Notice">
|
||||
In contrast to the Code Flow, where you'll receive a code for token exchange, with the implicit flow you'll receive
|
||||
the tokens directly from the authorization endpoint. This is unsecure and might lead to token leakage and replay attacks.
|
||||
It will further be removed in OAuth 2.1 for the exact same reason.
|
||||
|
||||
We therefore discourage the use of Implicit Flow and do not cover the flow in this guide.
|
||||
</Callout>
|
||||
|
||||
If you still need to rely on the implicit flow, simply keep in mind that the response on the authorization_endpoint is
|
||||
the same you would be given on the token_endpoint and check the [OAuth / OIDC endpoint documentation](/apis/openidoauth/endpoints) for more information.
|
||||
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
|
||||
## Auth Request
|
||||
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
on /authorize with at least the following parameters:
|
||||
|
||||
- `client_id`: this tells the authorization server which application it is, copy from Management Console
|
||||
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
||||
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
||||
- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
|
||||
|
||||
When using the Implicit Flow you will also have to provide a `nonce` parameter to bind the client session to the id_token and to mitigate replay attacks. Furthermore, we recommend using a `state` parameter, which enables you to transfer a state through the authentication process.
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization-endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your callback endpoint you provided by the `redirect_uri`.
|
||||
|
||||
<Callout>
|
||||
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client, the error will be display directly to the user on the auth server.
|
||||
</Callout>
|
||||
|
||||
Upon successful authentication you'll be given the `access_token`, `id_token`, `expires_in` and if provided the unmodified `state` parameter, as you would be given from the token_endpoint when using Authorization Code Flow.
|
||||
|
||||
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
||||
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
||||
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
||||
@@ -0,0 +1,72 @@
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
|
||||
## Auth Request
|
||||
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
on /authorize with at least the following parameters:
|
||||
|
||||
- `client_id`: this tells the authorization server which application it is, copy from Management Console
|
||||
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
||||
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
||||
- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
|
||||
|
||||
We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
|
||||
the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
|
||||
|
||||
You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
|
||||
|
||||
So your request might look like this (linebreaks and whitespace for display reasons):
|
||||
|
||||
Try out the request in our [OIDC Authentication Request Playground](https://zitadel.com/playgrounds/oidc?auth_method=Client%20Secret%20Basic).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization-endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
|
||||
callback endpoint you provided by the `redirect_uri`.
|
||||
|
||||
<Callout>
|
||||
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
|
||||
the error will be display directly to the user on the auth server.
|
||||
</Callout>
|
||||
|
||||
Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
|
||||
You will need this `code` in the token request.
|
||||
|
||||
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
||||
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
||||
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
||||
|
||||
## Token request
|
||||
|
||||
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
||||
|
||||
- code: the code that was issued from the authorization request
|
||||
- grant_type: must be `authorization_code`
|
||||
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
||||
|
||||
Depending on your authentication method you'll need additional headers and parameters:
|
||||
|
||||
Send a JWT in the `client_assertion` and set the `client_assertion_type` to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
|
||||
for us to validate the signature against the registered public key:
|
||||
|
||||
```curl
|
||||
curl --request POST \
|
||||
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data grant_type=authorization_code \
|
||||
--data code=${code} \
|
||||
--data redirect_uri=${redirect_uri} \
|
||||
--data client_assertion=${client_assertion} \
|
||||
--data client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
|
||||
```
|
||||
@@ -0,0 +1,79 @@
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
|
||||
## Auth Request
|
||||
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
on /authorize with at least the following parameters:
|
||||
|
||||
- `client_id`: this tells the authorization server which application it is, copy from Management Console
|
||||
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
||||
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
||||
- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
|
||||
|
||||
We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
|
||||
the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
|
||||
|
||||
### PKCE
|
||||
|
||||
PKCE stands for Proof Key for Code Exchange. So other than "normal" code exchange, the PKCE does not authenticate using
|
||||
client_id and client_secret but an additional code. You will have to generate a random string, hash it and send this hash
|
||||
on the authorization_endpoint. On the token_endpoint you will then send the plain string for the authorization to compute
|
||||
the hash as well and to verify it's correct. In order to do so you're required to send the following two parameters as well:
|
||||
|
||||
- `code_challenge`: the base64url representation of the (sha256) hash of your random string
|
||||
- `code_challenge_method`: must always be `S256` standing for sha256, this is the only algorithm we support
|
||||
|
||||
For example for `random-string` the code_challenge would be `9az09PjcfuENS7oDK7jUd2xAWRb-B3N7Sr3kDoWECOY`
|
||||
|
||||
Try out the request in our [OIDC Authentication Request Playground](https://zitadel.com/playgrounds/oidc).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization-endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
|
||||
callback endpoint you provided by the `redirect_uri`.
|
||||
|
||||
<Callout>
|
||||
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
|
||||
the error will be display directly to the user on the auth server.
|
||||
</Callout>
|
||||
|
||||
Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
|
||||
You will need this `code` in the token request.
|
||||
|
||||
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
||||
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
||||
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
||||
|
||||
## Token request
|
||||
|
||||
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
||||
|
||||
- code: the code that was issued from the authorization request
|
||||
- grant_type: must be `authorization_code`
|
||||
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
||||
|
||||
Depending on your authentication method you'll need additional headers and parameters:
|
||||
|
||||
Send your `client_id` and the previously generated string as `code_verifier` for us to recompute the `code_challenge` of the authorization request:
|
||||
|
||||
```curl
|
||||
curl --request POST \
|
||||
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data grant_type=authorization_code \
|
||||
--data code=${code} \
|
||||
--data redirect_uri=${redirect_uri} \
|
||||
--data client_id=${client_id} \
|
||||
--data code_verifier=${code_verifier}
|
||||
```
|
||||
@@ -0,0 +1,63 @@
|
||||
#### redirect_uri
|
||||
|
||||
Native clients might have to register multiple redirect_uris as operating system have different requirements.
|
||||
Typically, you register a redirect_uri starting with a custom protocol, e.g. `ch.zitadel.app://callback`.
|
||||
You're also allowed to use http://localhost, http://127.0.0.1 and http:[::1] without specifying a port: `http://locahost/callback`.
|
||||
|
||||
#### post creation actions
|
||||
|
||||
After the application creation, you might want to set additional options like `refresh_token` and `additional origins`.
|
||||
|
||||
If you want to request refresh_tokens and use them to renew the user's access_tokens without their interaction,
|
||||
enable them in the OIDC Configuration section by ticking the checkbox.
|
||||
|
||||
When calling the userinfo_endpoint or any ZITADEL API, we will check if an origin header is sent. This is automatically done
|
||||
by the user agent. If one is sent we will check if the origin is allowed for your application. By default, all computed
|
||||
origins of the redirect_uri list are allowed.
|
||||
So if your native app is built with a JavaScript base framework like ReactNative and you only specified redirect_uris
|
||||
with a custom protocol, you will need to add the origin where the app is served from, e.g. `http://localhost:8100`.
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization-endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
|
||||
callback endpoint you provided by the `redirect_uri`.
|
||||
|
||||
<Callout>
|
||||
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
|
||||
the error will be display directly to the user on the auth server.
|
||||
</Callout>
|
||||
|
||||
Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
|
||||
You will need this `code` in the token request.
|
||||
|
||||
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
||||
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
||||
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
||||
|
||||
## Token request
|
||||
|
||||
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
||||
|
||||
- code: the code that was issued from the authorization request
|
||||
- grant_type: must be `authorization_code`
|
||||
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
||||
|
||||
Depending on your authentication method you'll need additional headers and parameters:
|
||||
|
||||
Send your `client_id` and the previously generated string as `code_verifier` for us to recompute the `code_challenge` of the authorization request:
|
||||
|
||||
```curl
|
||||
curl --request POST \
|
||||
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data grant_type=authorization_code \
|
||||
--data code=${code} \
|
||||
--data redirect_uri=${redirect_uri} \
|
||||
--data client_id=${client_id} \
|
||||
--data code_verifier=${code_verifier}
|
||||
```
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: Integrating Your Application with ZITADEL using RFC 8628 OAuth 2.0 Device Authorization Flow
|
||||
sidebar_label: Device Authorization Flow
|
||||
---
|
||||
|
||||
ZITADEL implements device authorization as per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628). This document demonstrates its use.
|
||||
|
||||
This documentation aims to guide you through the process of seamlessly integrating your application with ZITADEL, leveraging the capabilities of [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628). ZITADEL is a powerful identity and access management (IAM) solution that provides robust authentication and authorization services for your applications. RFC 8628, also known as "OAuth 2.0 Device Authorization Grant", offers a standardized protocol for devices with limited input capabilities to obtain user authorization. By following the steps outlined here, you'll be able to empower your application with secure authentication and access control mechanisms provided by ZITADEL, ensuring a smooth and secure user experience.
|
||||
|
||||
## What is RFC 8628?
|
||||
|
||||
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), or the OAuth 2.0 Device Authorization Grant, defines a protocol for OAuth 2.0 clients that have limited input capabilities, such as devices with no browser or low-power sensors. It allows such devices to obtain user consent for authorizing access to protected resources by directing the user to a device-friendly authentication endpoint.
|
||||
|
||||
## Why Integrate with Zitadel?
|
||||
|
||||
ZITADEL offers a comprehensive identity and access management solution, providing features like single sign-on (SSO), multi-factor authentication (MFA), user management, and more. By integrating your application with ZITADEL, you can leverage these powerful features to enhance the security and usability of your application without reinventing the wheel.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To begin integrating your application with Zitadel using RFC 8628, follow the steps outlined in this documentation. We'll walk you through the process, from setting up your application in the Zitadel management console to handling user authentication and access tokens in your application code.
|
||||
|
||||
1. Go to “Organization”/”Projects”.
|
||||
2. Under “Applications” click the “New” button.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-01.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
3. Select “Native” and enter a name for the application, and click “Continue”.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-02.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
4. Select “Device Code”. Click “Continue”.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-03.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
5. Check the details and click “Create”.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-04.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
6. Copy the “Client ID” and store it for later use.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-05.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
## Device Client Example
|
||||
|
||||
The [ZITADEL OpenID Connect client and server library](https://github.com/zitadel/oidc/) written for Go has a device client example, which can behave and authenticate as a device. In order to run this client, you need a recent version of Go (>=1.20) installed on your device.
|
||||
|
||||
The example requires two environment variables to be set:
|
||||
|
||||
- `ISSUER`: server address of your instance or domain. You can find the issuer URL in the “URLs” section. In this example, it will be set to [https://test-0o6zvq.zitadel.cloud](https://test-0o6zvq.zitadel.cloud). **Do not use a trailing slash!**
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-06.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
- `CLIENT_ID`: the Client ID we obtained earlier.
|
||||
|
||||
Replace `ISSUER` and `CLIENT_ID` values with the ones you obtained and run the example as shown below:
|
||||
|
||||
``` bash
|
||||
ISSUER="https://test-0o6zvq.zitadel.cloud" \
|
||||
CLIENT_ID="232685602728952637@device_auth" \
|
||||
go run github.com/zitadel/oidc/v2/example/client/device@latest
|
||||
```
|
||||
|
||||
You should see some info-level log output with response data and a line with login instructions as given below:
|
||||
|
||||
``` bash
|
||||
Please browse to https://test-0o6zvq.zitadel.cloud/device and enter code GQWC-FWFK
|
||||
INFO[0002] start polling
|
||||
```
|
||||
|
||||
At this point, the device app starts polling the token endpoint at 5-second intervals until the request is allowed, denied, or times out (currently 5 minutes).
|
||||
|
||||
## Authenticate
|
||||
|
||||
When you browse to the given URL and the device code is entered, the authentication flow for a user is started. If you are already logged in, it skips right ahead to the final screen where you can choose to allow or deny the request. If you are not logged in, you will have to enter your credentials for login.
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-07.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-08.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-09.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-10.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
<img src="/docs/img/device-auth/device-auth-11.png" alt="Device Authorization Flow in ZITADEL"/>
|
||||
|
||||
When “allow” is clicked, the device (the CLI in this case) will receive a token on the next poll. A log line will be shown as given below:
|
||||
|
||||
``` bash
|
||||
INFO[0165] successfully obtained token: &{Um2W5Od0yBU0KHfhP0AD0726rXrpxlepOR7yyftMvocgMWr25pVCuca1oiSSLiQjcXQqCEA Bearer 43199 }
|
||||
```
|
||||
|
||||
At this point, the program terminates as it doesn’t have any other useful purpose. Regular device apps would of course use the token to consume the actual service.
|
||||
|
||||
## Code URL
|
||||
|
||||
During the start of the authorization flow ,there is a log line printed with the complete response object from ZITADEL that looks like this:
|
||||
|
||||
``` bash
|
||||
resp&{dOcbPeysDhT26ZatRh9n7Q KPVZ-DJGG https://test-0o6zvq.zitadel.cloud/device https://test-0o6zvq.zitadel.cloud/device?user_code=GQWC-FWFK 300 5}
|
||||
```
|
||||
|
||||
From this object, we used the `verification_uri` and `user_code` fields to print the information to the user to go to an address and enter the code. We also return a `verification_uri_complete` field, which already includes the code and allows skipping manual entry of the code.
|
||||
|
||||
``` bash
|
||||
https://test-0o6zvq.zitadel.cloud/device?user_code=GQWC-FWFK
|
||||
```
|
||||
|
||||
In real-life applications, this could be used to create a QR code on the device screen, and users can use their mobile phones to scan the code to go to the required URL for authentication. In the context of this example, you can restart the device example program and copy/paste the complete link instead of manually entering it.
|
||||
|
||||
## Security considerations
|
||||
|
||||
The user uses a low entropy code to link a device to their account, which is easy to brute-force. Also, the code or QR might be displayed in environments where others could observe and use the code to authenticate the device (hijack the session) to their account.
|
||||
|
||||
The device authorization grant specification was written with the philosophy that hijacking such sessions is not beneficial for the attacker. For example, with an on-demand streaming service, the attacker would be paying for the services the user is benefiting from. Hence, economically, the attack would not make sense.
|
||||
|
||||
See [here](https://datatracker.ietf.org/doc/html/rfc8628#section-5) for more information.
|
||||
|
||||
## Client library
|
||||
|
||||
For Go clients, the ZITADEL OIDC repository already includes device authorization in the `rp` package.
|
||||
|
||||
Use [rp.DeviceAuthorization](https://pkg.go.dev/github.com/zitadel/oidc/v2/pkg/client/rp#DeviceAuthorization) to start the flow and receive the URL and user code.
|
||||
[rp.DeviceAccessToken](https://pkg.go.dev/github.com/zitadel/oidc/v2/pkg/client/rp#DeviceAccessToken) polls the token endpoint and returns the access token once it succeeds.
|
||||
|
||||
The client implementation is rather simple and can easily be recreated in other languages. Go can be used as an example, or simply follow the [RFC](https://datatracker.ietf.org/doc/html/rfc8628) as a guide.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Authenticate users with OpenID Connect (OIDC)"
|
||||
description: "This guide explains how to utilize ZITADEL for user authentication within your applications using OpenID Connect (OIDC). Here, we offer comprehensive guidance on seamlessly integrating ZITADEL's authentication features, ensuring both security and user experience excellence. Throughout this documentation, we'll cover the setup process for ZITADEL authentication, including the recommended OIDC flows tailored to different application types. Additionally, we'll provide clear instructions on securely signing out or logging out users from your application, ensuring data security and user privacy. With our guidance, you'll be equipped to leverage ZITADEL's authentication capabilities effectively, enhancing your application's security posture while delivering a seamless login experience for your users."
|
||||
---
|
||||
|
||||
{/* THIS FILE IS AUTO-GENERATED FROM SIDEBAR-DATA.
|
||||
ANY MANUAL CHANGES WILL BE OVERWRITTEN.
|
||||
*/}
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
import { FileText, Folder, Link as LinkIcon } from 'lucide-react';
|
||||
|
||||
<Cards>
|
||||
<Card title="Oauth Recommended Flows" href="/guides/integrate/login/oidc/oauth-recommended-flows" icon={<FileText />} />
|
||||
<Card title="Login Users" href="/guides/integrate/login/oidc/login-users" icon={<FileText />} />
|
||||
<Card title="Device Authorization" href="/guides/integrate/login/oidc/device-authorization" icon={<FileText />} />
|
||||
<Card title="Endpoints" href="/apis/openidoauth/endpoints" icon={<FileText />} />
|
||||
<Card title="Authn Methods" href="/apis/openidoauth/authn-methods" icon={<FileText />} />
|
||||
<Card title="Scopes" href="/apis/openidoauth/scopes" icon={<FileText />} />
|
||||
<Card title="Claims" href="/apis/openidoauth/claims" icon={<FileText />} />
|
||||
<Card title="Grant Types" href="/apis/openidoauth/grant-types" icon={<FileText />} />
|
||||
<Card title="Authrequest" href="/apis/openidoauth/authrequest" icon={<FileText />} />
|
||||
<Card title="Webkeys" href="/guides/integrate/login/oidc/webkeys" icon={<FileText />} />
|
||||
<Card title="Token Exchange" href="/guides/integrate/token-exchange" icon={<FileText />} />
|
||||
</Cards>
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Authenticate users with OpenID Connect
|
||||
sidebar_label: OIDC Code Flow + PKCE
|
||||
---
|
||||
|
||||
import AuthMethods from "./_authmethods.mdx";
|
||||
|
||||
## Overview
|
||||
|
||||
This guide will show you how to use ZITADEL to login users into your application (authentication).
|
||||
It will guide you step-by-step through the basics and point out on how to customize process.
|
||||
|
||||
## OIDC / OAuth Flow
|
||||
|
||||
OAuth and therefore OIDC know three different application types:
|
||||
|
||||
- Web (Server-side web applications such as java, .net, ...)
|
||||
- Native (native, mobile or desktop applications)
|
||||
- User Agent (single page applications / SPA, generally JavaScript executed in the browser)
|
||||
|
||||
Depending on the app type you're trying to register, there are small differences.
|
||||
But regardless of the app type we recommend using Proof Key for Code Exchange (PKCE).
|
||||
|
||||
Please read the following guide about the [different-client-profiles](./oauth-recommended-flows#different-client-profiles) and why to use PKCE.
|
||||
|
||||
### Code Flow
|
||||
|
||||
For a basic understanding of OAuth and its flows, we'll briefly describe the most important flow: **Authorization Code**.
|
||||
|
||||
The following diagram demonstrates a basic authorization_code flow:
|
||||
|
||||

|
||||
|
||||
1. When an unauthenticated user visits your application,
|
||||
2. you will create an authorization request to the authorization endpoint.
|
||||
3. The Authorization Server (ZITADEL) will send an HTTP 302 to the user's browser, which will redirect them to the login UI.
|
||||
4. The user will have to authenticate using the demanded auth mechanics.
|
||||
5. Your application will be called on the registered callback path (redirect_uri) and be provided an authorization_code.
|
||||
6. This authorization_code must then be sent together with you applications authentication (client_id + client_secret) to the token_endpoint
|
||||
7. In exchange the Authorization Server (ZITADEL) will return an access_token and if requested a refresh_token and in the case of OIDC an id_token as well
|
||||
8. The access_token can then be used to call a Resource Server (API). The token will be sent as Authorization Header.
|
||||
|
||||
This flow is the same when using PKCE or JWT with Private Key for authentication.
|
||||
|
||||
## Create Application
|
||||
|
||||
To create an application, open your project in Management Console and start by clicking on the "New" button in the Application section.
|
||||
|
||||
#### Application type
|
||||
|
||||
This will start a wizard asking you for an application name and a type.
|
||||
|
||||
<Tabs
|
||||
groupId="app-type"
|
||||
default="web"
|
||||
values={[
|
||||
{'label': 'Web Application', 'value': 'web'},
|
||||
{'label': 'Native Application', 'value': 'native'},
|
||||
{'label': 'Single Page Application', 'value': 'spa'},
|
||||
]}
|
||||
>
|
||||
<Tab value="web">
|
||||
|
||||
#### Authentication method
|
||||
|
||||
After selecting WEB, you'll next have to choose an authentication method. As mentioned before we recommend using PKCE.
|
||||
For even better security you could switch to JWT or just rely on the standard Code Flow. For security reasons we don't
|
||||
recommend using POST and will not cover it in this guide.
|
||||
|
||||
Please change the authentication method here as well, if you did so in the wizard, so we can better guide you through the process:
|
||||
|
||||
<AuthMethods components={props.components} selected="web" />
|
||||
</Tab>
|
||||
|
||||
<Tab value="native">
|
||||
|
||||
#### Authentication method
|
||||
|
||||
When selecting Native the authentication method always needs to be PKCE.
|
||||
|
||||
<AuthMethods components={props.components} selected="native" />
|
||||
</Tab>
|
||||
|
||||
<Tab value="spa">
|
||||
|
||||
#### Authentication method
|
||||
|
||||
When selecting SPA the recommended authentication method is again PKCE. All common Frameworks like Angular, React, Vue.js and so on
|
||||
are able to successfully authenticate with PKCE. Our management console UI for instance uses PKCE as well.
|
||||
|
||||
<AuthMethods components={props.components} selected="spa" />
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Log Out Users from an Application with ZITADEL
|
||||
sidebar_label: Logout
|
||||
---
|
||||
|
||||
This guide shows you the different concepts and use cases of the logout process and how to use it in ZITADEL.
|
||||
|
||||
## OpenID Connect Single Logout
|
||||
|
||||
### Single Sign On (SSO) vs Single Logout (SLO)
|
||||
|
||||
Single Sign On (SSO) allows a user to login once without the need for authentication across multiple applications.
|
||||
Single Logout (SLO) is the counterpart to SSO. With SLO a user can logout and terminate sessions across many applications, without actively logging out from them.
|
||||
|
||||
The purpose of a logout is to terminate a user session.
|
||||
Depending on how the session handling is implemented, there are different mechanisms that can be used.
|
||||
There are two possibilities where sessions are stored:
|
||||
- The User Agent (e.g the Browser or Mobile App) stores the session information (e.g. in a cookie)
|
||||
- A Server stores the session information (e.g. in a database or api)
|
||||
|
||||
### OpenID Connect Logout
|
||||
|
||||
OpenID Connect defines three logout mechanisms to address the different architectures:
|
||||
- [OpenID Connect Session Management 1.0](https://openid.net/specs/openid-connect-session-1_0.html)
|
||||
- [OpenID Connect Front-Channel Logout 1.0](https://openid.net/specs/openid-connect-frontchannel-1_0.html)
|
||||
- [OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html)
|
||||
|
||||
#### Session Management
|
||||
|
||||
Session Management in OpenID Connect defines a mechanism for a client (Relying Party, RP) to monitor the state of the user session from a identity provider (OP, e.g ZITADEL).
|
||||
When a user logs out of the provider, the user's session is terminated and the client can in turn reflect that in its behavior.
|
||||
|
||||
#### RP initiated Logout
|
||||
|
||||
With the RP initiated flow all logout processes are triggered by a request from the client (e.g your application) through a well defined standard API by redirecting the user-agent to the [end_session_endpoint](/apis/openidoauth/endpoints#end-session-endpoint).
|
||||
If you have specified some post_logout_redirect_uris on your client you have to send either the id_token_hint or the client_id as param in your request.
|
||||
So ZITADEL is able to read the configured redirect uris.
|
||||
|
||||
```
|
||||
GET ${CUSTOM_DOMAIN}/oidc/v1/end_session
|
||||
?id_token_hint={id_token}
|
||||
&post_logout_redirect_uri=https://rp.example.com/logged_out
|
||||
&state=random_string
|
||||
```
|
||||
|
||||
#### Front-Channel Logout
|
||||
|
||||
The user agent handles the front-channel logout.
|
||||
Each client with an OpenID Session of the user that supports front-channel renders an iframe so the logout request is performed on all clients parallel.
|
||||
|
||||
<Callout>
|
||||
This is not yet implemented in ZITADEL
|
||||
</Callout>
|
||||
|
||||
#### Back-Channel Logout
|
||||
|
||||
The back-channel logout is a mechanism on the server-side and the user agent does not have to do anything.
|
||||
The user will logout from all clients even in the case the user agent was closed.
|
||||
|
||||
<Callout>
|
||||
This is not yet implemented in ZITADEL
|
||||
</Callout>
|
||||
|
||||
## Scenarios
|
||||
|
||||
1. Logout all users from the current user-agent/browser (current implementation of ZITADEL end_session_endpoint)
|
||||
2. Logout my user from the current user-agent/browser
|
||||
3. Logout my user from the all devices
|
||||
|
||||
## Session Handling in ZITADEL
|
||||
|
||||
The session management in ZITADEL is done on the server side.
|
||||
As soon as a user authenticates the first time, ZITADEL generates a user-agent cookie.
|
||||
All open sessions on that user-agent (browser) will be stored to the same cookie.
|
||||
If you delete the cookie in your browser, we will not be able to find out which sessions belong to your user-agent.
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Recommended authorization flows with OpenID Connect (OIDC) and OAuth 2.x
|
||||
sidebar_label: Recommended authorization flows
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
In this guide we will go over some basics on how to obtain an authorization with OpenID Connect 1.x and OAuth 2.x.
|
||||
|
||||
ZITADEL does not make assumptions about the application type you are about to integrate. Therefore you must qualify and define an appropriate method for your users to gain authorization to access your application (“authentication flow”). Your choice depends on the application’s ability to maintain the confidentiality of client credentials and the technological capabilities of your application. If you choose a deprecated or unfeasible flow to obtain authorization for your application, your users’ credentials may be compromised.
|
||||
|
||||
We invite you to further explore the different authorization flows in the OAuth 2.x standard. For the start we assume that you have a brand-new application (ie. without legacy requirements) and you found an reliable SDK/Library that does the heavy lifting for you.
|
||||
|
||||
So this module will only go over the basics and explain why we recommend the flow “Authorization Flow with PKCE” as default for most applications. We will also cover the case of machine-to-machine communication, ie. where there is no interactive login. Further we will guide you to further reading viable alternatives, if the default flow is not feasible.
|
||||
|
||||
## Basics of Federated Identity
|
||||
|
||||
Although Federated Identities are not a new concept ([RFC 6749](https://tools.ietf.org/html/rfc6749), “The OAuth 2.0 Authorization Framework” was released in 2012) it is important to highlight the difference between the traditional client-server authentication model and the concept of delegated authorization and authentication.
|
||||
|
||||
The aforementioned RFC provides us with some [problems and limitations](https://tools.ietf.org/html/rfc6749#section-1) of the client-server authentication, where a client requests a protected resource on the server by authenticating with the user’s credentials:
|
||||
|
||||
- Applications need to store users credentials (eg, password) for future use; compromise of any application results in compromise of the end-users credentials
|
||||
- Servers are required to support password authentication
|
||||
- Without means of limiting scope when providing the user’s credentials, the application gains overly broad access to protected resources
|
||||
- Users cannot revoke access for a single application, but only for all by changing credentials
|
||||
|
||||
So what do we want to achieve with delegated authentication?
|
||||
|
||||
- Instead of implementing authentication on each server and trusting each server
|
||||
|
||||
- Users only **authenticate** with a trusted server (ie. ZITADEL), that validates the user’s identity through a challenge (eg, multiple authentication factors) and issues an **ID token** (OpenID Connect 1.x)
|
||||
- Applications have means of **validating the integrity** of presented access and ID tokens
|
||||
|
||||
- Instead of sending around the user’s credentials
|
||||
- Clients may access protected resources with an **access token** that is only valid for specific scope and limited lifetime (OAuth 2.x)
|
||||
- Users have to **authorize** applications to access certain [**scopes**](/apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](/apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
|
||||
- Access tokens are bearer tokens, meaning that possession of the token provides access to a resource. But the tokens expire frequently and the application must request a new access token via **refresh token** or the user must reauthenticate
|
||||
|
||||

|
||||
|
||||
This is where the so-called “flows” come into play: There are a number of different flows on how to handle the process from authentication, over authorization, getting tokens and requesting additional information about the user.
|
||||
|
||||
Maybe interesting to mention is that we are mostly concerned with choosing the right OAuth 2.x flows (alas “authorization”). OpenID Connect extends the OAuth 2.x flow with useful features like endpoint discovery (where to ask), ID Token (who is the user, when and how did she authenticate), and UserInfo Endpoint (getting additional information about the user).
|
||||
|
||||
## Different client profiles
|
||||
|
||||
As mentioned in the beginning of this module, there are two main determinants for choosing the optimal authorization flow:
|
||||
|
||||
1. Client’s ability to maintain the confidentiality of client credentials
|
||||
2. Technological limitations
|
||||
|
||||
OAuth 2.x defines two [client types](https://tools.ietf.org/html/rfc6749#section-2.1) based on their ability to maintain the confidentiality of their client credentials:
|
||||
|
||||
- Confidential: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.
|
||||
- Public: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.
|
||||
|
||||
The following table gives you a brief overview of different client profiles.
|
||||
|
||||
<table className="table-wrapper">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Confidentiality of client credentials</th>
|
||||
<th>Client profile</th>
|
||||
<th>Examples of clients</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowSpan="2">Public</td>
|
||||
<td>User-Agent</td>
|
||||
<td>Single-page web applications (SPA), generally JavaScript executed in Browser</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Native</td>
|
||||
<td>Native, Mobile, or Desktop applications</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowSpan="2">Confidential</td>
|
||||
<td>Web</td>
|
||||
<td>Server-side web applications such as java, .net, …</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Machine-to-Machine</td>
|
||||
<td>APIs, generally services without direct user-interaction at the authorization server</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Our recommended authorization flows
|
||||
|
||||
We recommend using the flow **“Authorization Code with Proof Key of Code Exchange (PKCE)”** ([RFC7636](https://tools.ietf.org/html/rfc7636)) for **User-Agent**, **Native**, and **Web** clients.
|
||||
|
||||
If you don’t have any technical limitations, you should favor the flow Authorization Code with PKCE over other methods. The PKCE part makes the flow resistant against authorization code interception attack as described well in RFC7636.
|
||||
|
||||
_So what about APIs?_
|
||||
|
||||
We recommend using **“JWT bearer token with private key”** ([RFC7523](https://tools.ietf.org/html/rfc7523)) for Machine-to-Machine clients.
|
||||
|
||||
What this means is that you have to send an JWT token, containing the [standard claims for access tokens](/apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts.
|
||||
|
||||
If you don’t have any technical limitations, you should prefer this method over other methods.
|
||||
|
||||
A JWT with a private key can also be used with client profile web to further enhance security.
|
||||
|
||||
In case you need alternative flows and their advantages and drawbacks, there will be a module to outline more methods and our recommended fallback strategy per client profile that are available in ZITADEL.
|
||||
@@ -0,0 +1,357 @@
|
||||
---
|
||||
title: OpenID Connect and OAuth2 web keys
|
||||
sidebar_label: Web Keys
|
||||
---
|
||||
|
||||
Web Keys in ZITADEL are used to sign and verify JSON Web Tokens (JWT).
|
||||
ID tokens are created, signed and returned by ZITADEL when a OpenID connect (OIDC) or OAuth2
|
||||
authorization flow completes and a user is authenticated.
|
||||
Optionally, ZITADEL can return JWTs for access tokens if the OIDC Application is configured for it.
|
||||
|
||||
## Introduction
|
||||
|
||||
ZITADEL uses asymmetric cryptography to sign and validate JWTs.
|
||||
Keys are generated in pairs resulting in a private and public key.
|
||||
Private keys are used to sign tokens.
|
||||
Public keys are used to verify tokens.
|
||||
OIDC clients need the public key to verify ID tokens.
|
||||
OAuth2 API apps might need the public key if they want to client-side verification of a
|
||||
JWT access tokens, instead of [introspection](/apis/openidoauth/endpoints#introspection-endpoint).
|
||||
ZITADEL uses public key verification when API calls are made or when the userInfo or introspection
|
||||
endpoints are called with a JWT access token.
|
||||
|
||||
### JSON Web Key
|
||||
|
||||
ZITADEL implements the [RFC7517 - JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517) format for storage and distribution of public keys.
|
||||
Web keys in ZITADEL support a number of [JSON Web Algorithms (JWA)](https://www.rfc-editor.org/rfc/rfc7518) for digital signatures:
|
||||
|
||||
| Identifier | Description |
|
||||
| ---------- | ------------------------------- |
|
||||
| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 |
|
||||
| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 |
|
||||
| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 |
|
||||
| ES256 | ECDSA using P-256 and SHA-256 |
|
||||
| ES384 | ECDSA using P-384 and SHA-384 |
|
||||
| ES512 | ECDSA using P-512 and SHA-512 |
|
||||
| EdDSA | EdDSA signature algorithms[^1] |
|
||||
|
||||
[^1]: EdDSA refers to both Ed25519 and Ed448 curves. ZITADEL only supports Ed25519 with a SHA-512 hashing algorithm. EdDSA is for JSON Object Signing is defined in [RFC8037](https://www.rfc-editor.org/rfc/rfc8037).
|
||||
|
||||
### Client Algorithm Support
|
||||
|
||||
Before customizing the algorithm the instance admin **MUST** make sure the complete app and API ecosystem
|
||||
supports the chosen algorithm.
|
||||
|
||||
When all OIDC applications of an instance use opaque access tokens, and they call APIs which only use
|
||||
introspection for token validation, only the OIDC applications will need to support the chosen algorithm.
|
||||
If JWT access tokens are used and APIs do public key verification, those APIs need to support the chosen algorithm as well.
|
||||
|
||||
RS256 is widely considered the default algorithm and must be supported by all OIDC/Oauth2 providers, relying parties and resource servers.
|
||||
This is also the default ZITADEL uses when [creating web keys](#creation).
|
||||
It might be reasonable to assume RS384 and RS512 are just as supported, because those are just variations on RSA based keys.
|
||||
The ES256, ES384 and ES512 might have reasonable support as well,
|
||||
ECDSA is part of the same [JSON Web Algorithms (JWA)](https://www.rfc-editor.org/rfc/rfc7518) as RSA.
|
||||
|
||||
EdDSA usage is defined in the supplemental [RFC8037](https://www.rfc-editor.org/rfc/rfc8037),
|
||||
and therefore may be less supported than the others.
|
||||
Also, the `at_hash` claim in the ID token is a hashed string of the access token.
|
||||
The hasher is usually defined by the keys `alg` header. For example:
|
||||
|
||||
- RS256 defines an RSA key and a SHA256 hasher.
|
||||
- ES512 defines an elliptic curve key with the P-512 and SHA512 hasher.
|
||||
|
||||
Unfortunately, there is no published standard for the `at_hash` hasher used for EdDSA.
|
||||
In fact, EdDSA may use different curves and internally uses different hashers:
|
||||
|
||||
- ed25519 uses SHA512;
|
||||
- ed448 uses SHAKE256;
|
||||
|
||||
This resulted in a [proposal](https://bitbucket.org/openid/connect/issues/1125/_hash-algorithm-for-eddsa-id-tokens) at
|
||||
the Open ID workgroup to follow suit and use the same hashing algorithms for the `at_hash` claim.
|
||||
This means both signers and verifiers can't know the hasher by the `alg` value alone and need to inspect `crv` value as well.
|
||||
Since the decision in the proposal isn't published yet,
|
||||
there is a big change some OIDC client libraries don't have proper support for EdDSA / ed25519.
|
||||
|
||||
The ZITADEL back-end is written in Go. The Go developers have denied ed448 curve implementations to be included.
|
||||
Therefore ZITADEL only uses ed25519 with a SHA512.
|
||||
The same counts for [zitadel/oidc](https://github.com/zitadel/oidc) Go library.
|
||||
|
||||
## Web Key management
|
||||
|
||||
ZITADEL provides a resource based [web keys API](/reference/api/webkey).
|
||||
The API allows the creation, activation, deletion and listing of web keys.
|
||||
All public keys that are stored for an instance are served on the [JWKS endpoint](#json-web-key-set).
|
||||
Applications need public keys for token verification and not all applications are capable of on-demand
|
||||
key fetching when receiving a token with an unknown key ID (`kid` header claim).
|
||||
Instead, those application may do a time-based refresh or only load keys at startup.
|
||||
|
||||
Using the web keys API, keys can be created first and activated for signing later.
|
||||
This allows the keys to be distributed to the instance's apps and caches.
|
||||
Once a key is deactivated, its public key will remain available for token verification until the web key is deleted.
|
||||
Delayed deletion makes sure tokens that were signed before the key got deactivated remain valid.
|
||||
|
||||
When the `web_key` [feature](/reference/api/feature/zitadel.feature.v2.FeatureService.SetInstanceFeatures) is enabled the first time,
|
||||
two web key pairs are created with one activated.
|
||||
|
||||
### Creation
|
||||
|
||||
The web key [create](/apis/resources/webkey_service_v2/zitadel-webkey-v-2-web-key-service-create-web-key) endpoint generates a new web key pair,
|
||||
using the passed generator configuration from the request. This config is a one-of field of:
|
||||
|
||||
- RSA
|
||||
- ECDSA
|
||||
- ED25519
|
||||
|
||||
When the request does not contain any specific configuration,
|
||||
[RSA](#rsa) is used as default with the default options as described below:
|
||||
|
||||
```bash
|
||||
curl -L 'https://${CUSTOM_DOMAIN}/v2/web_keys' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
#### RSA
|
||||
|
||||
The RSA generator config takes two enum values.
|
||||
|
||||
- The `bits` fields determines the size of the RSA key:
|
||||
- `RSA_BITS_2048` (**default**)
|
||||
- `RSA_BITS_3072`
|
||||
- `RSA_BITS_4096`
|
||||
- The `hasher` field sets the hash mode and
|
||||
determines the `alg` header value of the web key:
|
||||
- `RSA_HASHER_SHA256` results in the RS256 algorithm header. (**default**)
|
||||
- `RSA_HASHER_SHA384` results in the RS384 algorithm header.
|
||||
- `RSA_HASHER_SHA512` results in the RS512 algorithm header.
|
||||
|
||||
For example, to create a RSA web key with the size of 3072 bits and the SHA512 algorithm (RS512):
|
||||
|
||||
```bash
|
||||
curl -L 'https://${CUSTOM_DOMAIN}/v2/web_keys' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{
|
||||
"rsa": {
|
||||
"bits": "RSA_BITS_3072",
|
||||
"hasher": "RSA_HASHER_SHA512"
|
||||
}
|
||||
}'
|
||||
|
||||
```
|
||||
|
||||
#### ECDSA
|
||||
|
||||
The ECDSA generator config takes a single `curve` enum value which determines both the key's curve parameters and hashing algorithm:
|
||||
|
||||
- `ECDSA_CURVE_P256` uses the NIST P-256 curve and sets the ES256 algorithm header.
|
||||
- `ECDSA_CURVE_P384` uses the NIST P-384 curve and sets the ES384 algorithm header.
|
||||
- `ECDSA_CURVE_P512` uses the NIST P-512 curve and sets the ES512 algorithm header.
|
||||
|
||||
For example, to create a ECDSA web key with a P-256 curve and the SHA256 algorithm:
|
||||
|
||||
```bash
|
||||
curl -L 'https://${CUSTOM_DOMAIN}/v2/web_keys' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{
|
||||
"ecdsa": {
|
||||
"curve": "ECDSA_CURVE_P256"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### ED25519
|
||||
|
||||
ED25519 is an EdDSA curve and currently the only EdDSA curve supported by ZITADEL.[^2]
|
||||
No config is needed for ed25519 as its specification already includes the curve parameters.
|
||||
ed25519 always uses the SHA512 hasher.
|
||||
|
||||
Note that the `alg` header for ed25519 is `EdDSA` and refers to both ed25519 and ed448 curves.
|
||||
Both curves specify different hashers.
|
||||
Clients which support both curves must inspect `crv` header value to assert the difference.
|
||||
|
||||
For example, to create a ed25519 web key:
|
||||
|
||||
```bash
|
||||
curl -L 'https://${CUSTOM_DOMAIN}/v2/web_keys' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{
|
||||
"ed25519": {}
|
||||
}'
|
||||
```
|
||||
|
||||
[^2]: The ZITADEL back-end is written in Go. The Go developers have denied ed448 curve implementations to be included.
|
||||
Therefore ZITADEL won't support this either.
|
||||
|
||||
### Activation
|
||||
|
||||
When a generated web key is [activated](/apis/resources/webkey_service_v2/zitadel-webkey-v-2-web-key-service-activate-web-key),
|
||||
its private key will be used to sign new tokens.
|
||||
There can be only one active key on an instance.
|
||||
Activating a key implies deactivation of the previously active key.
|
||||
|
||||
Public keys on the [JWKS](#json-web-key-set) endpoint may be [cached](#caching).
|
||||
Therefore it is advised to delay activation after generating a key,
|
||||
at least for the duration of the max-age setting plus any time it might take for client applications to refresh.
|
||||
|
||||
### Deletion
|
||||
|
||||
Non-active keys may be [deleted](/apis/resources/webkey_service_v2/zitadel-webkey-v-2-web-key-service-delete-web-key).
|
||||
Deletion also means tokens signed with this key become invalid.
|
||||
Active keys can't be deleted.
|
||||
As each public key is available on the [JWKS](#json-web-key-set) endpoint,
|
||||
it is important to cleanup old web keys that are no longer needed.
|
||||
Otherwise the endpoint's response size will only grow over time, which might lead to performance issues.
|
||||
|
||||
Once a key was activated and deactivated (by activation of the next key) deletion should wait:
|
||||
|
||||
- Until access and ID tokens are expired. See [OIDC token lifetimes](/guides/manage/console/default-settings#oidc-token-lifetimes-and-expiration).
|
||||
- ID tokens may be used as `id_token_hint` in authentication and end-session requests. The hint typically doesn't expire, but becomes invalid once the key is deleted.
|
||||
It might be desirable to keep keys around long enough to minimize user impact.
|
||||
|
||||
### Rotation example
|
||||
|
||||
This section gives an example on a key rotation strategy.
|
||||
This strategy aims to fulfill the following requirements:
|
||||
|
||||
1. Web keys are rotated monthly.
|
||||
2. Applications have enough time to see the next activated web key on the [JWKS](#json-web-key-set) endpoint.
|
||||
3. Web keys are kept long enough to cover the access and ID token validity of 24 hours.
|
||||
4. Web keys are kept long enough to to allow usage of the `id_token_hint` for at least 3 months.
|
||||
Users that haven't logged in / refreshed tokens with the client app for that period,
|
||||
will need to re-enter their username.
|
||||
|
||||
When the instance was created, resp. the feature was rolled out, the instance got two keys with the first one activated. When this feature becomes generally available, instance creation will setup the first two keys in the same way. So the initial state always looks like this:
|
||||
|
||||
| id | created | changed | state |
|
||||
| --- | ---------- | ---------- | --------------- |
|
||||
| 1 | 2025-01-01 | 2025-01-01 | `STATE_ACTIVE` |
|
||||
| 2 | 2025-01-01 | 2025-01-01 | `STATE_INITIAL` |
|
||||
|
||||
For the sake of this example we will use simplified IDs and restrict timestamps to dates.
|
||||
|
||||
After one month, on 2025-02-01, we wish to activate the next available key and create a new key to be available for activation next month. This fulfills requirements 1 and 2.
|
||||
|
||||
```bash
|
||||
curl -L -X POST 'https://${CUSTOM_DOMAIN}/v2/web_keys/2/_activate' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>'
|
||||
|
||||
curl -L 'https://${CUSTOM_DOMAIN}/v2/web_keys' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
Key ID 2 became active, Key ID 1 became inactive and a new key with ID 3 was created:
|
||||
|
||||
| id | created | changed | state |
|
||||
| --- | ---------- | ---------- | ---------------- |
|
||||
| 1 | 2025-01-01 | 2025-02-01 | `STATE_INACTIVE` |
|
||||
| 2 | 2025-01-01 | 2025-02-01 | `STATE_ACTIVE` |
|
||||
| 3 | 2025-02-01 | 2025-02-01 | `STATE_INITIAL` |
|
||||
|
||||
No keys are deleted yet.
|
||||
We continue like this monthly.
|
||||
At one point (on 2025-05-01) we will have a web key with `STATE_INACTIVE` with a changed date of 3 months ago:
|
||||
|
||||
| id | created | changed | state |
|
||||
| --- | ---------- | ---------- | ---------------- |
|
||||
| 1 | 2025-01-01 | 2025-02-01 | `STATE_INACTIVE` |
|
||||
| 2 | 2025-01-01 | 2025-03-01 | `STATE_INACTIVE` |
|
||||
| 3 | 2025-02-01 | 2025-04-01 | `STATE_INACTIVE` |
|
||||
| 4 | 2025-03-01 | 2025-05-01 | `STATE_INACTIVE` |
|
||||
| 5 | 2025-04-01 | 2025-05-01 | `STATE_ACTIVE` |
|
||||
| 6 | 2025-05-01 | 2025-05-01 | `STATE_INITIAL` |
|
||||
|
||||
In addition to the activate and create calls we made on this iteration,
|
||||
we can now safely delete the oldest key, as both requirement 3 and 4 are now fulfilled:
|
||||
|
||||
```bash
|
||||
curl -L -X DELETE 'https://${CUSTOM_DOMAIN}/v2/web_keys/1' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>'
|
||||
```
|
||||
|
||||
The final state:
|
||||
|
||||
| id | created | changed | state |
|
||||
| --- | ---------- | ---------- | ---------------- |
|
||||
| 2 | 2025-01-01 | 2025-03-01 | `STATE_INACTIVE` |
|
||||
| 3 | 2025-02-01 | 2025-04-01 | `STATE_INACTIVE` |
|
||||
| 4 | 2025-03-01 | 2025-05-01 | `STATE_INACTIVE` |
|
||||
| 5 | 2025-04-01 | 2025-05-01 | `STATE_ACTIVE` |
|
||||
| 6 | 2025-05-01 | 2025-05-01 | `STATE_INITIAL` |
|
||||
|
||||
Next month, Key ID 6 will be activated, an new key added and Key ID 2 can be deleted.
|
||||
|
||||
## JSON web key set
|
||||
|
||||
The JSON web key set (JWKS) endpoint serves all available public keys for the instance on
|
||||
`${CUSTOM_DOMAIN}/oauth/v2/keys`. This includes activated, newly non-activated and deactivated web keys. The response format is defined in [RFC7517, section 5: JWK Set Format](https://www.rfc-editor.org/rfc/rfc7517#section-5).
|
||||
|
||||
And looks like:
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "RSA",
|
||||
"kid": "280543383892525058",
|
||||
"alg": "RS384",
|
||||
"n": "0pVcbjTEr-awBmvztGLbBJB_-_YwjCKKXURJRpoXrChlaqtAvbkxby7mu9wSKAibxnvaobfuxnQydlB4CoKObUr00ARVBNeP5HLzeQUEx3CZh3s1LsjiuYov_yyvK9D12WH1LikP4ZPS68j-DVoEOEcFAE6cNikXTeDyCKa-ixROALieRXUQXTlvVyA_s0FhevmH0-M6rEN4YcfQuIZACEv2nQ4AJo0sNnugwrrqNn595ONKMSh2XTVngxxAD3TGHXg9bELB-WmgnZamVbO-ObpDBp5Ov73HL60_UoBTzBDECM6ovl52fHusLFw6Vkdt9_W3QhuRFljNqTPnna6rB-bLptQltBpnSBV3TxmklBcQ1EO3qeGvgOJsmDwSRlr28Du_1pyFMFANnG174eX5XrYASqTgJ1Wq7AfMBmv7YwGU7PbMce1V_CAV9u_hNkMJf0xQ4AIqrQ98f9hC5VCdCoKSOH1-1d8icEu7UmDyJohWqvY7xGOM_0Abx8ekMRT2O9PulmQ22me_GI5zXh7iv9yaoNq8EUNP5bdtr-ZG4PG8mqpLDSLpCpobYRK5AynyJkf-7_6neSy-ihu604ADKsNzB-uO58V8MPFdSPncyuUeTPX4dAVajbFyMtoAjtI1k_HYMU8nojRUrLSCJae9b0KtcPm9s7dCIL1Zpa4B-YM",
|
||||
"e": "AQAB"
|
||||
},
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "OKP",
|
||||
"kid": "280998627474669570",
|
||||
"crv": "Ed25519",
|
||||
"alg": "EdDSA",
|
||||
"x": "B51hFhRUHMHpqO1f-OThtnk3PfnRFaPFJWCLXSM_kuI"
|
||||
},
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "282465789963927554",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "X5s3tNoIXd5odp_-IwQq5oaAgMSoAxj0hwQ1DgHihmI",
|
||||
"y": "JqmTlRjoOv5bY5E9tAZXHaUHUamAAAFshO8zLhEZ9ZM"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
After the `web_key` feature is enabled, the response may still contain legacy keys, in order not to invalidate older sessions.
|
||||
The legacy keys will disappear once they expire.
|
||||
|
||||
### Caching
|
||||
|
||||
As web keys can be created and distributed ahead of time, it is safe for JWKS responses to be cached at intermediate proxies.
|
||||
Once the `web_key` feature is enabled, ZITADEL will send a `Cache-Control` header which allows caching.
|
||||
|
||||
By default and in ZITADEL Cloud we allow 5 minutes of caching:
|
||||
|
||||
```
|
||||
Cache-Control: max-age=300, must-revalidate
|
||||
```
|
||||
|
||||
Self-hosters can modify this setting through the `ZITADEL_OIDC_JWKSCACHECONTROLMAXAGE`
|
||||
environment variable or in the configuration yaml:
|
||||
|
||||
```yaml
|
||||
OIDC:
|
||||
JWKSCacheControlMaxAge: 5m
|
||||
```
|
||||
|
||||
Setting the value to `0` will result in a `no-store` value in the `Cache-Control` header.
|
||||
Reference in New Issue
Block a user