diff --git a/docs/docs/guides/integrate/login-ui/typescript-repo.mdx b/docs/docs/guides/integrate/login-ui/typescript-repo.mdx index f2a7879386..a2d76dc3b5 100644 --- a/docs/docs/guides/integrate/login-ui/typescript-repo.mdx +++ b/docs/docs/guides/integrate/login-ui/typescript-repo.mdx @@ -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. + +![Next.js Login Architecture](/img/typescript-login-architecture.png) + +_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 + +[![Deploy with Vercel](https://vercel.com/button)](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. + +![Deploy to Vercel](/img/deploy-to-vercel.png) diff --git a/docs/static/img/deploy-to-vercel.png b/docs/static/img/deploy-to-vercel.png new file mode 100644 index 0000000000..2dd31e7f70 Binary files /dev/null and b/docs/static/img/deploy-to-vercel.png differ diff --git a/docs/static/img/typescript-login-architecture.png b/docs/static/img/typescript-login-architecture.png new file mode 100644 index 0000000000..eac2ed4e70 Binary files /dev/null and b/docs/static/img/typescript-login-architecture.png differ