TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-02-28 15:47:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(login,v2): describe cloud usage (#9404)

Browse Source 
# Which Problems Are Solved

Users don't have the information that and how they can use the new login
without customization on their Zitadel cloud domain.

# How the Problems Are Solved

The How-to is described alongside customized deployment with Vercel
how-to.

This section is changed:
https://docs-git-docs-login-v2-cloud-zitadel.vercel.app/docs/guides/integrate/login/hosted-login#step-by-step-guide

# Additional Context

- Closes https://github.com/zitadel/DevOps/issues/98

---------

Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
This commit is contained in:
Elio Bischof 2025-02-26 16:46:42 +01:00 committed by GitHub
parent 4375c065b2
commit 77499ce603
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 47 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/docs/guides/integrate/login/_prevent-lockout.mdx Normal file
View File

@ -0,0 +1,4 @@
:::caution[Don't Lock Yourself Out of Your Instance]
Before you change your Zitadel configuration, we highly recommend you to create a service user with a personal access token (PAT) and the IAM_OWNER role.
In case something breaks, you can use this PAT to revert your changes or fix the configuration so you can use a login UI again.
:::

58
docs/docs/guides/integrate/login/hosted-login.mdx
View File

@ -3,6 +3,10 @@ title: Login users into your application with a hosted login UI
sidebar_label: Hosted Login UI
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PreventLockout from './_prevent-lockout.mdx';
ZITADEL provides a hosted single-sign-on page to securely sign-in users to your applications.
ZITADEL's hosted login page serves as a centralized authentication interface provided for applications that integrate ZITADEL.
As a developer, understanding the hosted login page is essential for seamlessly integrating authentication into your application.
@ -177,22 +181,46 @@ Your contributions will play a crucial role in shaping the future of our login s
#### Step-by-step Guide
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.
**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https://<YOUR_ZITADEL_INSTANCE_DOMAIN>/ui/v2/login` on your Zitadel Cloud instance domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication.
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 (YOUR_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, be 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)
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)
5. Add the domain where your login UI is hosted to the [trusted domains](https://zitadel.com/docs/apis/resources/admin/admin-service-add-instance-trusted-domain) in Zitadel. (Example: my-new-zitadel-login.vercel.app)
6. Use the new login in your application. You have three different options on how to achieve this
1. Enable the new login on your application configuration and add the URL of your login UI, with that settings Zitadel will automatically redirect you to the new login if you call the old one.
![Login V2 Application Configuration](/img/guides/integrate/login/login-v2-app-config.png)
2. Enable the [loginV2 feature](https://zitadel.com/docs/apis/resources/feature_service_v2/feature-service-set-instance-features) on the instance and add the URL of your login. If you enable this feature, the login will be used for every application configured in your Zitadel instance. (Example: https://my-new-zitadel-login.vercel.app)
3. Change the issuer in the code of your application to the new domain of your login
7. Enforce users to have their email verified. By setting `EMAIL_VERIFICATION` to `true` in your environment variables, your users will be enforced to verify their email address before they can log in.
**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.
<Tabs queryString="deployment">
<TabItem value="zitadel_cloud" label="Activate Zitadel Cloud V2 Login" default="true">
Zitadel Cloud provides the V2 login at the fixed path `/ui/v2/login`.
<PreventLockout/>
To activate it to authenticate on your Zitadel Cloud apps, you can follow one of these steps:
1. Enable the new login on your application configuration and point it to `/ui/v2/login`. With these settings, Zitadel will automatically redirect you to the new login if you call the old one.
![Login V2 Application Configuration](/img/guides/integrate/login/login-v2-app-config.png)
2. Enable the [loginV2 feature](https://zitadel.com/docs/apis/resources/feature_service_v2/feature-service-set-instance-features) on the instance and add the base URI `/ui/v2/login`. If you enable this feature, the login will be used for every application configured in your Zitadel instance. (Example: https://your-zitadel-instance.zitadel.cloud/ui/v2/login)
</TabItem>
<TabItem value="vercel_custom" label="Vercel Custom Login Deployment">
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.
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 (YOUR_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)
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)
5. Add the domain where your login UI is hosted to the [trusted domains](https://zitadel.com/docs/apis/resources/admin/admin-service-add-instance-trusted-domain) in Zitadel. (Example: my-new-zitadel-login.vercel.app)
6. Use the new login in your application.
<PreventLockout/>
You have three different options on how to achieve this:
1. Enable the new login on your application configuration and add the URL of your login UI. With these settings, Zitadel will automatically redirect you to the new login if you call the old one.
![Login V2 Application Configuration](/img/guides/integrate/login/login-v2-app-config.png)
2. Enable the [loginV2 feature](https://zitadel.com/docs/apis/resources/feature_service_v2/feature-service-set-instance-features) on the instance and add the URL of your login. If you enable this feature, the login will be used for every application configured in your Zitadel instance. (Example: https://my-new-zitadel-login.vercel.app)
3. Change the issuer in the code of your application to the new domain of your login
7. Enforce users to have their email verified. By setting `EMAIL_VERIFICATION` to `true` in your environment variables, your users will be enforced to verify their email address before they can log in.
</TabItem>
</Tabs>
### Important Notes