Configuring user and login options (Legacy Zitadel Documentation)

Zitadel Deprecated

Zitadel will no longer be supported in future versions of PhariaAI. All users must migrate to Dex to continue receiving updates and support.

This document contains legacy Zitadel configuration instructions for existing installations only.

For new installations

If you are setting up a new PhariaAI installation, do not use Zitadel. Instead, configure Dex during the installation process. See the IAM Configuration section in the Installation Process guide for detailed instructions on configuring Dex with your external OIDC identity provider.

For existing Zitadel installations

If you are using an existing Zitadel installation, please plan your migration to Dex as soon as possible. See How to migrate from Zitadel to Dex for complete migration instructions.

The legacy Zitadel configuration instructions below are provided only for existing installations that have not yet migrated to Dex.

---

Legacy: Configuring Zitadel (Deprecated)

caution

The information below applies to existing Zitadel-based installations only. This is legacy documentation that will be removed in a future release.

For new installations, use Dex which only supports federated authentication through external identity providers. See the Installation Process guide for configuration instructions.

This section guides you through configuring and using Zitadel (deprecated) as the identity provider for PhariaAI.

Installing with Zitadel

If you need to install PhariaAI with Zitadel (only for existing deployments that cannot migrate to Dex immediately), use the following configuration:

You can provide custom credentials for the initial user account in the section pharia-iam.config. This user account is used for user management in the PhariaAI stack via PhariaOS.

pharia-iam:
  config:
    # -- Init password of initial user. To be valid it requires to have 10-70 characters, including at least one uppercase letter, one lowercase letter, and one digit. User will need to change this password on the first login.
    adminPassword:
    # -- Enable management rights for Zitadel configuration
    adminEnableZitadelManagement: true

zitadel:
  enabled: true

dex:
  enabled: false

If you want to enable extra sign-up options such as self-sign-up or sign-up with SSO, you need to enable the rights to configure Zitadel by setting pharia-iam.config.adminEnableZitadelManagement: true. This grants the rights to configure sign-up options to your initial user account.

Post-installation steps

After installation, navigate to https://login.<YOUR_CONFIGURED_DOMAIN>/ and log in with the initial user account (configured in the Helm chart values pharia-iam.config) to complete the setup of the initial user credentials.

If you did not provide a custom initial user account password, you can display the autogenerated password with the following command:

kubectl get secret pharia-iam-admin-password  -o jsonpath="{.data.password}" | base64 -d

Login options with Zitadel

This section guides you through the login options for users in PhariaAI using Zitadel (deprecated). You can choose to configure one of the following options:

• Single Sign-On (SSO) with an external identity provider, or
• self-registration via email

How to enable SSO with an external identity provider (Zitadel)

The internal identity provider of PhariaAI, Zitadel, offers the possibility to integrate external identity providers for single sign-on (SSO). This allows users to log in to PhariaAI with their existing account from a company identity provider, such as Google, Microsoft, or Okta.

Prerequisites

• You enabled the flag pharia-iam.config.adminEnableZitadelManagement during the installation of PhariaAI; see IAM configuration.

Configure an external identity provider in Zitadel

1. Open the Zitadel Console
   • Navigate to the Zitadel console at https://login.<YOUR_CONFIGURED_DOMAIN> and log in with your initial user account.
   • If you happen to land on the info page of your admin account, navigate to https://login.<YOUR_CONFIGURED_DOMAIN>/ui/console or click on the logo in the top left corner. If this has no effect, you probably logged in with the wrong account.
2. Add an external identity provider
   • Switch to the Pharia organization.
     
   • Go to the Settings tab and select Identity Provider. Here you find a list of pre-configured external identity providers. Choose the desired provider and follow the instructions.
   • Some identity providers do not provide email verification information, although the email address is already verified. In this case check the box Email verified, to prevent any additional email verification steps:
     
   • For a seamless user experience, allow accounts to be created automatically only.
     
   • Make sure to activate the identity provider by clicking on the Activate button. For more information on how to configure external identity providers, see the Zitadel documentation.

Enable SSO in the login page

1. Enable external login for the Pharia organization
   • Go to the Settings tab and select Login Behavior and Security. On the bottom of the page, check the box for External Login allowed. Then click on Save.
2. Make Pharia the default organization
   • Go to the "all organizations" view by clicking on the two arrows next to the organization name in the top left corner and choosing Show All Organizations.
   • Click on the three dots next to the Pharia organization and select Set as default organization.

