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,190 @@
|
||||
---
|
||||
title: Applications
|
||||
sidebar_label: Applications
|
||||
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
import ThemedImage from "@/components/docusaurus/themed-image";
|
||||
import AuthType from "../../integrate/application/_auth-type.mdx";
|
||||
import ReviewConfig from "../../integrate/application/_review-config.mdx";
|
||||
import AppType from "./_application-types.mdx";
|
||||
|
||||
## What is an application?
|
||||
|
||||
Applications are the entry point to your [Project Overview](/guides/manage/console/projects-overview)
|
||||
. Users either login into one of your clients (Frontend) and interact with them directly, or use one of your APIs (Backend).
|
||||
|
||||
All applications within a project share the same **Roles** and **Authorizations**. This means you define a role once (e.g., `admin`) on the Project level, and it applies across all your web, mobile, and API applications.
|
||||
|
||||
To access your applications, navigate to your Project in the Management Console and select your application.
|
||||
|
||||
<img
|
||||
alt="Granted project"
|
||||
src="/docs/img/guides/console/applications.png"
|
||||
width="750px"
|
||||
|
||||
/>
|
||||
|
||||
## Create an Application
|
||||
|
||||
To add an application to your project, click on the **New** button and select your application type.
|
||||
|
||||
<img
|
||||
alt="Add application"
|
||||
src="/docs/img/guides/console/addapplication.png"
|
||||
width="120px"
|
||||
/>
|
||||
|
||||
## Application Types
|
||||
|
||||
ZITADEL offers five client types to cover different architectural patterns:
|
||||
|
||||
<AppType components={props.components} />
|
||||
|
||||
The first three options (Web, Native, and User Agent) require user interaction. The fourth option (API) is for machine-to-machine communication without direct user interaction.
|
||||
|
||||
Depending on the app type, there are small differences in the possible settings. To get a good understanding about user profiles and recommended flows, read the [Recommended Flows Guide](../../integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
|
||||
|
||||
### Web
|
||||
|
||||
Web applications are **server-side rendered** applications that users interact with.
|
||||
* **Examples:** Applications using Java (Spring/Thymeleaf), .NET (Razor), PHP, Python (Django/Flask), or enabling SSO in tools like GitLab.
|
||||
* **NextJS:** A NextJS app is typically a Web Application because it can execute server-side code (SSR/API routes) to keep secrets safe.
|
||||
* **Authentication:** Uses Authorization Code Flow (PKCE recommended) with a Client Secret.
|
||||
|
||||
<AuthType components={props.components} appType="web" />
|
||||
|
||||
### Native
|
||||
|
||||
Native Applications are installed on a thin client, such as a smartphone or desktop computer.
|
||||
* **Examples:** Android Apps, iOS Apps, Desktop Apps (Electron, Tauri).
|
||||
* **Authentication:** Uses the Key file generated by ZITADEL to authenticate or Authorization Code Flow with PKCE (for user login).
|
||||
|
||||
<AuthType components={props.components} appType="native" />
|
||||
|
||||
### User Agent
|
||||
|
||||
User Agent Applications are executed entirely in the web browser (Client-Side).
|
||||
* **Examples:** Single Page Applications (SPA) built with React, Angular, Vue, or Svelte that do not have a backend server.
|
||||
* **Authentication:** Uses Authorization Code Flow with PKCE (implicit flow is supported but not recommended).
|
||||
|
||||
<AuthType components={props.components} appType="user-agent" />
|
||||
|
||||
### API
|
||||
|
||||
These are applications without human interaction, accessed by other applications or services (Machine-to-Machine).
|
||||
* **Examples:** Background workers, CLIs, Daemons, Microservices.
|
||||
* **Authentication:** Uses Client Credentials (JWT Profile or Basic Auth) or Private Key JWT.
|
||||
|
||||
<AuthType components={props.components} appType="api" />
|
||||
|
||||
### SAML
|
||||
|
||||
If your application doesn't support the OIDC standard but supports SAML 2.0, choose this type. SAML is an XML-based open standard for exchanging authentication and authorization data.
|
||||
|
||||
After creating a SAML app, you can either:
|
||||
1. Add a link to a SAML metadata file.
|
||||
2. Upload the metadata XML file directly.
|
||||
|
||||
You can find example configurations for SAML 2.0 in our [integrate services](../../integrate/login/saml) guides.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Redirect URIs
|
||||
|
||||
App Types with user interaction (Web, Native, and User Agent) require Redirect URIs. These are the allowed URLs where ZITADEL sends the user after a successful login.
|
||||
|
||||
* **Security:** ZITADEL strictly checks these URIs during the login process. They must match exactly what is defined in your application code.
|
||||
* **Protocols:** Native applications can use custom protocols (e.g., `myapp://`) instead of `http/https`.
|
||||
|
||||
<img
|
||||
alt="Redirect URIs"
|
||||
src="/docs/img/guides/console/redirecturis.png"
|
||||
width="600px"
|
||||
/>
|
||||
|
||||
### Development Mode
|
||||
|
||||
If you are developing locally or need to redirect users to a non-secure protocol (other than `https://`), you must enable **Development mode**.
|
||||
When disabled, ZITADEL enforces strict security and only allows `https`.
|
||||
|
||||
<img
|
||||
alt="Development mode"
|
||||
src="/docs/img/guides/console/developmentmode.png"
|
||||
width="600px"
|
||||
/>
|
||||
|
||||
**Glob Patterns:**
|
||||
Development mode allows the use of glob patterns in Redirect URIs for flexibility:
|
||||
|
||||
| Special Terms | Meaning |
|
||||
| :--- | :--- |
|
||||
| `*` | Matches any sequence of **non-path-separators**. |
|
||||
| `/**/` | Matches zero or more directories. |
|
||||
| `?` | Matches any single non-path-separator character. |
|
||||
| `[class]` | Matches any single character against a class of characters (e.g., `[a-z]`). |
|
||||
| `{alt1,...}` | Matches a sequence if one of the comma-separated alternatives matches. |
|
||||
|
||||
<Callout type="note">
|
||||
Double stars (`**`) should appear surrounded by path separators (e.g., `/**/`). A pattern like `path/to/**.txt` is invalid; use `path/to/**/*.txt`.
|
||||
</Callout>
|
||||
|
||||
<Callout type="tip">
|
||||
IPv6
|
||||
When IPv6 URIs are used as redirects in development mode, square brackets must be escaped as they are special terms for globs. Example: `http://\[::1\]:80`
|
||||
</Callout>
|
||||
|
||||
### Review Configuration
|
||||
|
||||
<ReviewConfig components={props.components} authType="code" />
|
||||
|
||||
## Application Settings
|
||||
|
||||
After creating an application, you can modify its configuration.
|
||||
* **Auth Method:** You can switch authentication methods (e.g., from Basic to Private Key JWT) via the toggle or dropdowns.
|
||||
* **OIDC Compliance:** The Management Console checks if your configuration is OIDC compliant and shows tasks for completion if anything is missing.
|
||||
|
||||
<Callout type="caution">
|
||||
You **cannot** change the Application Type (e.g., from Web to Native) after creation. You must delete and recreate the application.
|
||||
</Callout>
|
||||
|
||||
<img
|
||||
alt="Application Settings"
|
||||
src="/docs/img/guides/console/application.png"
|
||||
width="800px"
|
||||
/>
|
||||
|
||||
### Token Settings
|
||||
|
||||
In the **Token Settings** section, you can customize the tokens issued for this application:
|
||||
* **Token Type:** Switch between **Bearer Token** (Opaque) and **JWT**.
|
||||
* **Content:** Check options to include User Roles and User Information inside the ID Token.
|
||||
* **ClockSkew:** Optionally set a time buffer added to the expiration time of the issued token to handle server time differences.
|
||||
|
||||
<img
|
||||
alt="Token settings"
|
||||
src="/docs/img/guides/console/app-token-settings.png"
|
||||
width="600px"
|
||||
/>
|
||||
|
||||
### Additional Origins
|
||||
|
||||
If your application makes requests from domains other than the Redirect URI (e.g., a Javascript app fetching data from an API on a different domain), you can specify them here to configure CORS (Cross-Origin Resource Sharing).
|
||||
|
||||
<img
|
||||
alt="Additional origins"
|
||||
src="/docs/img/guides/console/additional-origins.png"
|
||||
width="500px"
|
||||
/>
|
||||
|
||||
## Security Considerations
|
||||
|
||||
Ensure the configuration of application settings is limited to authorized users only.
|
||||
|
||||
* Use [Administrator roles](./managers) to limit permissions for your users to make changes to your applications.
|
||||
* When [granting projects](../../../concepts/structure/granted_projects) to other organizations, the receiving organization **cannot** see or change the application configuration. They can only assign roles.
|
||||
|
||||
## References
|
||||
|
||||
- [Recommended OIDC Flows](../../integrate/login/oidc/oauth-recommended-flows)
|
||||
Reference in New Issue
Block a user