mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-12 09:05:12 +00:00
d8ea041c56
## 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]>
148 lines
7.6 KiB
Plaintext
148 lines
7.6 KiB
Plaintext
---
|
|
title: Login App
|
|
sidebar_label: Login App
|
|
---
|
|
|
|
To replace the old embedded Login built with Golang and to showcase the use of our session and OIDC APIs, we've created the new [Login app](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#contribute-to-login).
|
|
|
|
## Used Apps And Packages
|
|
|
|
- **Login app**: The Login app used by ZITADEL Cloud, powered by Next.js
|
|
- `@zitadel/proto`: Typescript implementation of Protocol Buffers, suitable for web browsers and Node.js.
|
|
- `@zitadel/client`: Core components for establishing a client connection
|
|
|
|
## Login App
|
|
|
|
The new implementation of the Login app is based on Next.js and implements the [OIDC standard](./oidc-standard) by proxying requests to the ZITADEL backend and using the session API.
|
|
The UI uses the branding and behaves based on the policies and settings of your instance or organization.
|
|
It is also allows users to authenticate directly (without an OIDC context) and self service their account.
|
|
Its set of features will increase with time and its progress will be tracked [here](./login-app#implemented-features).
|
|
|
|
### Architectural Overview
|
|
|
|
The new Login app consists of a confidential (backend) part and a browser (client side) part.
|
|
In addition to that, the OIDC specification builds upon a proxy which is set up in the Next.js middleware. It rewrites requests of the paths `/.well-known/:path*`, `/oauth/:path*`, `/oidc/:path*` to ZITADEL.
|
|
|
|
The backend side of the application is authorized using a machine user's personal access token.
|
|
This token is used to fetch policies and settings from your instances or organization which define how users are authenticated and how the Login app is displayed.
|
|
|
|
The frontend side of the application communicates to the backend side by using a cookie which is set by the server.
|
|
The cookie consists of an id and a token and is bound to a session which is updated continuously.
|
|
|
|
The following illustration shows the architecture of the Login app and a potential authentication code flow starting from an application which implements the OIDC specification respectively.
|
|
|
|
|
|
|
|
_Note that the illustration is just a representation of the architecture and may not specify actual endpoints._
|
|
|
|
The flow starts by the `/authorize` endpoint which is intercepted by the Login app and forwarded to ZITADEL.
|
|
ZITADEL interprets the request and specifically redirects back to the Login app.
|
|
It does so by redirecting to `/login`.
|
|
The Login app is then able to load an [AuthRequest](/reference/api/oidc/zitadel.oidc.v2.OIDCService.GetAuthRequest).
|
|
|
|
The Auth Request defines how users proceed to authenticate. If no special prompts or scopes are set, the Login app brings up the `/loginname` page.
|
|
The /loginname page allows to enter loginname or email of a user which is then used to search for a user.
|
|
If the user is found, a session is created and set as cookie, then the user is redirected to the available authentication method page.
|
|
While the users continues and provides more information, the cookie is hydrated with this information until a final state is reached.
|
|
|
|
The communication from the browser to the server is done by [NextJS Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations).
|
|
The OIDC Auth request is always passed in the url to have a context to the ongoing authentication flow.
|
|
|
|
If enough user information is retrieved and the user is authenticated according to the policies, the flow is finalized by [requesting a the callback url](/reference/api/oidc/zitadel.oidc.v2.OIDCService.CreateCallback) for the auth request and the user is redirected back to the application.
|
|
The application can then request a token calling the /token endpoint of the Login app which is proxied to the ZITADEL API.
|
|
|
|
### Implemented features
|
|
|
|
#### OIDC Standard
|
|
|
|
- [x] Authorization Code Flow with PKCE
|
|
- [x] AuthRequest `hintUserId`
|
|
- [x] AuthRequest `loginHint`
|
|
- [x] AuthRequest `prompt`
|
|
- [x] Login
|
|
- [x] Select Account
|
|
- [x] Create
|
|
- [x] None
|
|
- [ ] Consent
|
|
- Scopes
|
|
- [x] `openid email profile address`
|
|
- [x] `offline access`
|
|
- [x] `urn:zitadel:iam:org:idp:id:{idp_id}`
|
|
- [x] `urn:zitadel:iam:org:project:id:zitadel:aud`
|
|
- [x] `urn:zitadel:iam:org:id:{orgid}`
|
|
- [x] `urn:zitadel:iam:org:domain:primary:{domain}`
|
|
- [ ] AuthRequest UI locales
|
|
- Multifactor
|
|
- [x] Passkeys
|
|
- [x] TOTP
|
|
- [x] OTP via email
|
|
- [x] OTP via SMS
|
|
- Passwordless
|
|
- [x] Passkeys
|
|
- Security Prompts
|
|
- [x] Setup Passkey as Passwordless method
|
|
- [x] Setup TOTP as Multifactor
|
|
- [ ] Password Change
|
|
- Login
|
|
- [x] Email Password
|
|
- [x] Passkey
|
|
- [x] IDPs
|
|
- [x] Google
|
|
- [x] GitHub
|
|
- [x] GitLab
|
|
- [x] Azure
|
|
- [ ] Apple
|
|
- Register
|
|
- [x] Email Password
|
|
- [x] Passkey
|
|
|
|
#### Self service
|
|
|
|
The self service part of the application allows to load the Login app without an OIDC flow.
|
|
Authenticated users are directly able to self service their account.
|
|
|
|
- [ ] Change user information
|
|
- [ ] Password Change
|
|
- [x] Setup Passkey
|
|
- [x] Setup Multifactor
|
|
- [x] Passkeys
|
|
- [x] TOTP
|
|
- [x] OTP via email
|
|
- [x] OTP via SMS
|
|
- [x] Setup Multifactor Passkey (U2F)
|
|
- [x] Validate Account (email verification)
|
|
|
|
### Setup
|
|
|
|
In order to run the new Login app, make sure to follow the instructions in the [contribution guide](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#contribute-to-login).
|
|
|
|
#### How to setup domains for OIDC
|
|
|
|
When setting up the new Login app for OIDC, the domain must be registered on your instance and use https.
|
|
To register your login domain on your instance, [add](/apis/resources/admin/admin-service-add-instance-trusted-domain) your domain on your instances Trusted Domains.
|
|
|
|
#### OIDC Proxy
|
|
|
|
When setting up the new Login app for OIDC, ensure it meets the following requirements:
|
|
|
|
- The OIDC Proxy is deployed and running on HTTPS
|
|
- The OIDC Proxy sets `x-zitadel-public-host` which is the host, your Login app is deployed to `ex. login.example.com`.
|
|
- The OIDC Proxy sets `x-zitadel-instance-host` which is the host of your instance `ex. test-hdujwl.zitadel.cloud`.
|
|
|
|
You can review an example implementation of a middleware [here](https://github.com/zitadel/zitadel/blob/main/apps/login/src/middleware.ts).
|
|
|
|
#### Deploy to Vercel
|
|
|
|
<a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fzitadel%2Fzitadel&env=ZITADEL_API_URL,ZITADEL_SERVICE_USER_ID,ZITADEL_SERVICE_USER_TOKEN&root-directory=apps/login&envDescription=Setup%20a%20service%20account%20with%20IAM_LOGIN_CLIENT%20membership%20on%20your%20instance%20and%20provide%20its%20id%20and%20personal%20access%20token.&project-name=zitadel-login&repository-name=zitadel-login" target="_blank" rel="noopener noreferrer" style={{cursor: "pointer", display: "inline-block", padding: "2px"}}>
|
|
<img src="https://vercel.com/button" alt="Deploy with Vercel" style={{pointerEvents: "none", display: "block"}}/>
|
|
</a>
|
|
|
|
To deploy your own version on Vercel, navigate to your instance and create a service user.
|
|
Create a personal access token (PAT) for the user and copy and set it as `ZITADEL_SERVICE_USER_TOKEN`, then navigate to Default settings and make sure it gets `IAM_LOGIN_CLIENT` permissions.
|
|
Finally set your instance url as `ZITADEL_API_URL`. Make sure to set it without trailing slash.
|
|
Also ensure your login domain is registered on your instance by adding it as a [Trusted Domain](/apis/resources/admin/admin-service-add-instance-trusted-domain).
|
|
|
|
If you want to enforce users to have their email verified, you can set the optional `EMAIL_VERIFICATION` variable to `true` in your environment and your users will be enforced to verify their email address before they can log in.
|
|
|
|
|