Skip to main content

Organizations

DescriptionLearn how ZITADEL is structured around Organizations and how to create your organization and verify a domain to use with that new organization.
Learning OutcomesIn this module you will:
  • Learn about organizations
  • Create a new organization
  • Verify your domain name
PrerequisitesExisting instance

What is an organization?

ZITADEL is organized around the idea that:

  • Multiple organizations can be managed within one instance.
  • organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management)
  • organizations are vessels for users and projects

Overview ZITADEL Organizations

Organizations in ZITADEL are therefore comparable to tenants of a system or organizational units of a directory based system.

You can use projects within your organization to manage the security context of closely related components, such as roles, grants and authorizations for multiple clients. You can set up multiple projects within your organization.

ZITADEL allows you to give other organizations permission to manage certain aspects of a project within your organization on their own. This means you could set up a project with roles that should exist within your service/software, but allow another organization to allocate the roles to users within their own organization. As a service provider, you will find this feature useful, as it allows you to establish a self-service culture for your business customers.

Organization Grant

Each organization has its own pool of usernames, which includes human and service users, for its domain ({username}@{domainname}.{zitadeldomain}). A username is unique within your organization. You can configure ZITADEL to use your own domain, and simplify user experience ({loginname}@{yourdomain.tld}).

There are several more modules in our documentation to go into more detail regarding organization management, projects, clients, and users. But first let’s create a new organization and verify your domain name.

Exercise - Create a new organization

To create a new organization login to your ZITADEL instance ({your-domain}-{random string}.zitadel.cloud or your custom domain). Click the organization drop down in the name in the upper left corner in the header, and then select “New organization”. You can either create a new organization with yourself as the organization manger or directly add another account.

Select Organization

If you want to enable you customers to create their organization by themself, we provide a creation form for a organization. <https://{your-domain}-{random string}.zitadel.cloud/ui/login/register/org> The customer needs to fill in the form with the organization name and the contact details.

Register new Organization

How ZITADEL handles usernames

As we mentioned before, each organization has its own pool of usernames, which includes human and service.

This means that, for example a user with the username road.runner, can only exist once in an organization called ACME. ZITADEL will automatically generate a "logonname" for each consisting of {username}@{domainname}.{zitadeldomain}, in our example road.runner@acme.zitadel.ch.

When you verify your domain name, then ZITADEL will generate additional logonames for each user with the verified domain. If our example organization would own the domain acme.ch and verify within the organization ACME, then the resulting logonname in our example would be road.runner@acme.ch in addition to the already generated road.runner@acme.zitadel.ch. The user can now use either logonname to authenticate with your application.

Domain verification and primary domain

Once you have successfully registered your organization, ZITADEL will automatically generate a domain name for your organization (eg, acme.zitadel.ch). Users that you create within your organization will be suffixed with this domain name.

You can improve the user experience, by suffixing users with a domain name that is in your control. If the "validate ord domains" settings in the Domain Policy is set to true, you have to prove the ownership of your domain, by DNS or HTTP challenge. If the settings is set to false, the created domain will automatically be set to verifed.

An organization can have multiple domain names, but only one domain can be primary. The primary domain defines which login name ZITADEL displays to the user, and what information gets asserted in access_tokens (preferred_username).

Please note that domain verification also removes the logonname from all users, who might have used this combination in the global organization (ie. users not belonging to a specific organization). Relating to our example with acme.ch: If a user ‘coyote’ exists in the global organization with the logonname coyote@acme.ch, then after verification of acme.ch, this logonname will be replaced with coyote@{randomvalue.tld}. ZITADEL will notify users affected by this change.

Exercise - Verify your domain name

  1. Browse to your organization
  2. Click Add Domain
  3. To start the domain verification click the domain name and a dialog will appear, where you can choose between DNS or HTTP challenge methods.
  4. For example, create a TXT record with your DNS provider for the used domain and click verify. ZITADEL will then proceed and check your DNS.
  5. When the verification is successful you have the option to activate the domain by clicking Set as primary

Verify Domain

Please note: Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time

Knowledge Check

  • Users exist only within projects or clients
    • yes
    • no
  • User can only login with {username}@{domainname}.{zitadeldomain}
    • yes
    • no
  • You can delegate access management self-service to another organization
    • yes
    • no
Solutions
  • Users exist only within projects or clients
    • yes
    • no (users exist within organizations)
  • User can only login with {username}@{domainname}.{zitadeldomain}
    • yes
    • no (You can validate your own domain and login with {loginname}@{yourdomain.tld})
  • You can delegate access management self-service to another organization
    • yes
    • no

Summary

  • Create your organization and a new user by visiting zitadel.ch
  • Organizations are the top-most vessel for your IAM objects, such as users or projects
  • Verify your domain in the Console to improve user experience; remember to not delete the verification code to allow recheck of ownership
  • You can delegate certain aspects of your IAM to other organizations for self-service

Where to go from here:

  • Create a project
  • Setup Passwordless MFA
  • Manage ZITADEL Roles
  • Grant roles to other organizations or users