diff --git a/docs/docs/apis/openidoauth/endpoints.mdx b/docs/docs/apis/openidoauth/endpoints.mdx index a9db7ffac..59f03ef05 100644 --- a/docs/docs/apis/openidoauth/endpoints.mdx +++ b/docs/docs/apis/openidoauth/endpoints.mdx @@ -569,7 +569,7 @@ curl --request POST \ The endpoint has to be opened in the user agent (browser) to terminate the user sessions. -No parameters are needed apart from the user agent cookie, but you can provide the following to customize the behaviour: +No parameters are needed apart from the user agent cookie, but you can provide the following to customize the behavior: | Parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/docs/examples/secure-api/java-spring.md b/docs/docs/examples/secure-api/java-spring.md index c545f13c2..035d749a0 100644 --- a/docs/docs/examples/secure-api/java-spring.md +++ b/docs/docs/examples/secure-api/java-spring.md @@ -38,7 +38,7 @@ If your starting from scratch, you can use the Spring Initializer with the [foll ### Support class To be able to take the most out of ZITADELs RBAC, we first need to create a CustomAuthorityOpaqueTokenIntrospector, that will -customize the introspection behaviour and map the role claims (`urn:zitadel:iam:org:project:roles`) +customize the introspection behavior and map the role claims (`urn:zitadel:iam:org:project:roles`) into Spring Security `authiorities`, which can be used later on to determine the granted permissions. So in your application, create a `support/zitadel` package and in there the `CustomAuthorityOpaqueTokenIntrospector.java`: diff --git a/docs/docs/guides/integrate/identity-providers/_prefill_action.mdx b/docs/docs/guides/integrate/identity-providers/_prefill_action.mdx index a63a3fcb4..a27e5b035 100644 --- a/docs/docs/guides/integrate/identity-providers/_prefill_action.mdx +++ b/docs/docs/guides/integrate/identity-providers/_prefill_action.mdx @@ -1,4 +1,3 @@ -import CodeBlock from '@theme/CodeBlock';

You can use a ZITADEL action if you want to prefill the fields {props.fields} with {props.provider} data.

diff --git a/docs/docs/guides/integrate/identity-providers/additional-information.mdx b/docs/docs/guides/integrate/identity-providers/additional-information.mdx new file mode 100644 index 000000000..6231a3b89 --- /dev/null +++ b/docs/docs/guides/integrate/identity-providers/additional-information.mdx @@ -0,0 +1,15 @@ +--- +title: Additional Information +sidebar_label: Additional Information +--- + +## Automatically prefill user data + +import PrefillAction from './_prefill_action.mdx'; + + + +This action is an example for OKTA. You can also use it for any other provider +```js reference +https://github.com/zitadel/actions/blob/main/examples/okta_identity_provider.js +``` diff --git a/docs/docs/guides/manage/console/_add_manager.mdx b/docs/docs/guides/manage/console/_add_manager.mdx new file mode 100644 index 000000000..00ac14a6b --- /dev/null +++ b/docs/docs/guides/manage/console/_add_manager.mdx @@ -0,0 +1,6 @@ +When adding a new manager, you can select multiple roles some of which are only allowed to read data. +This can be especially useful if you add service users for one of your projects where you only need read access. + +Per default you will only search for users within the selected organization. If you like to give a role to a user outside the organization you need to switch to the global search and type the exact loginname of the users. This will prevent users from guessing users from other organizations. + +Managers \ No newline at end of file diff --git a/docs/docs/guides/manage/console/_create-user.mdx b/docs/docs/guides/manage/console/_create-user.mdx new file mode 100644 index 000000000..1071690af --- /dev/null +++ b/docs/docs/guides/manage/console/_create-user.mdx @@ -0,0 +1,27 @@ +To create a new user, go to Users and click on **New**. Enter the required contact details and save by clicking “Create”. + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + + + Add Human + + + Add Service User + + + +After a human user is created, by default, an initialization mail with a code is sent to the registered email. This code then has to be verified on first login. +If you want to omit this mail, you can check the **email verified** and **set initial password** toggle. +If no password is set initially, the initialization mail prompting the user to set his password is sent. + +You can prompt the user to add a second factor method too by checking the **Force MFA** toggle in [Login behaviour settings](/docs/guides/manage/console/instance-settings#login-behavior-and-access). + +When logged in, a user can then manage his profile in console himself, adding a profile picture, external IDPs and Passwordless authentication devices. + +Profile Self Manage diff --git a/docs/docs/guides/manage/console/actions.mdx b/docs/docs/guides/manage/console/actions.mdx index 67e16c118..1d72582f5 100644 --- a/docs/docs/guides/manage/console/actions.mdx +++ b/docs/docs/guides/manage/console/actions.mdx @@ -23,4 +23,4 @@ This could for example be a **External Authentication** Flow, with a **Post Auth Flow Now whenever a user gets authenticated externally with an IDP, a action is triggered after the authentication itself. -If you want to know more where actions can be useful, take a look at the feature [here](/concepts/features/actions) or directly jump to an example of a custom behaviour [here](/guides/manage/customize/behavior). +If you want to know more where actions can be useful, take a look at the feature [here](/concepts/features/actions) or directly jump to an example of a custom behavior [here](/guides/manage/customize/behavior). diff --git a/docs/docs/guides/manage/console/instance-settings.mdx b/docs/docs/guides/manage/console/instance-settings.mdx index 68e3e9a96..0d00b9e0e 100644 --- a/docs/docs/guides/manage/console/instance-settings.mdx +++ b/docs/docs/guides/manage/console/instance-settings.mdx @@ -3,7 +3,7 @@ title: ZITADEL Instance Settings sidebar_label: Instance Settings --- -Instance settings work as default or fallback settings for your organizational settings. Most of the time you only have to set instance settings for the cases where you don't need specific behaviour in the organizations themselves or you only have one organization. +Instance settings work as default or fallback settings for your organizational settings. Most of the time you only have to set instance settings for the cases where you don't need specific behavior in the organizations themselves or you only have one organization. To access instance settings, use the instance page at `{instanceDomain}/ui/console/settings` or click at the instance button on the **top-right** of the page and then navigate to settings in the navigation. @@ -17,7 +17,7 @@ When you configure your instance, you can set the following: - **General**: Default Language for the UI - [**Notification settings**](#notification-providers-and-smtp): Notification and Email Server settings, so initialization-, verification- and other mails are sent from your own domain. For SMS, Twilio is supported as notification provider. -- [**Login Behaviour and Access**](#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. +- [**Login Behavior and Access**](#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**](#identity-providers): Define IDPs which are available for all organizations - [**Password Complexity**](#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more. - [**Lockout**](#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. @@ -43,7 +43,7 @@ In the Branding settings, you can upload you Logo for the login interface, set y | Icon | Upload your icon for the light and the dark design. Icons are used for smaller components. For example in console on the top left as the home button. | | Colors | You can set four different colors to design your login page and email. (Background-, Primary-, Warn- and Font Color) | | Font | Upload your custom font | -| Advanced Behaviour | **Hide Loginname suffix**: If enabled, your loginname suffix (Domain) will not be shown in the login page. **Disable Watermark**: If you disable the watermark you will not see the "Powered by ZITADEL" in the login page | +| Advanced Behavior | **Hide Loginname suffix**: If enabled, your loginname suffix (Domain) will not be shown in the login page. **Disable Watermark**: If you disable the watermark you will not see the "Powered by ZITADEL" in the login page | Make sure you click the "Apply configuration" button after you finish your configuration. This will ensure your design is visible for your customers. @@ -86,7 +86,7 @@ No default provider is configured to send some SMS to your users. If you like to Twilio -## Login Behaviour and Access +## Login Behavior and Access The Login Policy defines how the login process should look like and which authentication options a user has to authenticate. diff --git a/docs/docs/guides/manage/console/managers.mdx b/docs/docs/guides/manage/console/managers.mdx index e4b9d09e6..f71bc5698 100644 --- a/docs/docs/guides/manage/console/managers.mdx +++ b/docs/docs/guides/manage/console/managers.mdx @@ -12,12 +12,10 @@ In the right part of the console you can finde **MANAGERS** in the details part. Managers -When adding a new manager, you can select multiple roles some of which are only allowed to read data. -This can be especially useful if you add service users for one of your projects where you only need read access. +import AddManager from "./_add_manager.mdx"; -Per default you will only search for users within the selected organization. If you like to give a role to a user outside the organization you need to switch to the global search and type the exact loginname of the users. This will prevent allowing users to guess users from other organizations. + -Managers ## Roles diff --git a/docs/docs/guides/manage/console/organizations.mdx b/docs/docs/guides/manage/console/organizations.mdx index 0e22bea57..077603844 100644 --- a/docs/docs/guides/manage/console/organizations.mdx +++ b/docs/docs/guides/manage/console/organizations.mdx @@ -39,7 +39,7 @@ At the moment the username only allows e-mail formatted input. (This will be cha ### 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. +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](./instance-settings#domain-settings). Those loginnames consist of the format `{username}@{domainname}.{zitadeldomain}`. @@ -105,7 +105,7 @@ 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**](./instance-settings#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. +- [**Login Behavior and Access**](./instance-settings#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**](./instance-settings#identity-providers): Define IDPs which are available for all organizations - [**Password Complexity**](./instance-settings#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more. - [**Lockout**](./instance-settings#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. @@ -118,7 +118,7 @@ Those settings are the same as on your instance. 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](./projects#branding) +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 diff --git a/docs/docs/guides/manage/console/projects.mdx b/docs/docs/guides/manage/console/projects.mdx index 75a11da65..c46d907f9 100644 --- a/docs/docs/guides/manage/console/projects.mdx +++ b/docs/docs/guides/manage/console/projects.mdx @@ -64,7 +64,7 @@ Organizations can then create authorizations for their users on their own. The p ### Branding -If you have different designs for your organizations or probably and use project grants, you can define the login behaviour on the project detail page. +If you have different designs for your organizations or probably and use project grants, you can define the login behavior on the project detail page. - - Add Human - - - Add Service User - - - -After a human user is created, by default, an initialization mail with a code is sent to the registered email. This code then has to be verified on first login. -If you want to omit this mail, you can check the **email verified** and **set initial password** toggle. -If no password is set initially, the initialization mail prompting the user to set his password is sent. - -You can prompt the user to add a second factor method too by checking the **Force MFA** toggle in [Login behaviour settings](./instance-settings#login-behaviour-and-access). - -When logged in, a user can then manage his profile in console himself, adding a profile picture, external IDPs and Passwordless authentication devices. - -Profile Self Manage + ## Metadata diff --git a/docs/docs/guides/solution-scenarios/b2b.mdx b/docs/docs/guides/solution-scenarios/b2b.mdx index 5499e7d17..8ba4f0631 100644 --- a/docs/docs/guides/solution-scenarios/b2b.mdx +++ b/docs/docs/guides/solution-scenarios/b2b.mdx @@ -43,7 +43,7 @@ In order to define the need of the **Portal Application** some planning consider You can decide whether a organization is preselected for the login or if the user is redirected to the default login screen. You can send the user to a specific organization by defining the organization in a custom scope. (primary domain) Settings to the branding or the login options of the organization can be made from the organization section in [Console](https://{your_domain}.zitadel.cloud/ui/console/org). -The behaviour of the login branding can be set in your projects detail page. You can choose the branding of the selected organization, the user resource owner, or the projects resource owner. +The behavior of the login branding can be set in your projects detail page. You can choose the branding of the selected organization, the user resource owner, or the projects resource owner. ### Organizations diff --git a/docs/docs/guides/solution-scenarios/configurations.mdx b/docs/docs/guides/solution-scenarios/configurations.mdx index e13cc6cd3..e80c2bf6a 100644 --- a/docs/docs/guides/solution-scenarios/configurations.mdx +++ b/docs/docs/guides/solution-scenarios/configurations.mdx @@ -41,7 +41,7 @@ Read more about [applications](../manage/console/applications) and the [redirect It is possible to trigger the organization directly with the authorization request to ZITADEL. This will have the following impacts: -- Trigger organization login behaviour settings +- Trigger organization login behavior settings - Trigger organization branding - Only allow users from selected organization to login @@ -70,7 +70,7 @@ You can either set this attribute on your whole ZITADEL instance or just on some No matter how the username of your user does look like. You can additionally allow login with the email attribute of the user. -You can find this in the "Login Behaviour and Security" Setting of your instance or organizations. +You can find this in the "Login Behavior and Security" Setting of your instance or organizations. Go to the "Advanced" section, per default login with email address should be allowed. It is possible to disable it. ![Login Policy Advanced Setting: Disable email for login](/img/guides/scenarios/login_policy_advanced.png) diff --git a/docs/docs/guides/solution-scenarios/domain-discovery.mdx b/docs/docs/guides/solution-scenarios/domain-discovery.mdx index 439a7cd8a..f44e6a71f 100644 --- a/docs/docs/guides/solution-scenarios/domain-discovery.mdx +++ b/docs/docs/guides/solution-scenarios/domain-discovery.mdx @@ -28,7 +28,7 @@ Follow this guide to configure your ZITADEL instance for this scenario. You will use the instance default settings for the login for the organization **CIAM**. When opening `login.mycompany.com` then the login policy of the instance will be applied. -This means that you have to configure the [Login and Access](/docs/guides/manage/console/instance-settings#login-behaviour-and-access) Policy and [Identity Providers](/docs/guides/manage/console/instance-settings#identity-providers) for the **CIAM** users on the instance itself. +This means that you have to configure the [Login and Access](/docs/guides/manage/console/instance-settings#login-behavior-and-access) Policy and [Identity Providers](/docs/guides/manage/console/instance-settings#identity-providers) for the **CIAM** users on the instance itself. :::info You can also configure these settings on the default organization (see below) and send the scope `urn:zitadel:iam:org:id:{id}` with every [auth request](/docs/apis/openidoauth/authrequest#organization-policies-and-branding). @@ -43,7 +43,7 @@ The default organization will hold all unmatched users, ie. all users that are n ### Enable Domain Discovery -In the [Login Behavior and Security Settings](/docs/guides/manage/console/instance-settings#login-behaviour-and-access) enable "Domain discovery allowed" +In the [Login Behavior and Security Settings](/docs/guides/manage/console/instance-settings#login-behavior-and-access) enable "Domain discovery allowed" ### Configure login with email diff --git a/docs/docs/guides/solution-scenarios/onboarding/_org_login_description.mdx b/docs/docs/guides/solution-scenarios/onboarding/_org_login_description.mdx new file mode 100644 index 000000000..4cc17b510 --- /dev/null +++ b/docs/docs/guides/solution-scenarios/onboarding/_org_login_description.mdx @@ -0,0 +1,17 @@ +Per default the login ui of the default organization is shown. +To allow users of a specific organization to register with their IDP (e.g Azure AD) you have two options. + +1. Identify organization with organization scope + +By sending the organization scope in the authorization request to ZITADEL the specified organization will directly be triggered. +The configured settings of that organization such as IDPs will directly be shown. +If only one IDP is configured and local accounts are disabled the user will directly be redirected to the external provider. +``` +urn:zitadel:iam:org:id:{id} +``` + +2. Domain Discovery + +When domain discovery is enabled, ZITADEL is able to identify the entered domain of a user and match it to a specific organization. +If you want to know more about domain discovery and how to set it up please read the following guide: +[Domain Discovery in ZITADEL](/docs/guides/solution-scenarios/domain-discovery) diff --git a/docs/docs/guides/solution-scenarios/onboarding/b2b.mdx b/docs/docs/guides/solution-scenarios/onboarding/b2b.mdx new file mode 100644 index 000000000..0a3eadd6e --- /dev/null +++ b/docs/docs/guides/solution-scenarios/onboarding/b2b.mdx @@ -0,0 +1,213 @@ +--- +title: Onboarding B2B Customer +sidebar_label: Onboard B2B customer +--- + +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](/docs/guides/manage/console/overview) 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 [Manager role](/docs/guides/manage/console/managers) with permissions on an instance level such as "INSTANCE_OWNER" + +### Create a customer + +You do have two different options to create a new Organization. +1. If you are on a specific organization, click the dropdown in the header and press click "+ New Organization" + +Create Organization Dropdown + +2. If you are on the instance level, go to the Organization tab and click the "+ New" button above the Organization list. + +Organization List - Add new Organization + +No matter which option you choose you will 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. + +Create Organization + +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 configuration. + +#### Create User + +import CreateUser from '/docs/guides/manage/console/_create-user.mdx'; + + + +#### Add Manager Role to User + +Now you need to give the right manager 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 Managers Guide with the Role List](/docs/guides/manage/console/managers) + +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 managers. +Managers + +import AddManager from "/docs/guides/manage/console/_add_manager.mdx"; + + + +### Invite Team Members + +The first user of your customer is now ready to authenticate and manage resources in ZITADEL. +First task will be inviting a team member. + +We are now switching to the view of your customer's administrator user. + +:::note +The following actions can also be configured by an Instance Administrator for their customer. +To show how you can use the self-management possibilities it is shown from the customer's administrator. +::: + +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 setup a password and optionally some multi-factors. + +As the administrator only has permission for its own organization the ZITADEL Console UI does look slightly different. + +To invite a team member the admin has to repeat the steps you did before. +1. [Create User](./b2b#create-user) +2. [Add role "ORG_OWNER" to the user](./b2b#create-user#add-administrator-role-to-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 see already a list of activated providers here. If so, this is because some default providers are configured on the ZITADEL instances. +3. Configure the identity provider you need. + Follow our detailed configuration description of the different providers we have: [Configure the needed identity provider](/docs/guides/integrate/identity-providers) + +#### Auto-register users with SSO + +Let's assume you have configured AzureAD 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 configuration on your provider. + +1. Go to the detail page of your configured identity provider (In this example AzureAD) +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 Azure AD 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" + +:::note +It is only possible to automatically create accounts, that send all the required information to register a new user. +If your provider does not send all the required fields that ZITADEL needs to create a user, make sure to fill them in the background with an Action. +[Example for prefilling user data automatically](/docs/guides/integrate/identity-providers/additional-information#automatically-prefill-user-data) +::: + +#### Login with your user + +Last step is that your user can login to ZITADEL and use the SSO account. + +import OrgLoginDescription from "./_org_login_description.mdx"; + + + +Your user is now ready to login with SSO. +User Login 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 managers, roles and their meanings [here](/docs/guides/manage/console/managers) + +Register Organization Form + +#### 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 request: +[Restrict the instance features](/docs/apis/resources/admin/admin-service-set-restrictions) + +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 setup 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 needed information like the profile, email, password. etc. +This request allows you only to setup a user with password authentication at the moment. +By specifying the roles you can define, which permission the user should have within ZITADEL. +Per default the user will automatically get "ORG_OWNER". + +Setup Organiation with Admin User Graphic + +#### Example Request + +```bash +curl -L -X POST 'https://$CUSTOM-DOMAIN/admin/v1/orgs/_setup' \ +-H 'Content-Type: application/json' \ +-H 'Accept: application/json' \ +-H 'Authorization: Bearer ' \ +--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": "gigi@zitadel.com", + "isEmailVerified": true + }, + "phone": { + "phone": "+41 71 000 00 00", + "isPhoneVerified": true + }, + "password": "my_53cr3t-P4$$w0rd" + }, + "roles": [ + "string" + ] +}' +``` + +Detailed description of [Setup Organization](/docs/apis/resources/admin/admin-service-set-up-org#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 ressources. +The set organization metadata request allows you to add one key value pair to an organization: +[Set Organization Metadata](/docs/apis/resources/mgmt/management-service-set-org-metadata) +If you have more than one field, you can use the bulk add request: +[Bulk Set Organization Metadata](/docs/apis/resources/mgmt/management-service-bulk-set-org-metadata) + +The same requests also exist on the user ressource: +[Set User Metadata](/docs/apis/resources/mgmt/management-service-set-user-metadata) +[Bulk Set User Metadata](/docs/apis/resources/mgmt/management-service-bulk-set-user-metadata) diff --git a/docs/docs/guides/solution-scenarios/onboarding/end-users.mdx b/docs/docs/guides/solution-scenarios/onboarding/end-users.mdx new file mode 100644 index 000000000..ec67b7e2e --- /dev/null +++ b/docs/docs/guides/solution-scenarios/onboarding/end-users.mdx @@ -0,0 +1,92 @@ +--- +title: Onboard Users +sidebar_label: Onboard Users +--- + +End Users have three different possibilities on how to login with ZITADEL. +1. Local Account with Username, Password, MFA, Passkey, etc +2. Social Login like Google, Apple, Github, etc +3. External Identity Provider hosted/managed by Organization like Azure AD, LDAP, Okta etc + +You can either use the hosted login of ZITADEL to let users register themselves, or you can build your own UI and use the existing APIs. + +## Manually add/invite users + +import CreateUser from '/docs/guides/manage/console/_create-user.mdx'; + + + +## Automated / Self-registration possibilities + +If you want to start automating the process of onboarding your users and let them do self-registration the following sections give you some guidance. + +### Built-in register form + +#### Local User Registration + +To allow users to register themselves, you have to enable the "register allowed" in the login behavior settings. +You will now see the register button on the login screen. + +Register End User + +If nothing else is specified, a user will be registered to the default organization. +Default Organization + +You can specify another organization, by sending the organization scope in the authorization requests. +By sending the scope below the settings of the specified organization will be triggered and only users of the said organization will be able to authenticate. +The users will be registered to the given organization. +``` +urn:zitadel:iam:org:id:{id} +``` + +If the user chooses to register a local account, the register form will be shown. +All the mandatory fields like given name, family name, e-mail and password have to be filled. +You can only setup authentication with the built-in form. + +Register local user + +#### Registration with Social Login + +To allow your users to register with social logins you have to configure the external identity providers. +If you only need the social logins for your end users and you want to have them all in the organization, we recommend using the default organization for those users. +In that case you can configure the identity providers on the default organization. +If you want to have the social logins on different organizations you can configure the default on the instance, and enable it on the needed organizations. + +Please follow the configuration guides for the needed providers: [Let Users Login with Preferred Identity Provider in ZITADEL](/docs/guides/integrate/identity-providers) + +The configured providers will be shown on the first login screen or when the users click on the registration button, they will be able to choose between local account or the social login. + +Register End User + +#### Registration with Organization External Identity Provider + +If your business customer already have an identity provider, and you want to allow SSO for them, you can configure their providers directly for their organization. +Configure the needed provider such as Azure AD or OKTA. + +Please follow the configuration guides for the needed providers: [Let Users Login with Preferred Identity Provider in ZITADEL](/docs/guides/integrate/identity-providers) + +import OrgLoginDescription from "./_org_login_description.mdx"; + + + +### Build your own registration form + +ZITADEL allows you to build your own registration form and login UI. +The registration process highly depends on your needs. + +We do have a guide series on how to build your own login ui, which also includes the registration of different authentication methods, such as: +- Password authentication +- Multi-Factor +- Passkeys +- External Login Providers + +You can find all the guides here: [Build your own login UI](https://zitadel.com/docs/guides/integrate/login-ui) + +The create user request also allows you to add metadata (key, value) to the user. +This gives you the possibility to collect additional data from your users during the registration process and store it directly to the user in ZITADEL. +We recommend storing business relevant data in the database of your application, and only authentication and authorization relevant data in ZITADEL to follow the separation of concern pattern. + +#### Registration with Organization External Identity Provider + +If you want to know more about the multi-tenancy possibilities of ZITADEL, read the following blog post: +[Multi-Tenancy and Delegated Access Management with Organizations](https://zitadel.com/blog/multi-tenancy-with-organizations) \ No newline at end of file diff --git a/docs/docs/self-hosting/manage/production.md b/docs/docs/self-hosting/manage/production.md index b4ea7f340..ac15a0a40 100644 --- a/docs/docs/self-hosting/manage/production.md +++ b/docs/docs/self-hosting/manage/production.md @@ -121,7 +121,7 @@ Database: You also might want to configure how [projections](/concepts/eventstore/implementation#projections) are computed. These are the default values: ```yaml -# The Projections section defines the behaviour for the scheduled and synchronous events projections. +# The Projections section defines the behavior for the scheduled and synchronous events projections. Projections: # Time interval between scheduled projections RequeueEvery: 60s diff --git a/docs/docs/support/advisory/a10000.md b/docs/docs/support/advisory/a10000.md index 5b7a8e20f..8bd7d2b95 100644 --- a/docs/docs/support/advisory/a10000.md +++ b/docs/docs/support/advisory/a10000.md @@ -19,7 +19,7 @@ To address this, we are going to change this behavior so that users will be auto ## Statement -This behaviour change was tracked in the following issue: [Reuse current session if no prompt is selected](https://github.com/zitadel/zitadel/issues/4841) +This behavior change was tracked in the following issue: [Reuse current session if no prompt is selected](https://github.com/zitadel/zitadel/issues/4841) and released in version [v2.32.0](https://github.com/zitadel/zitadel/releases/tag/v2.32.0) ## Mitigation diff --git a/docs/docs/support/advisory/a10001.md b/docs/docs/support/advisory/a10001.md index e082107c0..013a9b2d2 100644 --- a/docs/docs/support/advisory/a10001.md +++ b/docs/docs/support/advisory/a10001.md @@ -20,7 +20,7 @@ To address this, we are going to change the behavior of the setting mentioned ab ## Statement -This behaviour change was tracked in the following PR: [Restrict AllowRegistration check to local registration](https://github.com/zitadel/zitadel/pull/5939). +This behavior change was tracked in the following PR: [Restrict AllowRegistration check to local registration](https://github.com/zitadel/zitadel/pull/5939). The change was part of version [v2.35.0](https://github.com/zitadel/zitadel/releases/tag/v2.35.0) ## Mitigation diff --git a/docs/docs/support/advisory/a10003.md b/docs/docs/support/advisory/a10003.md index d3a5d868d..b03265add 100644 --- a/docs/docs/support/advisory/a10003.md +++ b/docs/docs/support/advisory/a10003.md @@ -14,7 +14,7 @@ When users are redirected to the ZITADEL Login-UI without any organizational con based on the instance settings, e.g. available IDPs and possible login mechanisms. If the user will then register himself, by the registration form or through an IDP, the user will always be created on the default organization. -This behaviour led to confusion, e.g. when activating IDPs on default org would not show up in the Login-UI, because they would still be loaded from the instance settings. +This behavior led to confusion, e.g. when activating IDPs on default org would not show up in the Login-UI, because they would still be loaded from the instance settings. To improve this, we're introducing the following change: If users are redirected to the Login-UI without any organizational context, they will be presented a login screen based on the settings of the default organization (incl. IDPs). diff --git a/docs/docs/support/advisory/a10004.md b/docs/docs/support/advisory/a10004.md index 787c65aeb..ed5e8fabe 100644 --- a/docs/docs/support/advisory/a10004.md +++ b/docs/docs/support/advisory/a10004.md @@ -10,7 +10,7 @@ Date: 2023-10-14 ## Description -Due to storage optimisations ZITADEL changes the behaviour of sequences. +Due to storage optimisations ZITADEL changes the behavior of sequences. This change improves command (create, update, delete) performance of ZITADEL. Sequences are no longer unique inside an instance. diff --git a/docs/docs/support/technical_advisory.mdx b/docs/docs/support/technical_advisory.mdx index f0d4d068d..74c3dfa08 100644 --- a/docs/docs/support/technical_advisory.mdx +++ b/docs/docs/support/technical_advisory.mdx @@ -23,7 +23,7 @@ We understand that these advisories may include breaking changes, and we aim to A-10000 Reusing user session - Breaking Behaviour Change + Breaking Behavior Change The default behavior for users logging in is to be directed to the Select Account Page on the Login. With the upcoming changes, users will be @@ -39,13 +39,13 @@ We understand that these advisories may include breaking changes, and we aim to A-10001 Login Policy - Allow Register - Breaking Behaviour Change + Breaking Behavior Change When disabling the option, users are currently not able to register locally and also not through an external IDP. With the upcoming change, the setting will only prevent local registration. Restriction to Identity Providers can be managed through the corresponding IDP Template. No action - is required on your side if this is the intended behaviour or if you + is required on your side if this is the intended behavior or if you already disabled registration on your IDP. 2.35.0 @@ -75,7 +75,7 @@ We understand that these advisories may include breaking changes, and we aim to A-10003 Login-UI - Default Context - Breaking Behaviour Change + Breaking Behavior Change When users are redirected to the ZITADEL Login-UI without any organizational context, they're currently presented a login screen, based on the instance settings, @@ -91,9 +91,9 @@ We understand that these advisories may include breaking changes, and we aim to A-10004 Sequence uniquenes - Breaking Behaviour Change + Breaking Behavior Change - Due to storage optimisations ZITADEL changes the behaviour of sequences. + Due to storage optimisations ZITADEL changes the behavior of sequences. This change improves command (create, update, delete) performance of ZITADEL. Sequences are no longer unique inside an instance. From now on sequences are upcounting per aggregate id. @@ -123,7 +123,7 @@ We understand that these advisories may include breaking changes, and we aim to A-10006 Additional grant to cockroach database user - Breaking Behaviour Change + Breaking Behavior Change Versions >= 2.39.0 require the cockroach database user of ZITADEL to be granted to the `VIEWACTIVITY` grant. This can either be reached by grant the role manually or execute the `zitadel init` command. @@ -135,7 +135,7 @@ We understand that these advisories may include breaking changes, and we aim to A-10007 Additional grant to cockroach database user - Breaking Behaviour Change + Breaking Behavior Change Upcoming Versions require the SYSTEM_OWNER role to be available in the permission role mappings. Self-hosting ZITADEL users who define custom permission role mappings need to make sure their system users don't lose access to the system API. @@ -165,7 +165,7 @@ As ZITADEL Cloud customer, you can also login to the