Overview

All documentations are under active work and subject to change soon!

Features

  • Single-Sign On (SSO) and Single-Log Out (SLO) for
    • Web applications
      • Server Renderer
      • Single Page
    • Native Clients
      • Windows
      • MacOS
      • Linux
    • Mobile Clients
      • Android
      • iOS / iPadOS
  • Bearer Tokens to use with APIs
    • REST
    • GRPC
    • GraphQL
  • Role Based Access Control
  • OpenID Connect 1.0 (OIDC) support
  • OAuth 2.0 support
  • Identity Brokering
    • Federation with OIDC and OAuth 2.0 Identity Providers
    • Social Login
  • Management Console for central management of your data
  • Multi-factor Authentication
    • Support for TOTP/HOTP with any app, like authy, google authenticator, ...
  • User self-registration, recover password, email and phone verification, etc.
  • Organisation self-registration, domain verification, policy management
  • API's for easy integration in your application

Concepts

With ZITADEL there are some key concepts some should be aware of before using it to secure your applications and services. You find these definitions in the "What is..." heading of each resource.

Console

What is Console

Console is the ZITADEL Graphical User Interface.

Users can manage some information by their own.

  • profile information
  • credentials
  • external logins

Users (org owners) who manage organisations do this also with Console.

  • Organisation settings (policies, domains, idp's)
  • Manage users
  • Manage projects, clients and roles
  • Give access to users

For the IAM Administrators there is also a section in Console solely intended to manage the system.

  • Check failed events
  • Reset read models
  • Define system policies

Technologies

Console is built with Angular and interfaces with ZITADEL by utilizing the GRPC APIs over GRPC-web.

Organisations

What are organisations

Organisations are comparable to tenants of a system or OU's (organisational units) if we speak of a directory based system. ZITADEL is organised around the idea that multiple organisations share the same System and that they can grant each other rights so self manage certain things.

Global organisation

ZITADEL provides a global organisation for users who manage their accounts on their own. Think of this like the difference between a "Microsoft Live Login" vs. "AzureAD User" or if you think of Google "Gmail" vs "Gsuite".

Create an organisation without existing login

ZITADEL allows you to create a new organisation without a pre-existing user. For ZITADEL.ch you can create a org by visiting the Register organisation

Screenshot here

For dedicated ZITADEL instances this URL might be different, but in most cases should be something like https://accounts.YOURDOMAIN.TLD/register/org

Create an organisation with existing login

You can simply create a new organisation by visiting the ZITADEL Console and clicking "new organisation" in the upper left corner.

Screenshot here

For dedicated ZITADEL instances this URL might be different, but in most cases should be something like https://console.YOURDOMAIN.TLD

Verify a domain name

Once you created your organisation you will receive a generated domain name from ZITADEL for your organisation. For example if you call your organisation ACME you will receive acme.zitadel.ch as name. Furthermore the users you create will be suffixed with this domain name. To improve the user experience you can verify a domain name which you control. If you control acme.ch you can verify the ownership by DNS or HTTP challenge. After the domain is verified your users can use both domain names to log-in. The user "coyote" can now use "[email protected]" and "[email protected]". An organisation can have multiple domain names, but only one of it can be primary. The primary domain defines which login name ZITADEL displays to the user, and also what information gets asserted in access_tokens (preferred_username).

Screenshot here

Audit organisation changes

All changes to the organisation are displayed on the organisation menu within ZITADEL Console organisation menu. Located on the right hand side under "activity".

Screenshot here

Projects

What are projects

The idea of projects is to have a vessel for all components who are closely related to each other. In ZITADEL all clients located in the same project share their roles, grants and authorizations. From a access management perspective you manage who has what role in the project and your application consume this information. A project belongs to exactly one organisation. The attribute project role assertion defines, if the roles should be integrated in the tokens without sending corresponding scope (urn:zitadel:iam:org:project:role:{rolename}) With the project role check you can define if a user should have a requested role to be able to logon.

Clients

Clients are described here What are clients Basically these are you applications who initiate the authorization flow.

Roles

Roles (or Project Roles) is a mean of managing users access rights for a certain project. These roles are opaque for ZITADEL and have no weight in relation to each other. So if a user has two roles, admin and user in a certain project, the information will be treated additive.

Grants

With ZITADEL it is possible to give third parties (other organisations) the possibility to manage certain roles on their own. To achieve this the owner of a project can grant (some could say delegate) certain roles or all roles to a organisation. After granting that organisation it can manage on its own which user has what roles. This feature is especially useful for service providers, because they are able to establish a great self-service culture for their business customers.

Authorizations

Project vs. granted Project

The simple difference of a project vs a granted project is that a project belongs to your organisation and the granted project belongs to a third party who did grant you some rights to manage certain roles of their project. To make it more easily to differentiate ZITADEL Console displays these both as separate menu in the project section.

Manage a project

Screenshot here

RBAC Settings

  • Authorisation Check option (Check if the user at least has one role granted)
  • Enable Project_Role Assertion (if this is enabled assert project_roles, with the config of the corresponding client)

Define project specific roles

Screenshot here

Grant project to a third party

Screenshot here

Audit project changes

Screenshot here

Clients

What are clients

Clients are applications who share the same security context and interface with an "authorization server". For example you could have a software project existing out of a web app and a mobile app, both of these application might consume the same roles because the end user might use both of them.

Manage clients

Clients might use different protocols for integrating with an IAM. With ZITADEL it is possible to use OpenID Connect 1.0 / OAuth 2.0. In the future SAML 2.0 support is planned as well.

Screenshot here

Configure OpenID Connect 1.0 Client

To make configuration of a client easy we provide a wizard which generates a specification conferment setup. The wizard can be skipped for people who are needing special settings. For use cases where your configuration is not compliant we provide you a "dev mode" which disables conformance checks.

Screenshot here

Roles

What are Roles

With roles ZITADEL lets projects define there role based access controle.

Roles can be consumed by the clients which exist witing a specific project.

For more information about how roles can be consumed have a look the the protocol specific information.

Manage Roles

Each role consist of three fields.

Field Description Example
Key This is the Roles actual name which can be used to verify the users roles. User
Display Name A descriptive text for the purpose of the Role User is the default role provided to each person
Group The group field allows to group certain roles who belong in the same context User and Admin in the group default

Grantig Roles

To give someone (or somewhat) access to a projects resources and services ZITADEL provides to processes. Roles can be either granted to users org to organisations.

Grant Roles to Organisations

The possibility to grant roles to an organisation is intented as "delegation" so that a org can on their own grant access to users.

For example a service provider could grant the roles user, and manager to an org as soon as they purchases his service. This can be automated by utilising a service user in the service providers business process.

Screenshot here

Grant Roles to Users

By granting roles to users, be it humanes or machines, this user recieves the authorization to access resources from a service.

Screenshot here

Users

What are users

In ZITADEL there are different users. Some belong to dedicated organisations other belong to the global org. Some of them are human users others are machines. Nonetheless we treat them all the same in regard to roles management and audit trail.

Human vs. Service Users

The major difference between humane vs. machine users is the type of credentials who can be used. With machine users there is only a non interactive login process possible. As such we utilize “JWT as Authorization Grant”.

TODO Link to “JWT as Authorization Grant” explanation.

How ZITADEL handles usernames

ZITADEL is built around the concept of organisations. Each organisation has it's own pool of usernames which include human and service users. For example a user with the username alice can only exist once the org. ACME. ZITADEL will automatically generate a "logonname" for each user consisting of {username}@{domainname}.{zitadeldomain}. Without verifying the domain name this would result in the logonname [email protected]. If you use a dedicated ZITADEL replace zitadel.ch with your domain name.

If someone verifies a domain name within the org. ZITADEL will generate additional logonames for each user with that domain. For example if the domain is acme.ch the resulting logonname would be [email protected] and as well the generated one [email protected].

Domain verification also removes the logonname from all users who might have used this combination in the global org. Relating to example with acme.ch if a user in the global org, let's call him bob used [email protected] this logonname will be replaced with [email protected] ZITADEL notifies the user about this change

Manage Users

Create User

Screenshot here

Set Password

Screenshot here

Manage Service Users

Screenshot here

Authorizations

Screenshot here

Audit user changes

Screenshot here

Policies

What are policies

Polices are a means of enforcing certain behavior of ZITADEL. ZITADEL defines a default policy on the system level. However a org. owner can change these aspects within his own org.

Below is a list of available policies

Password complexity

This policy enforces passwords of users within the org. to be compliant.

  • min length
  • has number
  • has symbol
  • has lower case
  • has upper case

Screenshot here

IAM Access Preference

This policy enforces, when set to true, that usernames are suffixed with the organisations domain. Under normal operation this policy is only false on the global org. so that users can choose there email as username. Only available for the IAM Administrator

Screenshot here

Login Options

With this policy it is possible to define what options a user sees in the login process.

  • Username Password allowed
  • Self Register allowed
  • External IDP allowed
  • List of allowed external IDPs

Screenshot here

Audit policy changes

Screenshot here

Upcoming Policies

  • Password age
  • Password failure count

Identity Providers

What are Identity Providers

Identity providers or in short idp's are external systems to which ZITADEL can create a federation or use their directory service. Normally federation uses protocols like OpenID Connect 1.0, OAuth 2.0 and SAML 2.0.

Some examples include:

Social Providers

  • Google Account
  • Microsoft Live Account
  • Apple ID
  • GitHub
  • GitLab
  • ...

#### Enterprise Providers**

  • Azure AD Tenant
  • Gsuite hosted domain
  • ...

### Generic

  • ADFS
  • ADDS
  • Keycloak
  • LDAP

What is Identity Brokering

ZITADEL supports the usage as identity broker, by linking multiple external idp's into one user. With identity brokering the client which relies on ZITADEL does not need to care about the linking of identity.

Manage Identity Providers

Screenshot here

Federation Protocols

Currently supported are the following protocols.

  • OpenID Connect 1.0
  • OAuth 2.0

SAML 2.0 will follow later on.

Storage Federation

This is a work in progress.

Storage federation is a means of integrating existing identity storage like LDAP and ADDS. With this process ZITADEL can authenticate users with LDAP Binding and SPNNEGO for ADDS. It is also possible to synchronize the users just-in-time or scheduled.

Sync Settings

Here we will document all the different sync options

  • Readonly
  • Writeback
  • just-in-time sync
  • scheduled sync

TBD

Audit identity provider changes

Screenshot here

Audit

What about Audit

ZITADEL is built upon the concept of Event sourcing. With this ZITADEL can track each operation of all objects it maintains over an infinite amount of time. The only limit is the storage system.

With these events ZITADEL can provide you with a super detailed audit trail where you can see who changed what and when.

Over the next few releases we will steadily enhance and build features tailored to reporting and audit.

It is important to mention that even if ZITADEL does not yet supply the Graphical User Interface for certain audit aspects it still has all the data to generate these reports later on!

System Administration

What is meant by system

System describes the root of ZITADEL and includes all other elements like organisations, users and so on. Most of the time this part is managed by an user with the role IAM_OWNER.

Default Policies

When ZITADEL is setup for the first time we establish certain default polices for the whole system.

TODO Document default policy settings

Manage Read Models

Read Models are a way to normalize data out of the event stream for certain aspects. For example there is a model which consist of logonname and the password hash so that the login process can query that data.

All read models are eventual consistent by nature and sometimes an administrator would like to verify they are still up-to date. In the ZITADEL Console is a section called administration available where the admin can check all read models and there current state. There is even a possibility to regenerate a read model.

When a read model is regenerated it might take up some time to be fully operational again Depending on the model which is regenerated this might have a operational impact for the end-users

Screenshot here

Secret Handling

ZITADEL store secrets always encrypted or hashed in it's storage. Whenever feasible we try to utilize public / private key mechanics to handle secrets.

Encryption We use AES256 as default mechanic for storing secrets.

Password Hashing By default bcrypt is used with a salt of 14.

This mechanic is used for user passwords and client secrets

Signing Keys These keys are randomly generated within ZITADEL and are rotated on a regular basis (e.g all 6h).

Signing keys are stored with AES256 encryption

TLS Under normal operations ZITADEL's API nodes are located behind a reverse proxy. So the TLS Key handlings is out of context in this regard. However ZITADEL can use TLS keys at runtime level.

TODO Document TLS config

IAM Configuration

TODO Document ZITADEL config

Audit system changes

Screenshot here