mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-27 09:42:16 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
145 lines
9.3 KiB
Plaintext
145 lines
9.3 KiB
Plaintext
---
|
||
title: ZITADEL Organizations
|
||
sidebar_label: Organizations
|
||
---
|
||
|
||
import OrgDescription from "../../../concepts/structure/_org_description.mdx";
|
||
import Column from "@/components/column";
|
||
|
||
## 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.
|
||
|
||
<img
|
||
width="400px"
|
||
src="/docs/img/console_org_select.png"
|
||
alt="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.
|
||
|
||
<img
|
||
width="400px"
|
||
src="/docs/img/console_org_register.png"
|
||
alt="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](./default-settings#domain-settings).
|
||
|
||
Those loginnames consist of the format `{username}@{domainname}.${CUSTOM_DOMAIN}`.
|
||
If your user had the username `john.doe`, the generated loginname would be `[email protected]`.
|
||
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 `[email protected]` in addition to the already generated `[email protected]`.
|
||
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](./default-settings#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 verified.
|
||
|
||
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 [email protected], 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
|
||
|
||
<Callout>
|
||
You can also disable domain verification with DNS challenge in the [default settings](/guides/manage/console/default-settings#domain-settings).
|
||
</Callout>
|
||
|
||
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.
|
||
|
||
<img
|
||
width="400px"
|
||
src="/docs/img/console_verify_domain.png"
|
||
alt="Select Organization"
|
||
/>
|
||
|
||
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. Here are some useful links explaining how you can add TXT records for popular domain providers:
|
||
|
||
- [Cloudflare](https://www.zoho.com/mail/help/adminconsole/cloudflare.html#alink1)
|
||
- [Squarespace](https://support.squarespace.com/hc/en-us/articles/205812388-Domain-verification-with-a-TXT-Record-alternative-method-)
|
||
- [Name.com](https://www.name.com/support/articles/115004972547-adding-a-txt-record)
|
||
- [EasyDNS](https://kb.easydns.com/knowledge/how-to-make-a-dns-entry/)
|
||
- [DNS Made Easy](https://support.dnsmadeeasy.com/support/solutions/articles/47001001376-create-a-txt-record)
|
||
|
||
5. When the verification is successful you have the option to activate the domain by clicking **Set as primary**
|
||
|
||
<Callout type="warn">
|
||
Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time
|
||
</Callout>
|
||
|
||
## Organization Settings
|
||
|
||
In organizations you also have settings that have higher priority than on your default settings, and therefore override them.
|
||
Those settings are the same as your default settings.
|
||
|
||
> Note: that the following links, redirect to default settings to omit redundancy.
|
||
|
||
- [**Domain settings**](./default-settings#domain-settings): Whether users use their email or the generated username to login. Other Validation, SMTP settings
|
||
- [**Branding**](./default-settings#branding): Appearance of the login interface.
|
||
- [**Notification settings**](./default-settings#notification-settings): Setup Notification and Email Server settings for initialization-, verification- and other mails. Setup Twilio as SMS notification provider.
|
||
- [**Login Behavior and Access**](./default-settings#login-behavior-and-access): Multifactor Authentication Options and Enforcement, Define whether passkeys are allowed or not, Set Login Lifetimes and advanced behavior for the login interface.
|
||
- [**Identity Providers**](./default-settings#identity-providers): Define IDPs which are available for all organizations
|
||
- [**Password Complexity**](./default-settings#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more.
|
||
- [**Lockout**](./default-settings#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**](/guides/manage/console/organizations-overview#usernames-and-domains): This is where you manage your organization specific domains which can be used to build usernames
|
||
- [**Message Texts**](./default-settings#message-texts): Text and internationalization for emails
|
||
- [**Login Interface Texts**](./default-settings#login-interface-texts): Text and internationalization for the login interface
|
||
- [**External Links**](./default-settings#external-links): Links to your own Terms of Service and Privacy Policy regulations, Help Page, Support email, documentation link...
|
||
|
||
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](./projects#branding)
|
||
|
||
## Show Organization Login
|
||
|
||
As you should know by now ZITADEL knows the concept of Organizations.
|
||
You can define [default settings](/guides/manage/console/default-settings) for your ZITADEL, or you can overwrite them for an [Organization](#organization-settings).
|
||
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.
|
||
|
||
```bash
|
||
urn:zitadel:iam:org:id:{id}
|
||
```
|
||
|
||
Read more about the [scopes](/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Playground](https://zitadel.com/playgrounds/oidc).
|
||
|
||
## Default organization
|
||
|
||
On the Default settings page (`${CUSTOM_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](/guides/solution-scenarios/domain-discovery)), then all users are allowed to login and users can self-register to this default organization.
|