Skip to main content

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.

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.

Instance Button

When you configure your instance, you can set the following:

  • General: Default Language for the UI
  • Notification settings: 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: 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.
  • 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.
  • 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
  • Privacy Policy: Links to your own Terms of Service and Privacy Policy regulations. Link to Help Page.
  • OIDC Token Lifetimes and Expiration: Token lifetime and expiration settings.
  • Secret Appearance: Appearance of the generated codes and secrets used in mails for verification etc.

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.

Private Labeling

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.

SettingDescription
LogoUpload your logo for the light and the dark design. This is used mainly in the login interface.
IconUpload 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.
ColorsYou can set four different colors to design your login page and email. (Background-, Primary-, Warn- and Font Color)
FontUpload your custom font
Advanced BehaviourHide 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

Notification

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. 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
SMTP

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 Sender Number.

Twilio

Login Behaviour and Access

The Login Policy defines how the login process should look like and which authentication options a user has to authenticate.

SettingDescription
Register allowedEnable self register possibility in the login ui, this enables username password registration as well as registration with configured external identity providers
Username Password allowedPossibility to login with username and password. If this is disabled only login with external identity providers will be allowed
External IDP allowedPossibility 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
Force MFAForce a user to register and use a multifactor authentication, Ensure that you have added the MFA methods you want to allow.
PasswordlessChoose if passwordless login is allowed or not
Login Bahaviour and Access

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

Secondfactors (2FA):

  • OTP (One Time Password), Authenticator Apps like Google/Microsoft Authenticator, Authy, etc.
  • U2F (Universal Second Factor), e.g FaceID, WindowsHello, Fingerprint, Hardwaretokens like Yubikey

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
  • Multifactor 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
  • External 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 guide: Identity Brokering

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
Password Complexity

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.

If an account is locked, the administrator has to unlock it in the ZITADEL console

Lockout

Domain settings

In the domain policy you have two different settings. One is the "user_login_must_be_domain", by setting this all the users within an organisation will be suffixed with the domain of the organisation.

The second is "validate_org_domains" if this is set to true all created domains on an organisation must be verified per 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.

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.

Privacy Policy and TOS

With this setting you are able to configure your privacy policy, terms of service and help links. 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}}

Privacy Policy

Message texts

These are the texts for your notification mails. Available for change are:

Message TextDescription
Domain ClaimThe Mail after an organisation claimed a domain for itself. Users on other organisations with this domain will be notified
InitializationThe mail after a user has been created. A code is part of the message which then must be verified on first login
PasswordlessThe Mail to register an additional passwordless device by a link
Password ResetThe Mail to reset the password by a link
Verify EmailThe mail after the email has been changed. A code is part of the message which then must be verified on the next login
Password ChangeNotify the user, that the password has been changed. Can be configured in Notification

You can set the locale of the translations on the right.

Message texts

Login interface texts

These are the texts for the login. Just like for message texts, you can select the locale on the right.

Login texts

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
OIDC Token Lifetimes

Secret appearance

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
Secret appearance

If your done with your instance settings, you can proceed setting up your organizations. Again, make sure you get an understanding on how your project is structured and then continue.