Skip to main content

Log users into your application with different authentication options

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.

If you want to read more about authenticating with OIDC, head over to our comprehensive OpenID Connect Guide.

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. If you want to read more about authenticating with SAML, head over to our comprehensive SAML Guide.

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 for secure user authentication within your applications. This centralized authentication interface simplifies application integration by offering a ready-to-use login experience. For a comprehensive understanding of the hosted login page and its capabilities, please refer to our dedicated guide

The hosted login is particularly well-suited for scenarios where:

  • Minimal branding is required: If your primary focus is on functionality over a highly customized look and feel.
  • Standard authentication flows suffice: Your application doesn't necessitate complex or unique authentication processes.
  • OIDC or SAML are suitable: Your application integrates seamlessly with industry-standard protocols.
  • Time-to-market is critical: You need a rapid and efficient authentication solution to accelerate your development timeline.
  • Embedding the login UI is unnecessary: You prefer a separate, hosted login page for user authentication.

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​