apps/docs/content/guides/manage/console/default-settings.mdx
Default settings work as default or fallback settings for your organizational settings. Most of the time you only have to set default settings for the cases where you don't need specific behavior in the organizations themselves or you only have one organization.
To access default settings, use the settings page at {instanceDomain}/ui/console/settings or click at the default settings button on the top-right of the page and then navigate to settings in the navigation.
When you configure your default settings, you can set the following:
Feature Settings let you try out new features before they become generally available. You can also disable features you are not interested in.
The Page lets you choose between the settings Enabled, Disabled or Inherit.
If a feature is set to Inherit, it becomes available once its enabled per default.
Features can range from UI changes in the management console, to new APIs or performance improvements.
<Callout type="warn"> Be careful on which features you enable as they can be in an experimental state. </Callout>We recommend setting your Branding and SMTP settings initially as it will comfort your customers having a familiar UI for login and receiving notifications from your domain and mail addresses.
In the Branding settings, you can upload you Logo for the login interface, set your own colors for buttons, background, links, and choose between multiple behaviors. You don't need to be an expert as those settings can all be set without any knowledge of CSS.
| Setting | Description |
|---|---|
| Logo | Upload your logo for the light and the dark design. This is used mainly in the login interface. |
| Icon | Upload your icon for the light and the dark design. Icons are used for smaller components. For example in management 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 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 settings" button after you finish your settings. This will ensure your design is visible for your customers.
Branding settings applied on you instance act as a default for all your organizations. If you need custom branding on a organization take a look at our guide under organization setting.
In the notification settings you can configure when to notify users about certain events and you can customize your SMTP Server settings and your SMS Provider. At the moment Twilio is available as SMS provider.
You can configure on which changes the users will be notified. The text of the message can be changed in the Message texts
On each instance we configure our default SMTP provider. To make sure, that you only send some E-Mails from domains you own, you need to add a Custom Domain on your instance.
You can configure many SMTP providers using templates for popular providers. The templates will add known settings like host, port or default user and will suggest values for user and/or password.
<Callout> You have to activate your SMTP provider so Zitadel can use it to send your emails. Only one provider can be active. </Callout> <Callout type="warn"> The built-in SMTP provider is intended **only for testing and evaluation purposes**. Email delivery through this service may be **delayed or temporarily unstable**.For any production setup, you must configure your own SMTP provider to ensure reliable and consistent email delivery. </Callout>
Go to the ZITADEL customer portal to configure a Custom Domain.
To configure your custom SMTP please fill the following fields:
While you create/update a SMTP provider you have the chance to test your SMTP settings
In the SMTP providers table you can hover on a provider row to show buttons that allow you to activate/deactivate a provider, test your smtp settings and delete a provider
No default provider is configured to send some SMS to your users. If you like to validate the phone numbers of your users make sure to add your twilio settings by adding your Sid, Token and either a Sender Number or a Verification Service Sid. Setting a Verification Service Sid allows using the Twilio Verify Service instead of the Messages Service for verification.
The Login Policy defines how the login process should look like and which authentication options a user has to authenticate.
| Setting | Description |
|---|---|
| Username Password allowed | Possibility to login with username and password. If this is disabled only login with external identity providers will be allowed |
| Register allowed | Enable self register possibility in the login ui, this enables username password registration as well as registration with configured external identity providers |
| External IDP allowed | Possibility to login with an external identity (e.g Google, Microsoft, Apple, etc), If you like to allow external Identity providers add them to the providers list |
| Hide password reset | Disable the self-service option for users to reset their password. |
| Domain discovery allowed | If this setting is enabled, the user doesn't have to exist when entering the username. It is required to have an Organization Domain on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters [email protected] in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the Entra ID. |
| Ignore unknown usernames | This setting can be enabled, if no error message should be shown if the user doesn't exist. Example: A user enters the login name [email protected], the user doesn't exist, but will be redirected to the password screen. After entering a password, the user will get an error that either username or password are wrong. |
| Disable login with email address | By default users can additionally login with the email attribute of their user. Check this option to disable. |
| Disable login with phone number | By default users can additionally login with the phonenumber attribute of their user. Check this option to disable. |
The Default Redirect URI will be used, if a user calls the login page directly.
More specifically, typically an application will initiate login with an auth request.
The auth request contains a client-id and a redirect uri, that must match the settings in ZITADEL.
If there is no auth request, users will be redirected to the Default Redirect URI, which is by default https://${CUSTOM_DOMAIN}/ui/console/
Reasons why ZITADEL doesn't have a redirect URI:
We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL Management Console.
Change default redirect url of instance: https://${CUSTOM_DOMAIN}/ui/console/instance?id=login
Passkey authentication means that the user doesn't need to enter a password to login. In our case the user has to enter his loginname and as the next step proof the identity through a registered device or token. There are two different types one is depending on the device (e.g. Fingerprint, Face recognition, WindowsHello) and the other is independent (eg. Yubikey, Solokey).
In the multifactors section you can configure what kind of multifactors should be allowed. For passkeys to work, it's required to enable U2F (Universal Second Factor) with PIN. There is no other option at the moment. Multifactors:
Second factors (2FA):
Force a user to register and use a multifactor authentication, by checking the option "Force MFA". Ensure that you have added the MFA methods you want to allow. Or you can enable the "Force MFA for local authenticated users", which will enforce this rule only on local authentication, but not on users authenticated through an Identity Provider.
Configure the different lifetimes checks for the login process:
You can set up all kinds of external identity providers for identity brokering, which support OIDC (OpenID Connect). Create a new identity provider configuration and enable it in the list afterwards.
For a detailed guide about how to set up a new identity provider for identity brokering have a look at our identity provider guides.
With the password complexity policy you can define the requirements for a users password.
The following properties can be set:
With the password expiry policy you can set an expiration for user password. After the expiration, a user will be prompted to change their password during the next authentication.
Note, that ZITADEL will not warn or notify the user about the expiry, yet. If you want your users to be notified, you can read this setting and send the notification yourself.
The following properties can be set:
Define when an account should be locked.
The following settings are available:
If an account is locked, the administrator has to unlock it in the ZITADEL Management Console
If you enable this setting, all loginnames will be suffixed with the Organization Domain. If this setting is disabled, you have to ensure that usernames are unique over all organizations.
If this is enabled all created domains on an organization must be verified per dns/acme challenge.
More about how to verify a domain here. If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login.
If enabled, the SMTP server address must match the instance's primary Custom Domain. With that you can ensure that users receive notifications from the same domain that is used for login.
To be able to use the email as username you have to disable the attribute "User Loginname must contain orgdomain" on your domain settings. This means that all your users will not be suffixed with the domain of your organization and you can enter the email as username. All usernames will then be globally unique within your instance.
You can either set this attribute on your whole ZITADEL instance or just on some specific organizations.
Please refer to the settings guide for more information.
With this setting you are able to configure your privacy policy, terms of service, help links and help/support email address.
On register each user has to accept these policies.
This policy can be also be overridden by your organizations.
When focused on an input field you can see the language attribute, which can then be integrated into your link.
Example:
https://demo.com/tos-{{.Lang}}
Also you can set the link associated to the Documentation button in the console. Set an empty text if you don't want to show a Documentation button in your console. If you need a custom button to be shown in the management console you can set the button text and the link associated to the button (if the button text is button no text will be shown).
These are the texts for your notification mails. Available for change are:
| Message Text | Description |
|---|---|
| Domain Claim | The Mail after an organisation claimed a domain for itself. Users on other organisations with this domain will be notified |
| Initialization | The mail after a user has been created. A code is part of the message which then must be verified on first login |
| Passkey | The Mail to register an additional passkey device by a link |
| Password Reset | The Mail to reset the password by a link |
| Verify Email | The mail after the email has been changed. A code is part of the message which then must be verified on the next login |
| Password Changed | Notify the user, that the password has been changed. Can be configured in Notification |
You can set the locale of the translations on the right.
These are the texts for the login. Just like for message texts, you can select the locale on the right.
Drag allowed languages to the left column. Languages in the right column are not shown to your users.
Choose a default language which acts as a fallback, if no language header is set.
Set up how long the different oidc tokens should live. You can set the following times:
ZITADEL has some different codes and secrets, that can be specified. You can specify what kind of characters should be included, how long the secret should be and the expiration. The following secrets can be specified:
If your done with your default settings, you can proceed setting up your organizations. Again, make sure you get an understanding on how your project is structured and then continue.