Skip to main content

ZITADEL Organizations

What is an organization?​

An Organization is where your projects and users live. Looking at a B2B use case, an organization represents a business partner who typically has its own branding and has different access settings like additional federated login providers. Users from one organization are separated from others.

Create a new organization​

To create a new organization, click on the organizations dropdown and then select “New organization”. You can either create a new organization with your logged in user as the organization manager or directly create another account. If you choose your logged in user as organization manager, a membership for the new organization will be added to the account.

Select Organization

If you want to enable your customers to create their organization by themselves, we provide a creation form for an organization. <https://$CUSTOM-DOMAIN/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​

If your domain setting "user loginname must contain orgdomain" is disabled, your username will be unique within the whole instance. At the moment the username only allows e-mail formatted input. (This will be changed soon)

User Loginname must contain orgdomain​

If this behavior is not suitable for you, ZITADEL has the option to suffix the usernames with the organization domain. This setting is called User Loginname must contain orgdomain and is part of your Domain settings.

Those loginnames consist of the format {username}@{domainname}.{zitadeldomain}. If your user had the username john.doe, the generated loginname would be john.doe@acme.zitadel.cloud. This also means that only one user with the username john.doe can exist in your organization called ACME.

If you verify your domain name or add additional domains, ZITADEL will generate those additional login names for you. If the organization would own the domain acme.ch and verify it, then the resulting loginname would be john.doe@acme.ch in addition to the already generated john.doe@acme.zitadel.cloud. The user can now use either login name to authenticate with your application.

Note: You can set this setting on your instance as well as your organizations. All available usernames are shown on the top of the user pages.

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.cloud). 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 org domains" settings in the Domain Settings is set to true, you have to prove the ownership of your domain, by DNS or HTTP challenge. If the setting 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 login name 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 login name coyote@acme.ch, then after verification of acme.ch, this login name will be replaced with coyote@{randomvalue.tld}. ZITADEL will notify users affected by this change.

Verify your domain name​

info

You can also disable domain verification with DNS challenge in the instance settings.

  1. Browse to your organization settings
  2. Select the menu entry Verified domains
  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.
Select Organization
  1. 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. Here are some useful links explaining how you can add TXT records for popular domain providers:
  1. When the verification is successful you have the option to activate the domain by clicking Set as primary
caution

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

Organization Settings​

In organizations you also have settings that have higher priority then on your instance, and therefore override its instance. Those settings are the same as on your instance.

Note: that the following links, redirect to instance settings to omit redundancy.

  • Login Behavior and Access: Multifactor Authentication Options and Enforcement, Define whether Passwordless authentication methods are allowed or not, Set Login Lifetimes and advanced behavour for the login interface.
  • Identity Providers: Define IDPs which are available for all organizations
  • Password Complexity: Requirements for Passwords ex. Symbols, Numbers, min length and more.
  • Lockout: Set the maximum attempts a user can try to enter the password or any (T)OTP method. When the number is exceeded, the user gets locked out and has to be unlocked.
  • Verified domains: This is where you manage your organization specific domains which can be used to build usernames
  • Domain settings: Whether users use their email or the generated username to login. Other Validation, SMTP settings
  • Branding: Appearance of the login interface.
  • Message Texts: Text and internationalization for emails
  • Login Interface Texts: Text and internationalization for the login interface
  • Privacy Policy: Links to your own Terms of Service and Privacy Policy regulations. Link to Help Page.

If you need custom branding on a organization (for example in a B2B scenario, where organizations are allowed to use their custom design), navigate back to the home page, choose your organization in the header above, navigate to the organization settings and set the custom design here.

The behavior of the login page, applying custom design, is then defined on your projects detail page. Read more about it here

Show Organization Login​

As you should know by now ZITADEL knows the concept of Organizations. You can define default settings for your ZITADEL, or you can overwrite them for an Organization. Per default the ZITADEL Login will always show what is defined per default. As soon as the Organization context is given, the settings defined on the specific organization can be triggered. This means when you want to trigger the settings of an organization directly, make sure to send the organization scope in the authentication request.

urn:zitadel:iam:org:id:{id}

Read more about the scopes or try it out in our OIDC Playground.

Default organization​

On the instance settings page ($YOUR_DOMAIN//ui/console/orgs) you can set an organization as default organization. Click the "..." on the right hand side of the table and select "Set as default organization".

The current default organization is marked by a label "Default".

When no organization was selected (eg, with the auth request or through Domain Discovery), then all users are allowed to login and users can self-register to this default organization.