mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +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,130 @@
|
||||
---
|
||||
title: ZITADEL OIDC Authentication Request Playground
|
||||
sidebar_label: OIDC Playground
|
||||
---
|
||||
|
||||
import { ExternalLink } from "lucide-react";
|
||||
|
||||
The OIDC Playground is for testing OpenID Authentication Requests, giving you more insight how OpenID Connect works and how you can customize ZITADEL behavior with different parameters.
|
||||
|
||||
An OpenID Connect (OIDC) [authentication request](https://openid.net/specs/openid-connect-core-1_0.html) is an OAuth 2.0 Authorization Request using additional parameters and scopes to request that the end-user be authenticated by ZITADEL.
|
||||
|
||||
<a href="https://zitadel.com/playgrounds/oidc" target="_blank" className="flex items-center gap-2 text-primary hover:underline">
|
||||
Go to the OIDC Playground <ExternalLink className="h-4 w-4" />
|
||||
</a>
|
||||
|
||||
## Why this OIDC playground?
|
||||
|
||||
Currently ZITADEL requires human users to authenticate trough the hosted login page.
|
||||
Your application should initiate a login by issuing an authentication request and redirecting the user to the login page. You can customize the behavior of ZITADEL by providing additional parameters and scopes in the request.
|
||||
|
||||
This playground should help you to initially craft an authentication request and to explore the behavior of ZITADEL in more depth.
|
||||
|
||||
## Request parameters explained
|
||||
|
||||
Not all request parameters are available in the playground. Please refer to the full documentation of the [authorization endpoint](/apis/openidoauth/endpoints#authorization-endpoint).
|
||||
|
||||
### Your Domain
|
||||
|
||||
The <span className="text-yellow-500">Custom Domain</span> to your ZITADEL instance. Use the base-path, the playground will add the required path to the request.
|
||||
|
||||
### Required Parameters
|
||||
|
||||
<p>
|
||||
<span className="text-green-500">Client ID</span> is the resource id of an
|
||||
application. It's the application where you want your users to login. You can
|
||||
find the resource id in the Console. When using organization grants, use the
|
||||
client id from the origin organization.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<span className="text-blue-500">Redirect URI</span> be one of the
|
||||
pre-configured redirect uris for your application. You must add the redirect
|
||||
uri for your application, else you will receive an error.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<span className="text-orange-500">Response Type</span> defines whether a code,
|
||||
id_token token or just id_token will be returned. Most use cases will need
|
||||
code.
|
||||
</p>
|
||||
|
||||
More in the <a href="/apis/openidoauth/endpoints#required-request-parameters">documentation</a> about required Parameters.
|
||||
|
||||
### Authentication methods
|
||||
|
||||
Depending on the authentication and authorization flow of your application you might need to append some information to the authentication request.
|
||||
|
||||
<span className="text-teal-600">Authentication method</span> "(none) PKCE" is recommended
|
||||
for most application types. The playground appends automatically a code challenge
|
||||
for PKCE flows.
|
||||
|
||||
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login/oidc/oauth-recommended-flows#our-recommended-authorization-flows) for more details.
|
||||
|
||||
More in the [documentation](/apis/openidoauth/authn-methods) about authentication methods.
|
||||
|
||||
### Additional Parameters
|
||||
|
||||
<div>
|
||||
<span className="text-cyan-500">Prompt</span> defines if and how the user
|
||||
should be prompted on login. For example:
|
||||
<ul>
|
||||
<li>
|
||||
<code>select_account</code>: user is prompted to select one of the
|
||||
existing sessions or create a new one
|
||||
</li>
|
||||
<li>
|
||||
<code>create</code>: present the register form
|
||||
</li>
|
||||
<li>
|
||||
<code>login</code>: requires the user to re-authenticate
|
||||
</li>
|
||||
<li>
|
||||
<code>none</code>: user must be authenticated without interaction, an
|
||||
error is returned otherwise; use for silent-refresh
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
<span className="text-rose-500">Login hint</span> must be a valid logon name
|
||||
of a user. You can skip the account picker by providing the Login hint.
|
||||
</p>
|
||||
|
||||
There are many more additional parameters. Please refer to the [documentation](/apis/openidoauth/endpoints#additional-parameters) about additional parameters.
|
||||
|
||||
## Standard Scopes
|
||||
|
||||
Used to request additional information from ZITADEL.
|
||||
These scopes are defined in the OpenID Connect specification.
|
||||
The `openid` scope is mandatory.
|
||||
|
||||
Not all scopes are available in the playground. Please refer to the full [documentation](/apis/openidoauth/scopes) for the exhaustive list of available standard and reserved scopes.
|
||||
|
||||
## Reserved Scopes
|
||||
|
||||
You can request additional information that is specific to ZITADEL or customize the behavior of ZITADEL by including reserved scopes.
|
||||
Please refer to the [documentation](/apis/openidoauth/scopes#reserved-scopes) for a full list of available reserved scopes.
|
||||
|
||||
### Organization policies and branding
|
||||
|
||||
Enforce an organization's policies and branding as well as membership of the user by passing the scope `urn:zitadel:iam:org:id:{id}` with the required <span className="text-purple-500">Organization ID</span>.
|
||||
|
||||
Please refer to the full [guide on branding](/guides/manage/customize/branding).
|
||||
|
||||
### Get user metadata
|
||||
|
||||
Pass the scope `urn:zitadel:iam:user:metadata` to request a user's metadata.
|
||||
Please refer to the full [guide on user-metadata](/guides/manage/customize/user-metadata) for further details.
|
||||
|
||||
### Access core apis
|
||||
|
||||
Calling the [core API](/apis/introduction) with the authenticated user, requires that the projectID of ZITADEL is included in the audience claim.
|
||||
|
||||
This can be achieved by adding the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to your applications authorization request.
|
||||
|
||||
## How to use ZITADEL in your project
|
||||
|
||||
Please refer to our [guide](/guides/integrate/login/oidc/login-users) on how to login users.
|
||||
|
||||
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](/sdk-examples/introduction).
|
||||
Reference in New Issue
Block a user