mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-08 23:25:12 +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:
Florian Forster
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -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}
|
||||
```
|
||||
Reference in New Issue
Block a user