diff --git a/docs/docs/guides/integrate/login-ui/device-auth.mdx b/docs/docs/guides/integrate/login-ui/device-auth.mdx index 6e2585b39..8ec5a668e 100644 --- a/docs/docs/guides/integrate/login-ui/device-auth.mdx +++ b/docs/docs/guides/integrate/login-ui/device-auth.mdx @@ -47,7 +47,7 @@ scope=openid%20email%20profile The request includes all the relevant information for the OAuth2 Device Authorization Grant and in this example we also have some scopes for the user. You now have to proxy the auth request from your own UI to the device authorization Endpoint of ZITADEL. -For more information, see [OIDC Proxy](./typescript-repo#oidc-proxy) for the necessary headers. +For more information, see [OIDC Proxy](./login-app#oidc-proxy) for the necessary headers. :::note The version and the optional custom URI for the available login UI is configurable under the application settings. diff --git a/docs/docs/guides/integrate/login-ui/typescript-repo.mdx b/docs/docs/guides/integrate/login-ui/login-app.mdx similarity index 67% rename from docs/docs/guides/integrate/login-ui/typescript-repo.mdx rename to docs/docs/guides/integrate/login-ui/login-app.mdx index 44ff9694d..56a72b9c0 100644 --- a/docs/docs/guides/integrate/login-ui/typescript-repo.mdx +++ b/docs/docs/guides/integrate/login-ui/login-app.mdx @@ -1,49 +1,46 @@ --- -title: Typescript Repository -sidebar_label: Typescript Repository +title: Login App +sidebar_label: Login App --- -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. +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). -## Included Apps And Packages +## Used Apps And Packages -- **[login](./typescript-repo#new-login-ui)**: The future login UI used by ZITADEL Cloud, powered by Next.js +- **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 -- `@zitadel/tsconfig`: shared `tsconfig.json`s used throughout the monorepo -- `eslint-config-zitadel`: ESLint preset -## Login UI +## Login App -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 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](./typescript-repo#implemented-features). +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. +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. +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 and a potential authentication code flow starting from an application which implements the OIDC specification respectively. +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. ![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. +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 is then able to load an [AuthRequest](/docs/apis/resources/oidc_service_v2/oidc-service-get-auth-request#get-oidc-auth-request-details). +The Login app is then able to load an [AuthRequest](/docs/apis/resources/oidc_service_v2/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 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. @@ -52,7 +49,7 @@ The communication from the browser to the server is done by [NextJS Server Actio 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_v2/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. +The application can then request a token calling the /token endpoint of the Login app which is proxied to the ZITADEL API. ### Implemented features @@ -68,7 +65,7 @@ The application can then request a token calling the /token endpoint of the logi - [x] None - [ ] Consent - Scopes - - [x] `openid email profile address`` + - [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` @@ -101,7 +98,7 @@ The application can then request a token calling the /token endpoint of the logi #### Self service -The self service part of the application allows to load the login without an OIDC flow. +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 @@ -117,26 +114,28 @@ Authenticated users are directly able to self service their account. ### 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). +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. +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](/docs/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: +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 is deployed to `ex. login.example.com`. +- 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 middlware [here](https://github.com/zitadel/typescript/blob/main/apps/login/src/middleware.ts). +You can review an example implementation of a middlware [here](https://github.com/zitadel/zitadel/blob/main/apps/login/src/middleware.ts). #### 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_TOKEN&root-directory=apps/login&envDescription=Setup%20a%20service%20account%20with%20IAM_LOGIN_CLIENT%20membership%20on%20your%20instance%20and%20provide%20its%20personal%20access%20token.&project-name=zitadel-login&repository-name=zitadel-login) + + Deploy with Vercel + 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. diff --git a/docs/docs/guides/integrate/login-ui/oidc-standard.mdx b/docs/docs/guides/integrate/login-ui/oidc-standard.mdx index a8f19c9ed..d09ccb484 100644 --- a/docs/docs/guides/integrate/login-ui/oidc-standard.mdx +++ b/docs/docs/guides/integrate/login-ui/oidc-standard.mdx @@ -37,7 +37,7 @@ https://login.example.com/oauth/v2/authorize?client_id=170086824411201793%40your The auth request includes all the relevant information for the OIDC standard and in this example we also have a login hint for the login name "minnie-mouse". You now have to proxy the auth request from your own UI to the authorize Endpoint of ZITADEL. -For more information, see [OIDC Proxy](./typescript-repo#oidc-proxy) for the necessary headers. +For more information, see [OIDC Proxy](./login-app#oidc-proxy) for the necessary headers. :::note The version and the optional custom URI for the available login UI is configurable under the application settings. diff --git a/docs/docs/guides/integrate/login-ui/saml-standard.mdx b/docs/docs/guides/integrate/login-ui/saml-standard.mdx index 4bef906e7..459113e53 100644 --- a/docs/docs/guides/integrate/login-ui/saml-standard.mdx +++ b/docs/docs/guides/integrate/login-ui/saml-standard.mdx @@ -37,7 +37,7 @@ https://login.example.com/saml/v2/SSO?SAMLRequest=nJLRa9swEMb%2FFXHvjmVTY0fUhqxh The SAML request includes all the relevant information for the SAML standard, which includes the RelayState, the used binding and other information. You now have to proxy the SAML request from your own UI to the SSO Endpoint of ZITADEL. -For more information, see [OIDC Proxy](./typescript-repo#oidc-proxy) for the necessary headers. +For more information, see [OIDC Proxy](./login-app#oidc-proxy) for the necessary headers. :::note The version and the optional custom URI for the available login UI is configurable under the application settings. diff --git a/docs/docs/guides/integrate/login/hosted-login.mdx b/docs/docs/guides/integrate/login/hosted-login.mdx index a9ed18c38..be89e9659 100644 --- a/docs/docs/guides/integrate/login/hosted-login.mdx +++ b/docs/docs/guides/integrate/login/hosted-login.mdx @@ -129,36 +129,10 @@ With the introduction of passkeys the gesture can be provided on ANY of the user This is not strictly the device where the login flow is being executed (e.g., on a mobile device). The user experience depends mainly on the operating system and browser. -## Hosted Login Version 2 (Beta) +## Hosted Login Version 2 -We have worked on a new, self-hostable implementation of our hosted login built with Next.js and leveraging our [Session API](/docs/guides/integrate/login/login-users#zitadels-session-api). -This solution empowers you to easily fork and customize the login experience to perfectly match your brand and needs. - -In this initial release, the new login is available for self-hosting only. We'll be progressively replacing the built-in login with this improved version, built with [TypeScript](https://github.com/zitadel/typescript). - -### Current State - -:::info -The documentation describes the state of the feature in ZITADEL V3. -::: - -Our primary goal for the TypeScript login system is to replace the existing login functionality within Zitadel Core, which is shipped with Zitadel automatically. This will allow us to leverage the benefits of the new system, including its modular architecture and enhanced security features. - -To achieve this, we are actively working on implementing the core features currently available in Zitadel Core, such as: - -- **Authentication Methods:** - - Username and Password - - Passkeys - - Multi-Factor Authentication (MFA) - - External Identity Providers (OIDC, SAML, etc.) -- **OpenID Connect (OIDC) Compliance:** Adherence to the OIDC standard for seamless integration with various identity providers. -- **Customization**: - - Branding options to match your organization's identity. - - Flexible configuration settings to tailor the login experience. - -The full feature list can be found [here](https://github.com/zitadel/typescript?tab=readme-ov-file#features-list). - -As we continue to develop the TypeScript login system, we will provide regular updates on its progress and new capabilities. +We have worked on a new, self-hostable implementation of our hosted MIT licensed login built with Next.js and leveraging our [Session API](/docs/guides/integrate/login/login-users#zitadels-session-api). +This solution empowers you to easily customize the login experience to perfectly match your brand and needs. ### Limitations @@ -172,17 +146,21 @@ For the first implementation we have excluded the following features: - As passkey and u2f is bound to a domain, it is important to notice, that setting up the authentication possibility in the ZITADEL management console (Self-service), will not work if the login runs on a different domain - Custom Login Texts -### Beta Testing +### Important Changes -The TypeScript login system is currently in beta testing. Your feedback is invaluable in helping us refine and improve this new solution. -At your convenience please open any issues faced on our Typescript Login GitHub repository to report bugs or suggest enhancements while more general feedback can be shared directly to fabienne@zitadel.com. -Your contributions will play a crucial role in shaping the future of our login system. Thank you for your support! +- **Create Users:** The new TypeScript Login app is built with the session and the user V2 API, the users V2 API does have some differences to the v1 API, so make sure you create users through the new API. +- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: `${CUSTOM_DOMAIN}/idps/callback` +- **Passkey/U2F:** Those authentication methods are bound to a domain. As your new login runs on a different domain than the previous login, existing passwordless authentication and u2f (fingerprint, face id, etc.) can’t be used. Also when they are managed through the management console of ZITADEL, they are added on a different domain. +
+ *Note: If you run the login on a subdomain of your current instance, this problem + can be avoided. E.g myinstance.zitadel.cloud and login.myinstance.zitadel.cloud* #### Step-by-step Guide -**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https:///ui/v2/login` on your Zitadel Cloud custom domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication. +**Using the new login:** To use the new login without changing your current setup, the easiest way is to visit `https:///ui/v2/login` on your Zitadel Cloud custom domain. +You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication. -**Customizing the new login:** The easiest way to actually customizing it is to fork the https://github.com/zitadel/typescript repo and use the "Deploy" button to run your code on Vercel. +**Customizing the new login:** The easiest way to actually customizing it is to fork the https://github.com/zitadel/zitadel repo and use the [Deploy with Vercel button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) to run your login code on Vercel. @@ -199,12 +177,12 @@ Your contributions will play a crucial role in shaping the future of our login s - The simplest way to deploy the new login for yourself is by using the [“Deploy” button in our repository](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) to deploy the login directly to your Vercel. + The simplest way to deploy the new login for yourself is by using the [Deploy with Vercel button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) to deploy the login directly to your Vercel. 1. [Create a service user](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-with-a-pat) with a PAT in your instance 2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (CUSTOM_DOMAIN/ui/console/instance?id=organizations) Note: [Zitadel Manager Guide](https://zitadel.com/docs/guides/manage/console/managers) - 3. Deploy login to Vercel: You can do so by directly clicking the [“Deploy” button](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) at the bottom of the readme in our [repository](https://github.com/zitadel/typescript) + 3. Deploy login to Vercel: You can do so by directly clicking the [“Deploy” button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) in our [repository](https://github.com/zitadel/zitadel) 4. If you have used the deploy button in the steps before, you will automatically be asked for this step. Enter the environment variables in Vercel - PAT - ZITADEL_API_URL (Example: https://my-domain.zitadel.cloud, no trailing slash) @@ -221,13 +199,3 @@ Your contributions will play a crucial role in shaping the future of our login s -### Important Notes - -As this feature is currently in Beta, please be aware of some potential workarounds and important considerations before implementation. - -- **Create Users:** The new typescript login is built with the session and the user V2 API, the users V2 API does have some differences to the v1 API, so make sure you create users through the new API. -- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: `${CUSTOM_DOMAIN}/idps/callback` -- **Passkey/U2F:** Those authentication methods are bound to a domain. As your new login runs on a different domain than the previous login, existing passwordless authentication and u2f (fingerprint, face id, etc.) can’t be used. Also when they are managed through the management console of ZITADEL, they are added on a different domain. -
- *Note: If you run the login on a subdomain of your current instance, this problem - can be avoided. E.g myinstance.zitadel.cloud and login.myinstance.zitadel.cloud* diff --git a/docs/sidebars.js b/docs/sidebars.js index 53da9b51c..08a3fcf2f 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -360,7 +360,7 @@ module.exports = { "guides/integrate/login-ui/oidc-standard", "guides/integrate/login-ui/saml-standard", "guides/integrate/login-ui/device-auth", - "guides/integrate/login-ui/typescript-repo", + "guides/integrate/login-ui/login-app", ], }, { diff --git a/docs/vercel.json b/docs/vercel.json index 04909d074..2c1dc1d14 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -221,6 +221,11 @@ "destination": "/docs/guides/integrate/login/hosted-login#password-reset", "permanent": true }, + { + "source": "/docs/guides/integrate/login-ui/typescript-repo", + "destination": "/docs/guides/integrate/login-ui/login-app", + "permanent": true + }, { "source": "/docs/legal/service-description/billing", "destination": "https://help.zitadel.com/pricing-and-billing-of-zitadel-services",