Skip to main content

Login users into your application with a hosted or custom login UI

ZITADEL is a comprehensive identity and access management platform designed to streamline user authentication, authorization, and management processes for your application. It offers a range of features, including single sign-on (SSO), multi-factor authentication (MFA), and centralized user management.

With ZITADEL, you can securely authenticate users using industry-standard protocols such as OpenID Connect and SAML. This enables seamless integration with various applications and services, providing a unified authentication experience for your users.

Besides federated authentication with OpenID Connect and SAML, ZITADEL offers an API to authenticate users allowing you to create your own login process and user interface.

In this guide, we will walk through the different protocols, features and concepts that can be used to login users securely into your applications.

Screenshot of ZITADEL login screen

Using industry-standard protocols​

Authenticate users with OpenID Connect 1.0​

OpenID Connect (OIDC) offers a modern and lightweight authentication protocol built on top of OAuth 2.0, providing flexible authentication flows and easy integration with web and mobile applications. ZITADEL offers a certified compliant implementation of the OpenID Connect Standard, ensuring compliance with proven security best practices.

Authenticating users through the OpenID Connect protocol typically requires an application to redirect the user with an Auth Request to the identity provider that contains information such as the requesting application, scopes, and redirect url. The identity provider is not part of the original application, but a standalone service like ZITADEL that may run under the same domain The user will authenticate using their credentials. After successful authentication, the user will be redirected back to the original application.

Authenticate users with SAML​

SAML (Security Assertion Markup Language) is a widely adopted standard for exchanging authentication and authorization data between identity providers and service providers.

Authentication with SAML (Security Assertion Markup Language) involves a series of exchanges between a service provider (SP), an identity provider (IdP), and the user. Here's an overview of how the process typically works:

  1. User Attempts to Access a Service: The user tries to access a service or application that requires authentication, such as logging into a web application.

  2. Service Provider Redirects to Identity Provider: The service provider (SP) detects that the user needs to be authenticated and redirects the user's browser to the designated identity provider (IdP) for authentication. This redirection often occurs via a SAML request, which includes information about the service provider and a request for authentication.

  3. User Authenticates with Identity Provider: The user is presented with the identity provider's login page, where they enter their credentials (username and password). Alternatively, depending on the IdP's configuration, the user might be authenticated using single sign-on (SSO) mechanisms such as a pre-existing session or multi-factor authentication.

  4. Identity Provider Generates SAML Assertion: Upon successful authentication, the identity provider creates a SAML assertion containing information about the user, such as their identity and attributes. This assertion is digitally signed by the identity provider to ensure its integrity and authenticity.

  5. SAML Assertion Sent to Service Provider: The identity provider sends the SAML assertion back to the user's browser as a response to the original SAML request. The browser then forwards the assertion to the service provider.

  6. Service Provider Validates SAML Assertion: The service provider receives the SAML assertion and validates it to ensure its integrity and authenticity. This typically involves verifying the digital signature of the assertion and checking that it originated from a trusted identity provider.

  7. User Granted Access: If the SAML assertion is successfully validated, the service provider considers the user authenticated and grants them access to the requested service or application. The user can now interact with the service without needing to reauthenticate until their session expires or they log out.

Overall, authentication with SAML provides a secure and standardized method for enabling single sign-on (SSO) and federated identity management across different applications and systems. It allows users to access multiple services with a single set of credentials, streamlining the authentication process while maintaining strong security measures.

Note that SAML might not be suitable for mobile applications. In case you want to integrate a mobile application, use OpenID Connect or our Session API.

There are more differences between SAML and OIDC that you might want to consider.

ZITADEL's Session API​

ZITADEL's Session API provides developers with a straightforward method to manage user sessions within their applications. The Session API is not an industry-standard and can be used instead of OpenID Connect or SAML to authenticate users by building your own custom login user interface.

Tokens in the Session API​

The session API will return a session token that can be used to authenticate users from your application. This token should not be confused with am access or id tokens in opaque or JWT form that is issued during OpenID connect flows.

Token exchange

Token exchange between Session API and OIDC / SAML tokens is not possible at this moment.

Key features of the Session API​

These are some key features of the API:

  1. Session Management: The Session API allows you to create, retrieve, update, and delete sessions for users within your application. Sessions represent a user's active login session, providing temporary access to your application's resources.

  2. Creating Sessions: With the Session API, you can initiate a new session for a user after they successfully authenticate through ZITADEL. This typically involves generating a session token or ID, which is then associated with the user's identity and used to track their session activity.

  3. Retrieving Sessions: You can retrieve information about existing sessions using the Session API, such as session ID, user ID, creation time, and expiration time. This allows you to monitor active user sessions and retrieve session details as needed for auditing or troubleshooting purposes.

  4. Updating Sessions: The Session API enables you to update session attributes or extend session lifetimes based on specific application requirements. Each authentication step, such as username / password check or multi-factor verification, will result in an update session. Also you might want to refresh a session token periodically to prevent it from expiring prematurely or update session metadata to reflect changes in user permissions or settings.

  5. Deleting Sessions: When a user logs out or their session expires, you can use the Session API to delete the corresponding session from your application's records. This helps maintain data integrity and security by ensuring that inactive sessions are properly removed from the system.

Overall, ZITADEL's Session API simplifies session management within your application, providing a convenient and secure way to track user sessions, enforce session policies, and maintain a seamless user experience. By integrating the Session API into your application, you can effectively manage user authentication and access control while ensuring data privacy and security.

Use the Hosted Login to sign-in users​

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.

Build a custom Login UI to authenticate users​

In certain cases, you want to build your own login UI to optimize your user experience. We have dedicated guides on how to build your custom login UI with ZITADEL.

When building your own login UI, you will leverage the Session API to authenticate users and manage user sessions.

Session API support for OIDC and SAML

At the moment developers can only integrate with ZITADEL's Session API and not with standard compliant OpenID Connect or SAML flows.

When to build your custom Login UI​

Main reasons why developers might want to build their own login UI include:

  1. Embedding Login in your application: From a security standpoint you should follow the best practice recommendation to open a browser and then redirect to your application. For certain applications, such as games or mobile apps, you might want to embed the login for a better user experience
  2. Customize business process: You might want to change existing flows that are provided by the hosted login to fit your business process. Make sure to validate that your customization can't be handled by Actions instead.
  3. Customize branding: We designed the hosted login with security in mind, which limits the customization capabilities. Besides that we might not be able to handle all requirements for custom branding. If you believe your customization should be part of the hosted login instead, please open an improvement idea.
  4. Independence of standards You don't want or need to rely on industry standards for authentication such as OpenID Connect or SAML for authenticating users.

Further reference​