Configure default roles for federated users

To access any resource in PhariaAI, a user must be assigned a role. You can configure default roles for federated users to be assigned on the first login.

Add role assignment

• Go to the Actions tab. A default action with the name assignDefaultRole will already be present, which by default assigns the AssistantUser role. If you wish to assign a different default role from AssistantUser, you can change this in the values under pharia-iam.config.defaultRolesForLogin.
• Select the flow type External Authentication and click the Add Trigger button. Select Trigger Type Post Creation and select the assignDefaultRole Action. Click on Save.

How to enable self-sign-up (Zitadel)

PhariaAI uses Zitadel as an identity provider. Zitadel provides a self-service registration flow that allows users to sign up for an account without the need for an administrator to create an account for them. Using this flow, a user can sign up for an account by providing their email address and a password. They then receive a verification email to confirm their email address and complete the registration process. We recommend to filter the email addresses to allow only those users with a specific email domain to sign up.

warning

Self-registration with username/password is not supported in Dex. After migrating to Dex, all users must authenticate through an external identity provider. See the migration guide for details on the authentication changes.

Prerequisites

• You enabled the flag pharia-iam.config.adminEnableZitadelManagement during the installation of PhariaAI; see IAM configuration.
• You have an email provider that you can use to send verification emails.

Configure an email provider in Zitadel

To enable self-sign-up, you need to configure an email provider in Zitadel. This is necessary to send verification emails to users who sign up for an account. You can use one of the pre-configured email providers or any other email provider that supports SMTP or API-based email sending.

1. Open the Zitadel Console
   • Navigate to the Zitadel console at https://login.<YOUR_CONFIGURED_DOMAIN>/ and log in with your initial user account.
   • If you happen to land on the info page of your admin account, navigate to https://login.<YOUR_CONFIGURED_DOMAIN>/ui/console or click on the logo in the top left corner. If this has no effect, you probably logged in with the wrong account.
2. Configure an email provider
   • Open the Default Settings on the right upper corner and navigate to the Email Providers section.
   • Add your preferred email provider by clicking on its icon and following the instructions.

Enable self-registration in Zitadel

1. Open the Zitadel Console
   • Go back to the main screen by clicking on the logo in the top left corner.
2. Enable self-sign-up and domain discovery for the Pharia organization
   • Switch to the Pharia organization.
     
   • Go to the Settings tab and select Login Behavior and Security. On the bottom of the page, check the boxes for User Registration allowed and Domain Discovery allowed. Then click on Save.
   • Navigate to the settings for Verified domains. Make sure that the email domain of your company appears here, otherwise add it by clicking on the + New button.
3. Install check for correct domain on sign up
   • Navigate to the Actions tab and click on the + New button to create a new action. Make sure that the action has the same name as the function defined in the action, in this example filterRegistration. Copy the code from the snippet below and paste it into the editor. You need to replace the example domains with the domains you want to allow for sign-up, and you may add more domains if needed. For further information on how to write actions, see the Zitadel documentation.

     /**
     * Only allow users with a given domain to register
     *
     * Flow: Internal Authentication or External Authentication, Trigger: Pre creation
     *
     * @param ctx
     * @param api
     */
     function filterRegistration(ctx, api) {
         let validDomains = ["domain1.com", "domain2.com"];
         let isValid = false;
         for (const domain of validDomains){
             if (ctx.v1.user.human.email.endsWith("@" + domain)) {
                 isValid = true;
                 break;
             }
         }
         if (!isValid){
             throw "email needs to be from domain " + validDomains.join(", ");
         }
     }
   • Disable the box Allowed To Fail. When you do this, a warning is displayed to inform you that any coding errors (for example) may prevent users to register. However, as we specifically want to prevent registration from users with an invalid domain, we can close the warning and then click on Add.
   • Select the flow type Internal Authentication and click the Add Trigger button. Now select the Trigger Type Pre Creation and select the previously created action. Click on Save.

Optional: Configure default roles for self-registration

To access any resource in PhariaAI, a user must be assigned a role. You can configure default roles for federated users to be assigned to newly registered users.

Add role assignment

• Stay in the Actions tab for the Pharia organization. A default action with the name assignDefaultRole will already be present. If you wish to have a different default role from AssistantUser, you can change this in the values under pharia-iam.config.defaultRolesForLogin.
• Again, select the flow type Internal Authentication and click the Add Trigger button. This time select Trigger Type Post Creation and select the previously created Action. Click on Save.