ZITADEL Default Settings
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 settomgs 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:
- Organizations: A list of your organizations
- Features: Feature Settings let you try out new features before they become generally available. You can also disable features you are not interested in.
- Notification settings: Setup Notification and Email Server settings for initialization-, verification- and other mails. Setup Twilio as SMS notification provider.
- 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: Define IDPs which are available for all organizations
- Password Complexity: Requirements for Passwords ex. Symbols, Numbers, min length and more.
- Password Expiry: Set an expiry for passwords. After the expiration, a user will be prompted to change their password during the next login.
- 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.
- Domain settings: Whether users use their email or the generated username to login. Other Validation, SMTP settings
- Branding: Appearance of the login interface.
- Message Texts: Text and internationalization for emails
- Login Interface Texts: Text and internationalization for the login interface
- External Links: Links to your own Terms of Service and Privacy Policy regulations, Help Page, Support email, documentation link...
- OIDC Token Lifetimes and Expiration: Token lifetime and expiration settings.
- Secret Generator: Appearance and expiration of the generated codes and secrets used in mails for verification etc.
Features​
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 console, to new APIs or performance improvements.
Be careful on which features you enable as they can be in an experimental state.
Branding​
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 behavours. 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 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 configuration" button after you finish your configuration. 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 settiong.
Notification settings​
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.
Notification​
You can configure on which changes the users will be notified. The text of the message can be changed in the Message texts
SMTP​
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.
You have to activate your SMTP provider so Zitadel can use it to send your emails. Only one provider can be active.
Go to the ZITADEL customer portal to configure a custom domain.
To configure your custom SMTP please fill the following fields:
- Sender email address
- Sender name
- Enable or Disable Transport Layer Security (TLS)
- Host
- User
- SMTP Password
While you create/update a SMTP provider you have the chance to test your SMTP configuration
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
SMS​
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 configuration 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.
Login Behavior and Access​
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 does't not mandatory have to exist when entering the username. It is required to have verified domains on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters john@zitadel.com 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 john@zitadel.com, 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. |
Default Redirect URI​
The Default Redirect URI will be used, if a user calls the login page directly.
More specifically, typically a client will initiate login with an auth request.
The auth request contains a client-id and a redirect uri, that must match the configuration 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:
- The login has not been called with an OIDC authorize request
- The user landed on the login through an email link, e.g. Password Reset, Initialize User
We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL console.
Change default redirect url of instance: https://<custom_domain>/ui/console/settings?id=login
Passwordless​
Passwordless 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).
Multifactor (MFA)​
In the multifactors section you can configure what kind of multifactors should be allowed. For passwordless to work, it's required to enable U2F (Universial Second Factor) with PIN. There is no other option at the moment. Multifactors:
- U2F (Universal Second Factor) with PIN, e.g FaceID, WindowsHello, Fingerprint, Hardwaretokens like Yubikey
Second factors (2FA):
- Time-based One Time Password (TOTP), Authenticator Apps like Google/Microsoft Authenticator, Authy, etc.
- Universal Second Factor (U2F), e.g FaceID, WindowsHello, Fingerprint, Hardware tokens like Yubikey
- One Time Password with Email (Email OTP)
- One Time Password with SMS (SMS OTP)
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.
Login Lifetimes​
Configure the different lifetimes checks for the login process:
- Password Check Lifetime specifies after which period a user has to reenter his password during the login process
- External Login Check Lifetime specifies after which period a user will be redirected to the IDP during the login process
- Multi-factor Init Lifetime specifies after which period a user will be prompted to setup a 2-Factor / Multi-factor during the login process (value 0 will deactivate the prompt)
- Second Factor Check Lifetime specifies after which period a user has to revalidate the 2-Factor during the login process
- Multi-factor Login Check Lifetime specifies after which period a user has to revalidate the Multi-factor during the login process
Identity Providers​
You can configure 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 configure a new identity provider for identity brokering have a look at our identity provider guides.
Password Complexity​
With the password complexity policy you can define the requirements for a users password.
The following properties can be set:
- Minimum Length
- Has Uppercase
- Has Lowercase
- Has Number
- Has Symbol (Everything that is not a number or letter)
Password Expiry​
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:
- Maximum validity in days
- Expiration warning after days
Lockout​
Define when an account should be locked.
The following settings are available:
- Maximum Password Attempts: When the user has reached the maximum password attempts the account will be locked, If this is set to 0 the lockout will not trigger.
- Maximum OTP Attempts: When the user has reached the maximum (T)OTP attempts the account will be locked, If this is set to 0 the lockout will not trigger.
If an account is locked, the administrator has to unlock it in the ZITADEL console
Domain settings​
Add organization domain as suffix to loginnames​
If you enable this setting, all loginnames will be suffixed with the organization domain. If this settings is disabled, you have to ensure that usernames are unique over all organizations.
Validate Org domains​
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.
SMTP Sender Address matches Instance Domain​
If enabled, the SMTP server address must match the instance's primary domain. With that you can ensure that users receive notifications from the same domain that is used for login.
Use email as username​
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 configuration guide for more information.
External links​
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 overriden 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 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).
Message texts​
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 |
| Passwordless | The Mail to register an additional passwordless 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 Change | 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.
Login interface texts​
These are the texts for the login. Just like for message texts, you can select the locale on the right.
Languages​
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.
OIDC token lifetimes and expiration​
Configure how long the different oidc tokens should life. You can set the following times:
- Access Token Lifetime
- ID Token Lifetime
- Refresh Token Expiration
- Refresh Token Idle Expiration
Secret generator​
ZITADEL has some different codes and secrets, that can be specified. You can configure what kind of characters should be included, how long the secret should be and the expiration. The following secrets can be configured:
- Initialization Mail Code
- Email verification code
- Phone verification code
- Password reset code
- Passwordless initialization code
- Application secrets
- One Time Password (OTP) - SMS
- One Time Password (OTP) - Email
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.