Delegated access management

Hosted Login

Multifactor Authentication

Passwordless Authentication

Audit Trail

Identity Brokering

Platform

Service Accounts

Features

Easy integration

B2B (Business to Business)

Self Service

Existing identities

Secure authentication

Use Cases

Learn how to install, setup, and use ZITADEL.

Documentation

ZITADEL Cloud

Self-hosting

Trust center

Examples and Guides

Github Repository

Develop

Get Started

Contribute

Roadmap

Changelog

About Us

Jobs

Contact

Company

Read the blog

Sign up

Login

Pricing

Blog

Some of our past blog posts cover the topics of [designing a custom login flow](https://zitadel.com/blog/custom-login) with our [Typescript-based login](https://zitadel.com/blog/typescript-login) system.

In this post, we dive into the key aspects of hosting your own custom login UI using the Zitadel typescript library. We will guide you through the steps to deploy your own fully customized login user interface (UI) to Vercel (or the hosting service you prefer) and seamlessly connect it to your Zitadel Instance.

## Deploying the custom login UI:

### 1. Create a Zitadel Cloud instace

Create a free Zitadel Cloud Instance, that will be used to run this demo (you can also use a self-hosted Zitadel instance, if you prefer).
[Zitadel Cloud Instance Setup Guide](https://zitadel.com/docs/guides/manage/cloud/start)


---

### 2. Create a User

- Create a User of type *Machine* (formerly service user).
- Assign the **IAM Login Client Administrator** role.https://zitadel.com/docs/guides/manage/console/managers
    
    ![image title](https://cdn.sanity.io/images/y3uu7rkl/production/4595ca73d79dd0a0c0418e6f404f1d0e5658c03f-1488x720.png)
    

---

### 3. Create a PAT (Personal Access Token)

Create a PAT for the Service User and save it — you will need this later.

![image title](https://cdn.sanity.io/images/y3uu7rkl/production/e825e6707b2654046147d513f5380f45cbb50348-1512x770.png)


---

### 4. Fork and Deploy the Login UI

- Fork the TypeScript login UI repo: [GitHub - zitadel/typescript](https://github.com/zitadel/typescript)
- Deploy the project to your Vercel account. You can deploy directly via the Vercel deploy button in the repo README.
    - [Vercel GitHub Deployment Guide](https://vercel.com/docs/git/vercel-for-github)
        
        ![image title](https://cdn.sanity.io/images/y3uu7rkl/production/634952a6b75fe242e0526721277a06418e55514a-300x118.png)
        

### 4a. Set Environment Variables

Set the environment variables required by the app:

![image title](https://cdn.sanity.io/images/y3uu7rkl/production/b57ef92fbc8d3383dbc86cc52edc61ca94fa6c15-1924x564.png)

- **`ZITADEL_API_URL`**: The URL where your Zitadel instance is hosted.
    
    Example:
    
    `https://<INSTANCE_NAME>.zitadel.cloud`
    
- **`ZITADEL_SERVICE_USER_TOKEN`**: A Personal Access Token (PAT) created in step 3 of the setup process. This token authenticates your service user.
- **`EMAIL_VERIFICATION`** (optional): Set to `true` if you require users to verify their email before they can proceed.

eg:

```
ZITADEL_API_URL=https://<INSTANCE_NAME>.zitadel.cloud
ZITADEL_SERVICE_USER_TOKEN=<your_pat_here>
EMAIL_VERIFICATION=true
```


---

### 5. Add the Vercel Domain as a Trusted Domain

After deployment completes, copy your Vercel domain (without https://) and add it as a trusted domain to your Zitadel instance.

- Use the Zitadel Management API with an IAM_OWNER access token (not the PAT from step 3). You can use Postman for this.
- [How to get access tokens](https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-apis#how-to-access-zitadel-apis)
- [Trusted domains API endpoint](https://zitadel.com/docs/apis/resources/admin/admin-service-add-nstance-trusted-domain)

![image title](https://cdn.sanity.io/images/y3uu7rkl/production/4215a74dab41125c3a7819e242de2021849b7b5c-1500x284.png)


---

### 6. Configure Your Zitadel Application

- Open your Zitadel Console.
- Create a new application.
- Enable the new login UI checkbox.
- Add your Vercel app URL as a Custom Base URL.
[React Login UI Setup Guide](https://zitadel.com/docs/examples/login/react#set-up-application-and-obtain-keys)
    
   ![image title](https://cdn.sanity.io/images/y3uu7rkl/production/05ec7d3c6e478e483042fdacc7804937803502b2-1482x1052.png)
 
 
---

### 7. Test Your Self-Hosted Login UI

To test your self-hosted login UI, you can use the [Zitadel React quickstart application](https://github.com/zitadel/zitadel-react).

- Replace authority and client ID with your Vercel deployment URL and Zitadel app client ID.
- Run the app and test login.
    
    ![image title](https://cdn.sanity.io/images/y3uu7rkl/production/096d42c0d9984d687768b93388e149eb1fa4215d-1412x288.png)
    

---

## Conclusion

Self-hosting the Zitadel TypeScript login UI lets you fully customize your authentication experience while staying secure and scalable. With just a few steps, you can deliver a seamless, branded login flow powered by Zitadel — **including the ability to use a different custom login domain per application, a powerful level of flexibility that most of our competitors don’t offer.**

This post dives into some of the key aspects of hosting your own custom login UI using the Zitadel typescript library.

How to self-host the Zitadel typescript login UI?

When exploring a new application, one of the first touchpoints a user encounters is the login experience. While a simple, generic screen can be an effective and efficient way to approach the beginning of your user flow, building out a custom login interface allows you to deliver a branded, seamless, memorable experience that aligns with your app’s functionality, user interface (UI), user experience (UX), and design. 

For scenarios where a simple username/password and  'forgot your password?' buttons aren't enough, Zitadel offers a robust, API-driven solution that supports advanced authentication methods, including passkeys, multi-factor authentication (MFA), and enterprise or social login integrations, allowing you to create and smoothly integrate a fully customized login UI.
## Custom Login: The Use Case
While we provide a [powerful built-in authentication flow](https://zitadel.com/docs/guides/integrate/login/hosted-login) compatible with OIDC & SAML standards, we recognize that some organizations require more flexibility to create more customized and advanced workflows that align with specific business logic, compliance requirements, security policies, or user experience needs. This is why we support customized logins where you have the ability to integrate your system while using our robust authentication and authorization capabilities. This gives you complete  control of branding, user experience, and flows without compromising security.

Your login page isn't just a gateway to your app; it is an opportunity to present a strong first impression. By using our customizable APIs, you will improve the aesthetic experience and tailor authentication to meet your needs. Whether you are managing [multi-factor authentication](https://zitadel.com/docs/guides/integrate/login-ui/mfa), [adding external login capabilities](https://zitadel.com/docs/guides/integrate/login-ui/external-login), or even exploring [integrating passkeys](https://zitadel.com/docs/guides/integrate/login-ui/passkey) into your workflow, Zitadel makes it easier to implement advanced authentication flows while ensuring a smooth user journey.

Below is an example of a login flow implementation shown in our [TypeScript repository](https://zitadel.com/docs/guides/integrate/login-ui/typescript-repo), which provides all of the packages and components you need to build your own branded login user interface using Zitadel's APIs.

![](https://cdn.sanity.io/images/y3uu7rkl/production/fbbb86dfe32182ba8aa326c127f96c12b5568e4a-2544x825.png)


## How does Zitadel Support Custom Logins?
	
With Zitadel, you can implement custom logins through our [session](https://zitadel.com/docs/apis/resources/session_service_v2) and user APIs. These APIs allow you to authenticate users through various methods, including traditional username/password, passkeys, or external Identity Providers (IDPs). 
You have full  control over the session lifecycle, starting from initiating the login process to managing user sessions after authentication. This includes configuring session expiration, integrating multi-factor authentication (MFA), and deploying any additional security mechanisms that strengthen the user verification process while maintaining compliance with authentication standards.
### Exploring How Our Users Leverage Custom Logins
Building out your custom login with Zitadel is use-case-agnostic. Our users utilize custom logins with Zitadel in a variety of approaches. 

Here are two examples:

**Example 1: Exploring authentication and accessibility**

One of our users, [Melvin Weiershäuser](https://github.com/mweiershaeuser), was exploring authentication methods and accessibility for his academic thesis. For this project, he required a custom login to compare traditional authentication and passkey methods to assess their impact on accessibility and the development of more accessible user experiences. Initially, he evaluated both Zitadel and Keycloak and ultimately chose Zitadel due to the flexibility in integrating a custom login interface. To complete the project, he built his solution with Zitadel and Next.js, with the implementation supporting both multi-factor authentication (MFA) and passkeys. Key features included passkey registration, service user integration for login control, and session management. By leveraging Zitadel’s authentication capabilities, he was able to provide valuable insights into how login methods can influence accessibility and usability while maintaining a smooth authentication experience. The project is [publicly available on GitHub](https://github.com/mweiershaeuser/sso) for those interested in exploring it further.

**Example 2: Designing a secure login for a banking app**

Security is key when developing a user authentication flow for a mobile application for fintech companies. One such fintech company, an IT and digitalization partner for leading financial and insurance service providers, set out to provide a more seamless and branded login process that integrated better with their own application.  They built out a custom login using Swift and Android Java while integrating a .NET backend with our session API to ensure a secure, device-bound auth process. By customizing their login experience with Zitadel, they were able to enable multi-user handling, token rotation, and enhance security through session revocation. This addressed their need for heightened protection, paired with a frictionless user experience. 
## Looking Ahead
We are committed to further enhancing our API and SDK offerings and make it easier for developers to implement custom logins. We  recently launched our ready-to-use [TypeScript-based login system](https://zitadel.com/blog/typescript-login) that reduces development time and effort for our users. 

Start building your custom login UI today, and join a growing community of developers shaping the future of authentication. If you have any  questions as you are building out a custom login and integrating it with Zitadel, contact us through [our community](http://zitadel.com/chat). 






Learn more about building out your own login UI integrated with Zitadel and explore real-world approaches building out secure custom login flows.

Designing a Login Flow That Fits with Zitadel


We've developed a new TypeScript-based login system to streamline the authentication process for our customers. This solution offers a **flexible**, **customizable**, and **self-hostable** login experience.

By providing a ready-to-use login solution, we aim to reduce development time and effort for our customers. The open-source nature of the project allows for easy customization and adaptation to specific business needs.

Our immediate goal is to enable customers to self-host the login system. In the future, we plan to fully integrate this new login system into our cloud offering, providing a more robust and secure authentication experience. We plan to initiate the first cloud integration by the end of February. New customers will be automatically provisioned with the new cloud-based login. Existing customers will have the flexibility to migrate their entire instance or individual applications at their preferred time.

The new TypeScript login system offers several key improvements:

- **Leverages Modern Technology**: By utilizing our newly developed [session APIs](https://zitadel.com/docs/apis/resources/session_service_v2), we've significantly enhanced the security and performance of the authentication process.
- **Enhanced Features**: The system introduces new features such as user invitation flows and passkey-only authentication, providing greater flexibility and convenience for our users.
- **Improved Developer Experience**: The use of TypeScript, a widely adopted language in frontend development, makes the codebase more accessible and easier to contribute to. This encourages community involvement and fosters rapid development.

## Current State

Our primary goal for the TypeScript login system is to fully replace the existing login functionality within the current Zitadel version, which is shipped with Zitadel default. 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, 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.

<figure>
  <img
    src="/blog/2025-01-21-typescript-login-01.png"
    width="100%"
    alt="Login UI with authentication method loginname, Apple, Google OIDC, Google and GitLab"
  />
</figure>

## Limitations

For the first release we have excluded the following features:

- SAML 2.0 ([IdP](https://zitadel.com/docs/apis/saml/endpoints) & [SP](https://zitadel.com/docs/guides/integrate/identity-providers/mocksaml))
- [Generic JWT IDP](https://zitadel.com/docs/guides/integrate/identity-providers/jwt_idp)
- [LDAP IDP](https://zitadel.com/docs/guides/integrate/identity-providers/ldap)
- [Device Authorization Grants](https://zitadel.com/docs/guides/integrate/login/oidc/device-authorization)
- Timebased features
  - [Lockout Settings](https://zitadel.com/docs/guides/manage/console/default-settings#lockout)
  - [Password Expiry Settings](https://zitadel.com/docs/guides/manage/console/default-settings#password-expiry)
  - [Login Settings - Multifactor init prompt](https://zitadel.com/docs/guides/manage/console/default-settings#login-behavior-and-access)
  - [Force MFA on external authenticated users](https://zitadel.com/docs/guides/manage/console/default-settings#login-behavior-and-access)
- [Passkey](https://zitadel.com/docs/guides/manage/console/default-settings#passwordless)/[U2F Setup](https://zitadel.com/docs/guides/manage/console/default-settings#multifactor-mfa)
  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](https://zitadel.com/docs/guides/manage/console/default-settings#login-interface-texts) configurations are not used in the typescript login, if you want to customize them, fork the repository and change the texts to you liking

## Beta Testing

The TypeScript login system is currently in the beta testing phase. Your feedback is highly valuable in helping us refine and improve this new solution.

At your convenience please open any issues faced on our [Typescript Login GitHub repository](https://github.com/zitadel/typescript) to report bugs or suggest enhancements while more general feedback can be shared directly to the [corresponding discord thread](https://discord.com/channels/927474939156643850/1329100936127320175/threads/1329827099606782093).
Your contributions will play a crucial role in shaping the future of our login system.
Thank you for your support!

### Steps to start testing

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 (ZITADEL_SERVICE_USER_ID) with a PAT](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-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)
   [https://zitadel.com/docs/guides/manage/console/managers](https://zitadel.com/docs/guides/manage/console/managers)
3. Deploy login to Vercel: You can do so, be directly clicking the “Deploy” button at the bottom of the readme in our [repository](https://github.com/zitadel/typescript)
   <figure>
     <img src="/blog/2025-01-21-typescript-login-02.png" width="100%" alt="Deploy to vercel button" />
   </figure>
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
   - ZITADEL_SERVICE_USER_ID
   - 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. To implement the new login, choose one of the following options:
   1. Enable the new login in your application configuration: Add the URL of your new login UI to your application’s settings. Zitadel will automatically redirect users to the new login if they attempt to use the old one.
   2. Enable the loginV2 feature on the instance:Activate the LoginV2 feature in your Zitadel instance and specify the URL of your new login. This will apply the new login for all applications configured under your Zitadel instance. Example: https://my-new-zitadel-login.vercel.app. More details: [Zitadel Documentation](https://zitadel.com/docs/apis/resources/feature_service_v2/feature-service-set-instance-features)
   3. Update the issuer URL in your application configuration: Change the issuer domain in your application configuration to match the new login domain.

For more information read our [Login V2 documentation](https://zitadel.com/docs/guides/integrate/login/hosted-login#hosted-login-version-2-beta)

## Important Notes

- **User Creation**: The new TypeScript login utilizes the Session and User V2 APIs. Note that the User V2 API introduces some changes compared to the V1 API. Ensure you create users using the new V2 API to maintain compatibility.
- **External Identity Providers (IDPs)**: To enable login with external identity providers, such as Google or Apple, follow our existing setup guides. Ensure that you use the following redirect URL: $YOUR-DOMAIN/idps/callback.
- **Passkey/U2F Authentication**: These authentication methods are domain-bound. Since your new login operates on a different domain than the previous one, existing passwordless authentication (e.g., fingerprint, Face ID) and U2F methods cannot be reused. Additionally, when managed through the Zitadel console, they will be tied to the old domain. Note: To avoid this issue, consider running the new login on a subdomain of your current instance (e.g., myinstance.zitadel.cloud and login.myinstance.zitadel.cloud).

## Customization / Feature requests

If you have specific customization needs beyond the current capabilities of the Typescript login offering, please follow one of these two options:

1. **Fork the Repository**: By forking the [Typescript Login](https://github.com/zitadel/typescript) repository on GitHub, you can directly modify the source code to implement your desired features. This offers maximum flexibility and control over the login system.
2. **Build Your Own Login UI**: For full customization control, you can leverage our Session API to build your own login interface. This allows you to create a fully tailored experience that aligns perfectly with your application's design and functionality. A detailed guide on how to use the Session API is available [here](https://zitadel.com/docs/guides/integrate/login-ui).

## Future plans

Our roadmap for the TypeScript login includes several exciting developments:

### Short-term Goals

- **Feature Parity**: We will continue to implement the missing features listed above to ensure seamless migration.
- **Multi-tenancy**: We will enable multi-tenancy to support our cloud offering, allowing new users to directly access the new login experience while existing customers can migrate at their own pace.

### Long-term Vision

- **Self-Service Components**: We plan to introduce self-service components for the users like profile management, making it easier for you to integrate these functionalities into your applications without relying on our full-fledged management console.
- **Enhanced Customization**: We will explore options to further customize the appearance of the login page, allowing you to tailor it to your specific branding and design preferences.

By focusing on these areas, we aim to provide a powerful, flexible, and customizable login solution that empowers your applications.

Now it’s your turn. Do you have any suggestions for [improvement](https://github.com/zitadel/typescript/issues/new?template=improvement.yaml) or [bug reports](https://github.com/zitadel/typescript/issues/new?template=bug.yaml)? Explore the [repository](https://github.com/zitadel/typescript) and share your feedback in our [discord thread](https://discord.com/channels/927474939156643850/1329100936127320175/threads/1329827099606782093).


We've developed a new TypeScript-based login system to streamline the authentication process for our customers.

Introducing our New TypeScript Login

All posts/ #custom login

How to self-host the Zitadel typescript login UI?

Designing a Login Flow That Fits with Zitadel

Introducing our New TypeScript Login

Why

Explore

Company