Onboard B2B customers using organizations

In this guide we will explain how you can create and set up new organizations in ZITADEL to help you with your onboarding flows. Creating a new organization is the best choice for multi-tenancy use cases that require separation of customers, teams, or groups of users.

We will also explain how to leverage Administrators to delegate self-service team management and setting up policies to users of each organization.

When you want to build an onboarding process for your business customers you have to go through the following steps:

1. Create an organization: The organization represents the customer or a team
2. Create the first administrator user: This user is the account for your customer, which should be able to configure settings such as SSO, MFA, etc.
3. Give the user permission to configure settings, create users and assign roles to users in ZITADEL

As soon as you have successfully created the organization and added an administrator, then your customer is able to start managing the organization and users themselves. The first actions they typically want to take are the following:

1. Invite Team member
2. Configure SSO
3. Configure Security Settings
4. Configure Branding

ZITADEL does have multiple possibilities to achieve that process.

Onboard customers through the ZITADEL Management Console

Each ZITADEL instance does automatically bring a management console with it. The console can be used to manage all your resources through a UI. You can access it by calling the following URL: ${CUSTOM-DOMAIN}/ui/ Make sure that your admins have a Administrator role with permissions on an instance level such as "INSTANCE_OWNER"

Create a customer

1. Create a new Organization. Click the dropdown in the header and click "+ New Organization" to be redirected to the create organization screen.

If the setting "Use your personal account as organization owner" is enabled, your user will automatically get the role "ORG_OWNER" in the organization. Give the organization a name and create it.

Click on the newly created organization in the list and you will switch your context to that organization.

Add First Administrator

Create the first user for your customer and ensure the user has enough permissions to self-manage the needed settings.

Create User

import CreateUser from "../../../guides/manage/console/_create-user.mdx";

Add Administrator Role to User

Now you need to assign the right administrator role to your user. In this case we want to give "ORG_OWNER". If you do want to know more about the roles, check out the ZITADEL Administrators Guide with the Role List

Go to the detail page of the organization and select the "+" button in the top right corner, where you already see a list of existing administrators.

import AddAdministrator from "../../manage/console/_add_administrator.mdx";

Invite Team Members

The first user of your customer is now ready to authenticate and manage resources in ZITADEL. The first task will be inviting a team member.

We are now switching to the view of your customer's administrator user.

The Administrator user received an initialization e-mail after the user was created. With the link in the email, the admin will be able to set up a password and optionally some multi-factors.

As the administrator only has permission for its own organization, the ZITADEL Management Console UI does look slightly different.

To invite a team member, the admin has to repeat the steps you did before.

1. Create User
2. Add role "ORG_OWNER" to the user

Setup Single-Sign-On (SSO)

Your next step is to configure SSO so your users can authenticate with an existing user into ZITADEL.

First, go to the Login Behavior and Security Settings. Make sure that the "External IDP allowed" is enabled. This setting does generally allow users to authenticate with an external provider.

1. Go to the Settings Page
2. Navigate to Identity Providers You might already see a list of activated providers here. If so, this is because some default providers are configured on the ZITADEL instances.
3. Set up the identity provider you need. Follow our detailed setup description of the different providers we have: Set up the needed identity provider

Auto-register users with SSO

Let's assume you have configured Entra ID as an identity provider, and you want to allow all your employees to login with the corresponding user without having to register. This does need some specific settings on your provider.

1. Go to the detail page of your configured identity provider (In this example Entra ID)
2. Enable "Automatic creation" in the optional settings. Optionally, if you want to update the user information in ZITADEL, when they have changed in the Entra ID additionally enable "Automatic update"
3. Enable the "Account creation allowed" if it is not already
4. If you also want to allow users to link to an existing account, if they already have an account in ZITADEL, enable "Account linking allowed"

Login with your user

The last step is that your user can log in to ZITADEL and use the SSO account.

import OrgLoginDescription from "./_org_login_description.mdx";

Your user is now ready to log in with SSO.

Automated onboarding for your customers

If you want to start automating the process of onboarding your customers, the following sections give you some guidance.

Built-in register organization form

A basic form that allows a customer to enter an organization name and a user account is hosted on the following URL: {custom-domain}/ui/login/register/org

When a user registers through this form, an organization and a user are created. The user will automatically get the role "ORG_OWNER" withing ZITADEL and is able to manage the whole organization. You can read more about the administrators, roles and their meanings here

Disable built-in register organization form

If you do not want to allow users to register organizations with this form, you can disable it with the following request27: Restrict the instance features

Disabling the form makes sense if your administrators manage new customers themselves or if you build your own form.

Build your own form with setup organization request

If the built-in register form doesn't fulfill your needs, we recommend building your own form.

The administration API of ZITADEL allows you to set up a new organization with a first administrator user. The setup organization requests, has the possibility to specify an organization with its name and a domain. You can directly send a human user with all the necessary information like the profile, email, password. etc. This request allows you only to set up a user with password authentication at the moment. By specifying the roles you can define which permission the user should have within ZITADEL. By default, the user will automatically get "ORG_OWNER".

Example Request

curl -L -X POST 'https://${CUSTOM_DOMAIN}/admin/v1/orgs/_setup' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "org": {
    "name": "Organisation C",
    "domain": "org-c.com"
  },
  "human": {
    "userName": "gigi-giraffe",
    "profile": {
      "firstName": "Gigi",
      "lastName": "Giraffe",
      "nickName": "gigi-giraffe",
      "displayName": "Gigi Giraffe",
      "preferredLanguage": "en",
      "gender": "GENDER_UNSPECIFIED"
    },
    "email": {
      "email": "[email protected]",
      "isEmailVerified": true
    },
    "phone": {
      "phone": "+41 71 000 00 00",
      "isPhoneVerified": true
    },
    "password": "my_53cr3t-P4$$w0rd"
  },
  "roles": [
    "string"
  ]
}'

Detailed description of Setup Organization

If you need to add custom data to either the organization or the user you can use the metadata. Metadata is a key value construct that allows you to store any additional information to the resources. The set organization metadata request allows you to add one key value pair to an organization: Set Organization Metadata If you have more than one field, you can use the bulk add request: Bulk Set Organization Metadata

The same requests also exist on the user resource: Set User Metadata Bulk Set User Metadata