Skip to main content

Login users into your application with a hosted login UI

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.

Centralized authentication endpoint​

ZITADEL's hosted login page acts as a centralized authentication endpoint where users are redirected to authenticate themselves. When users attempt to access a protected resource within your application, you can redirect them to the hosted login page to authenticate using their login methods and credentials or through Single-sign-on (SSO). After successful authentication, the user will be redirected back to the originating application.

Security and compliance​

ZITADEL's hosted login page prioritizes security and compliance with industry standards and regulations. It employs best practices for securing authentication processes, such as encryption, token-based authentication, and adherence to protocols like OAuth 2.0, OpenID Connect, and SAML.

We make sure to harden the login UI and minimize the attack surface. One of the measures we apply is setting the necessary security heads thus minimizing the risk of common vulnerabilities in login pages, such as XSS vulnerabilities. Put your current login to the test and compare the results with our hosted login page. Tools like Mozilla's Observatory can give you a good first impression about the security posture.

Developer-friendly integration​

Integrating the hosted login page into your application is straightforward, thanks to ZITADEL's developer-friendly documentation, SDKs, and APIs. Developers can easily implement authentication flows, handle authentication callbacks, and customize the user experience to seamlessly integrate authentication with their application's workflow.

Overall, ZITADEL's hosted login page simplifies the authentication process for developers by providing a secure, customizable, and developer-friendly authentication interface. By leveraging this centralized authentication endpoint, developers can enhance their application's security, user experience, and compliance with industry standards and regulations.

Key features of the hosted login​

Flexible usernames​

Different login name formats can be used on ZITADEL's hosted login page to select a user. Login methods can be a user's username, containing the username and an organization domain, their email addresses, or their phone numbers. By default, all of these login methods are allowed and can be adjusted by Managers to meet their requirements.

Support for multiple authentication methods​

The hosted login page supports various authentication methods, including traditional username/password authentication, social login options, multi-factor authentication (MFA), and passwordless authentication methods like passkeys. The second factor (2FA) and multi-factor authentication methods (MFA) available in ZITADEL include OTP via an authenticator app, TOTP via SMS, OTP via email, and U2F.

Developers can configure the authentication methods offered on the login page based on their application's security and usability requirements.

Enterprise single-sign-on​

Screenshot of ZITADEL console showing different identity provider templates

With the hosted login page from ZITADEL developers will get the best support for multi-tenancy single-sign-on with third-party identity providers. ZITADEL acts as an identity broker between your applications and different external identity providers, reducing the implementation effort for developers. External Identity providers can be configured for the whole instance or for each organization that represents a group of users such as a B2B customer or organizational unit.

ZITADEL offers various identity provider templates to integrate providers such as Okta, Entra ID or on-premise LDAP.

Multi-tenancy authentication​

ZITADEL simplifies multi-tenancy authentication by securely managing authentication for multiple tenants, called Organizations, within a single instance.

Key features include:

  1. Secure Tenant Isolation: Ensures robust security measures to prevent unauthorized access between tenants, maintaining data privacy and compliance. Managers for an organization have only access to data and configuration within their Organization.
  2. Custom Authentication Configurations: Allows tailored authentication settings, branding, and policies for each tenant.
  3. Centralized Management: Provides centralized administration for efficient management across all tenants.
  4. Scalability and Flexibility: Scales seamlessly to accommodate growing organizations of all sizes.
  5. Domain Discovery: Starting on a central login page, route users to their tenant based on their email address or other user attributes. Authentication settings will be applied automatically based on the organization's policies, this includes routing users seamlessly to third party identity providers like Entra ID.

Customization options​

While the hosted login page provides a default authentication interface out-of-the-box, ZITADEL offers customization options to tailor the login page to match your application's branding and user experience requirements. Developers can customize elements such as logos, colors, and messaging to ensure a seamless integration with their application's user interface.

Customization and Branding

The login page can be changed by customizing different branding aspects and you can define a custom domain for the login (eg, login.acme.com).

By default, the displayed branding is defined based on the user's domain. In case you want to show the branding of a specific organization by default, you need to either pass a primary domain scope (urn:zitadel:iam:org:domain:primary:{domainname}) with the authorization request, or define the behavior on your Project's settings.

Fast account switching​

The hosted login page remembers users who have previously authenticated. In case a user has used multiple accounts, for example, a private account and a work account, to authenticate, then all accounts will be shown on the Account Picker. Users can still login with a different user that is not on the list. This allows users to quickly switch between users and provide a better user experience.

info

This behavior can be changed with the authorization request. Please refer to our guide.

Self-service for users​

ZITADEL's hosted login page offers many self-service flows that allow users to set up authentication methods or recover their login information. Developers use the self-service functionalities to reduce manual tasks and improve user experience. Key features include:

Password reset​

Unauthenticated users can request a password reset after providing the loginname during the login flow.

  • User selects reset password
  • An email will be sent to the verified email address
  • User opens a link and has to provide a new password

Prompt users to set up multifactor authentication​

Users are automatically prompted to provide a second factor, when

  • Instance or organization login policy is set
  • Requested by the client
  • A multi-factor is set up for the user

When a multi-factor is required, but not set up, then the user is requested to set up an additional factor.

Disabling multifactor prompt

You can disable the prompt, in case multifactor authentication is not enforced by setting the Multifactor Init Lifetime to 0.

Enroll passkeys​

Users can select a button to initiate passwordless login or use a fall-back method (ie. login with username/password), if available.

The passwordless with passkeys login flow follows the FIDO2 / WebAuthN standard. With the introduction of passkeys the gesture can be provided on ANY of the user's devices. 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)​

We have worked on a new, self-hostable implementation of our hosted login built with Next.js and leveraging our 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.

Current State​

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.

As we continue to develop the TypeScript login system, we will provide regular updates on its progress and new capabilities.

Limitations​

For the first implementation we have excluded the following features:

  • SAML (SP & OP)
  • Generic JWT IDP
  • LDAP IDP
  • Device Authorization Grants
  • Timebased features
    • Lockout Settings
    • Password Expiry Settings
    • Login Settings - Multifactor init prompt
    • Force MFA on external authenticated users
  • Passkey/U2F Setup
    • 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​

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!

Step-by-step Guide​

The simplest way to deploy the new login for yourself is by using the “Deploy” button in our repository to deploy the login directly to your Vercel.

  1. Create a service user (ZITADEL_SERVICE_USER_ID) 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
  3. Deploy login to Vercel: You can do so, be directly clicking the “Deploy” button at the bottom of the readme in our repository
  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
  5. Add the domain where your login UI is hosted to the trusted domains 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
    2. Enable the loginV2 feature 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.

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: $YOUR-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