This is a guide on how to configure and manage Unique’s Identity Access Management (IAM) solution Zitadel for use with the Unique platform. Refer to the applicable section for what you want to configure.

1. Cluster IAM organization

On a new environment or local setup there is a root organization in Zitadel called “Cluster IAM”. Only one root user exists and needs to be used to login for the first time to perform the initial setup.

The Cluster IAM organization is used to manage the Zitadel Project that defines the user roles for the entire environment. The project (and its roles) are then granted to other organizations in the same environment.

After successfully logging in with the root user and changing the password, the root user’s profile page in Zitadel will be displayed. Click on the “Default settings” button on the top right to get to the instance overview of Zitadel.

2. Creating an organization

On the instance overview screen, navigate to the “Organizations” section and click on the “+ New” button to create a new organization. Enter the organization name and click “Create”. You will be redirected to the overview that now includes the newly created organization.

After creating a new organization, a project can be setup and granted to it.

3. Setup a project

Navigate back to the Cluster IAM organization overview by clicking on the “Organization” button on the top right.

Open the “Projects” tab and make sure you’re on the “Cluster IAM” root organization. Then click on “Create New Project” and enter a name for the project (e.g.: “unique”).

3.1 Setup an application

Once you’ve created a project in the root organization an application needs to be setup and configured inside that project. Click on the tile with the “+” and enter an application name (e.g.: “unique-app”). For the type of the application, choose “WEB”.

In the second step, choose the Authentication Method “PKCE”.

In the third step, you need to enter the Redirect URIs and Post Logout URIs. Here’s a list of the URIs you need to add. They are the same for Redirect and Post Logout, but listed independently here for completeness. Replace “<baseUrl>” with the base URL of your environment.

Redirect URIs

- https://<baseUrl>/chat
- https://<baseUrl>/knowledge-upload
- https://<baseUrl>/theme
- https://<baseUrl>/admin

Post Logout URIs

- https://<baseUrl>/chat
- https://<baseUrl>/knowledge-upload
- https://<baseUrl>/theme
- https://<baseUrl>/admin

- http://localhost:3003/chat
- http://localhost:3004/knowledge-upload
- http://localhost:3005/theme
- http://localhost:3006/admin

On the last step, review and confirm the configuration for the application and click on “Create”.

3.2 Configure application token settings

After the application has been created, navigate to the “Token Settings” section on the application overview page. Ensure the following settings are configured and click on “Save”.

• “Auth Token Type” is set to JWT

• “Add user roles to the access token” is enabled

• “User roles inside ID Token” is enabled

• “User info inside ID Token” is enabled

3.3 Configure project roles

Roles are granted as authorizations to users in Zitadel to give access to certain features of Unique solution.

Navigate to the “Roles” section on the project click on “+ New” and add all roles defined on the “Roles and Permissions” page linked above.

3.4 Grant project to an organization

The project configured in the root “Cluster IAM” organization needs to be granted to other organizations on the Zitadel instance. To do this, navigate to the “Grants” section on the project in the “Unique IAM” root organization and click on the “+ New” button.

Search for the organization you want to add the grant for and continue. Select all the roles and save the grant.

4. Set-up Service user

4.1 Scope Management Service User

The Unique application needs a service user for syncing the user data we have in Zitadel with our Unique System. To set this service user up, the following steps are necessary:

1. In Zitadel, set-up the scope-management service user, following this documentation https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/588546089/Service+User+configuration#Creating-a-service-user. This service user needs no Unique roles to function.

2. In Zitadel, generate a Personal Access Token (PAT) for the created service user, details to be found here: https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/588546089/Service+User+configuration#Generating-personal-access-token-(PAT). Copy the PAT after creation, you will need it in step 4 to store it in the Azure Key Vault.

3. In Zitadel, give the scope-management service user, the IAM Owner Viewer role on an instance level. To switch to the instance, simply click on Default Setting at the top right in Zitadel:

   

   Then add the Service user and give it the role under this button in Zitadel:

   

   After the role was assigned to the user, it should show up like this in the list of the users with instance roles:

   

4. In the Azure Key Vault, search for the keyvault that contains the secret manual-zitadel-scope-mgmt-pat and add the generated PAT from step 2 there as a value.
   

After performing the setup of the scope-management service user, the user-sync cronjob is able to use this service user user’s PAT from the key vault to make requests to the Zitadel API and sync the provisioned users to the Unique backend.

5. Adding Zitadel Actions

tbd - work in progress

6. Configuring SSO

tbd - work in progress

OLD DOCS (will get removed soon - wip)

Scope

This tutorial only applies for clients with a Customer Managed Tenant.

Setup Actions

Add one new action called addGrant with this content

function addGrant(ctx, api) {
    api.userGrants.push({
        projectID: '<Resource ID of granted project Unique Apps>',
        projectGrantID: '<Grant ID of granted project Unique Apps>',
        roles: ['chat.chat.basic', 'chat.chat.unlimited', 'chat.chat.upload', 'chat.knowledge.read', 'chat.knowledge.write']
    });
}

This action has to be added as a Post Creation trigger in External Authentication flow.

Add another action called setEmailVerified with this content

function setEmailVerified(ctx, api) {
    api.setEmailVerified(true)
}

This action has to be added as a Pre Creation trigger in External Authentication flow.