mirror of
https://github.com/zitadel/zitadel.git
synced 2025-05-02 06:40:48 +00:00
docs: typescript login (#7621)
* typescript docs * docs * self service part * deploy part * headers * update description * illustration description * endpoints * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * rm scope * Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * screenshot deploy to vercel --------- Co-authored-by: Livio Spring <livio.a@gmail.com>
This commit is contained in:
Max Peintner
GitHub
parent
4c945f8bdc
commit
20fb032743
@ -5,11 +5,10 @@ sidebar_label: Typescript Repository
|
||||
|
||||
To replace our current golang built login UI and showcase the use of our new resource, session and OIDC APIs, we've created the [Typescript Repository](https://github.com/zitadel/typescript).
|
||||
The typescript repository contains all TypeScript and JavaScript packages and applications you need to create your own Login UI using the ZITADEL APIs.
|
||||
The repo implements the [OIDC standard](./oidc-standard)
|
||||
|
||||
## Included Apps And Packages
|
||||
|
||||
- `login`: The future login UI used by ZITADEL Cloud, powered by Next.js
|
||||
- **[login](./typescript-repo#new-login-ui)**: The future login UI used by ZITADEL Cloud, powered by Next.js
|
||||
- `@zitadel/server`: core components for establishing node client connection, grpc stub
|
||||
- `@zitadel/client`: core components for establishing web client connection, grpc stub
|
||||
- `@zitadel/react`: shared React utilities and components built with Tailwind CSS
|
||||
@ -17,7 +16,46 @@ The repo implements the [OIDC standard](./oidc-standard)
|
||||
- `@zitadel/tsconfig`: shared `tsconfig.json`s used throughout the monorepo
|
||||
- `eslint-config-zitadel`: ESLint preset
|
||||
|
||||
## Implemented features of OIDC Standard
|
||||
## Login UI
|
||||
|
||||
The new implementation of the login 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](./typescript-repo#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 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 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 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 is then able to load an [AuthRequest](/docs/apis/resources/oidc_service/oidc-service-get-auth-request#get-oidc-auth-request-details).
|
||||
|
||||
The Auth Request defines how users proceed to authenticate. If no special prompts or scopes are set, the login brings up the `/loginname` page.
|
||||
The /loginname page allows to enter loginname or email of a user. User discovery is implemented at /api/loginname and if the user is found, they will be redirected to the available authentication method page.
|
||||
Right after the user is found, a session is created and set as cookie.
|
||||
This cookie is then hydrated with more information once the users continues.
|
||||
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](/docs/apis/resources/oidc_service/oidc-service-create-callback) 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 which is proxied to the ZITADEL API.
|
||||
|
||||
### Implemented features
|
||||
|
||||
#### OIDC Standard
|
||||
|
||||
- [x] Authorization Code Flow with PKCE
|
||||
- [x] AuthRequest `hintUserId`
|
||||
@ -25,8 +63,9 @@ The repo implements the [OIDC standard](./oidc-standard)
|
||||
- [ ] AuthRequest `prompt`
|
||||
- [x] Login
|
||||
- [x] Select Account
|
||||
- [ ] Consent
|
||||
- [x] Create
|
||||
- [x] None
|
||||
- [ ] Consent
|
||||
- Scopes
|
||||
- [x] `openid email profile address``
|
||||
- [x] `offline access`
|
||||
@ -53,13 +92,41 @@ The repo implements the [OIDC standard](./oidc-standard)
|
||||
- [ ] Azure
|
||||
- [ ] Apple
|
||||
- Register
|
||||
|
||||
- [x] Email Password
|
||||
- [x] Passkey
|
||||
|
||||
## How to setup domains
|
||||
#### Self service
|
||||
|
||||
In order to use the new login app, the domain must be registered on your instance and use https.
|
||||
The self service part of the application allows to load the login without an OIDC flow.
|
||||
Authenticated users are directly able to self service their account.
|
||||
|
||||
- [ ] Change user information
|
||||
- [ ] Password Change
|
||||
- [x] Setup Passkey
|
||||
- [ ] Setup Multifactor TOTP
|
||||
- [ ] Setup Multifactor Passkey (U2F)
|
||||
- [ ] Validate Account (email verification)
|
||||
|
||||
### Setup
|
||||
|
||||
In order to run the new login app, make sure to follow the instructions in the [Readme](https://github.com/zitadel/typescript/blob/main/README.md#run-login-ui).
|
||||
|
||||
#### 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.
|
||||
If you are using a self hosted instance, [install](/docs/apis/resources/system/system-service-add-domain) your domain on your instance using the system service.
|
||||
|
||||
The login using our cloud service is still experimental, but you can purchase your domain on zitadel.com, install it on your domain following [our guide](/docs/guides/manage/cloud/instances#add-custom-domain).
|
||||
If you want to use the login with your cloud instance, you can purchase your domain on zitadel.com, install it on your domain following [our guide](/docs/guides/manage/cloud/instances#add-custom-domain).
|
||||
After your domain has been verified, you can reconfigure your DNS settings in order to deploy the login on your own.
|
||||
|
||||
#### Deploy to Vercel
|
||||
|
||||
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fzitadel%2Ftypescript&env=ZITADEL_API_URL,ZITADEL_SERVICE_USER_ID,ZITADEL_SERVICE_USER_TOKEN&root-directory=apps/login&envDescription=Setup%20a%20service%20account%20with%20IAM_OWNER%20membership%20on%20your%20instance%20and%20provide%20its%20id%20and%20personal%20access%20token.&project-name=zitadel-login&repository-name=zitadel-login)
|
||||
|
||||
To deploy your own version on Vercel, navigate to your instance and create a service user.
|
||||
Copy its id from the overview and set it as `ZITADEL_SERVICE_USER_ID`.
|
||||
Then create a personal access token (PAT), copy and set it as `ZITADEL_SERVICE_USER_TOKEN`, then navigate to your instance settings and make sure it gets `IAM_OWNER` permissions.
|
||||
Finally set your instance url as `ZITADEL_API_URL`. Make sure to set it without trailing slash.
|
||||
|
||||
|
||||
|
||||
BIN
docs/static/img/deploy-to-vercel.png
vendored
Normal file
BIN
docs/static/img/deploy-to-vercel.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 280 KiB |
BIN
docs/static/img/typescript-login-architecture.png
vendored
Normal file
BIN
docs/static/img/typescript-login-architecture.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 87 KiB |
Loading…
x
Reference in New Issue
Block a user