mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-03 12:52:16 +00:00
3c3bce1a6b
* WIP: docs(proxy): describe proxy settings * fix nginx * refactor (docs): deploy and operate sections * chore: ignore package-lock since we use yarn * chore: update to rc1 * chore: broken links * chore: update yarn * docs: move disclaimer to bottom * chore: fix broken links * Update docs/docs/guides/operate/tls_modes.mdx Co-authored-by: Fabi <[email protected]> * test caddy files * syntax highlight * traefik example * refactor: docs * refactor * working state * got a working state * remove bar * mark rate limits for update * remove zitadel.ch * fix cases * docs: zitadel quickstart * docs: zitadel quickstart * docs: create app and project * docs: move customer portal docs to guides manage cloud * docs: move customer portal docs to guides manage cloud * docs: move customer portal docs to guides manage cloud * docs: add help me choose in the quickstart * docs: broken links * fix broken links * Update knative guide * styling * docs: support customer portal * update to main instead v2-alpha * use version 2 tag * docs: images * docs: move authentication and authorization guides to integrate * docs: quickstart use examples * docs: lb example * fix broken link * docs: update userinfo endpoints * docs: update userinfo endpoints * fix oidc endpoint * docs: remove unused endpoints in app.module Co-authored-by: Fabi <[email protected]> Co-authored-by: Fabienne <[email protected]> Co-authored-by: Livio Amstutz <[email protected]>
60 lines
4.1 KiB
Plaintext
60 lines
4.1 KiB
Plaintext
---
|
||
title: Organizations
|
||
---
|
||
|
||
## What is an organization?
|
||
|
||
import OrgDescription from '../../../concepts/structure/_org_description.mdx';
|
||
import Column from '../../../../src/components/column';
|
||
|
||
<OrgDescription name="OrgDescription" />
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
## 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 [email protected].
|
||
|
||
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 [email protected] in addition to the already generated [email protected]. 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.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 ord domains" settings in the [Domain Policy](../../../concepts/structure/policies) 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 [email protected], 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
|
||
|
||
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**
|
||
|
||
|
||
|
||
> **_Please note:_** Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time
|
||
|
||
<!-- //TODO Add whats next again -->
|