Skip to main content

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 seperated 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 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​

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

User Loginname must contain orgdomain​

If this behaviour 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 logonames 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 logonname 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 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.

Verify your domain name​

info

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

  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

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 Behaviour 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. When the number is exceeded, the user gets locked out and has to be unlocked.
  • 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 behaviour of the login page, applyling custom design, is then defined on your projects detail page. Read more about it here

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.