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.
When setting up a new organization, follow all the steps in this guide in order to have a working setup.
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.
Where to find the root user
New environment → Helmfile
10_document_chat.yamlunder the “zitadel” release (search for “Cluster IAM”)Local setup → In the
monorepounder.devcontainer/unique.example/zitadel/zitadel-init-steps.yaml
The root user’s password must be changed when initially logging in.
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
Development Mode
If working with a local setup for development, the Development Mode needs to be enabled to allow for http localhost URLs of the services (same for Redirect and Post Logout). The URLs for local development the following:
- 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. All the roles and their descriptions can be found on the following page: Roles and Permissions.
Navigate to the “Roles” section on the project click on “+ New” and add all roles defined on the “Roles and Permissions” page linked above.
The screenshot might be up to date on all roles and only shows an example of roles added in a project. Refer to https://unique-ch.atlassian.net/wiki/x/SICeHg and add all roles that are listed there.
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.
Creating additional (new) roles in Zitadel
When adding new roles the following actions are required:
Add the new role to the project on the “Cluster IAM” root organization
Add the new role to the Grant given to the organizations. This can be done by clicking on a grant and editing it to make sure the new role is included in the grant.
4. Adding Zitadel Actions
tbd - work in progress
5. 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.
Author |
|---|