{"type":"doc","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"When setting up a new organization, follow all the steps in this guide in order to have a working setup.","type":"text"}]}]},{"type":"rule"},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"style":{"value":"none"}},"macroMetadata":{"macroId":{"value":"6a0b2d19-25ed-409b-ab32-75cb4ec2d962"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"e0da49b8-a83b-403b-abfe-f31852d4ec03"}},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"1. Cluster IAM organization","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Where to find the root user","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"New environment","type":"text","marks":[{"type":"em"}]},{"text":" → Helmfile ","type":"text"},{"text":"10_document_chat.yaml","type":"text","marks":[{"type":"code"}]},{"text":" under the “zitadel” release (search for “Cluster IAM”)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Local setup","type":"text","marks":[{"type":"em"}]},{"text":" → In the ","type":"text"},{"text":"monorepo","type":"text","marks":[{"type":"code"}]},{"text":" under ","type":"text"},{"text":".devcontainer/unique.example/zitadel/zitadel-init-steps.yaml","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"The root user’s password must be changed when initially logging in.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"“Default settings”","type":"text","marks":[{"type":"em"}]},{"text":" button on the top right to get to the instance overview of Zitadel.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2860,"alt":"Screenshot 2024-06-03 at 19.20.32-20240603-172101.png","id":"e22b6d08-acd1-43a3-9995-0fad61f976e4","collection":"contentId-624164882","type":"file","height":1502}},{"type":"caption","content":[{"text":"Root user’s profile page in Zitadel - “Default settings” navigates to the instance overview","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"2. Creating an organization","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"“Create”","type":"text","marks":[{"type":"em"}]},{"text":". You will be redirected to the overview that now includes the newly created organization.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2860,"alt":"Screenshot 2024-06-03 at 19.30.27-20240603-173115.png","id":"3c4b12c1-a2d6-4afd-9527-fb3a067def45","collection":"contentId-624164882","type":"file","height":1502}},{"type":"caption","content":[{"text":"Adding a new organization from the instance overview","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2860,"alt":"Screenshot 2024-06-03 at 19.34.16-20240603-173422.png","id":"5cb9d3d5-b9d4-4397-b5a2-a73daa991102","collection":"contentId-624164882","type":"file","height":1502}},{"type":"caption","content":[{"text":"Creating a new organization","type":"text"}]}]},{"type":"paragraph","content":[{"text":"After creating a new organization, a project can be setup and granted to it.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"3. Setup a project","type":"text"}]},{"type":"paragraph","content":[{"text":"Navigate back to the Cluster IAM organization overview by clicking on the ","type":"text"},{"text":"“Organization”","type":"text","marks":[{"type":"em"}]},{"text":" button on the top right.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2860,"alt":"Screenshot 2024-06-03 at 19.44.46-20240603-174515.png","id":"182e330f-e039-4e85-b3c2-8b0431bac90d","collection":"contentId-624164882","type":"file","height":1502}},{"type":"caption","content":[{"text":"Navigate back to the organization overview","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Open the ","type":"text"},{"text":"“Projects”","type":"text","marks":[{"type":"em"}]},{"text":" tab and make sure you’re on the ","type":"text"},{"text":"“Cluster IAM” root organization","type":"text","marks":[{"type":"strong"}]},{"text":". Then click on ","type":"text"},{"text":"“Create New Project”","type":"text","marks":[{"type":"em"}]},{"text":" and enter a name for the project (e.g.: “unique”).","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2842,"alt":"Screenshot 2024-06-04 at 11.36.36-20240604-093742.png","id":"213373e9-b518-42e1-886a-08fb6268297a","collection":"contentId-624164882","type":"file","height":1504}},{"type":"caption","content":[{"text":"Navigate to the root organization’s projects","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2842,"alt":"Screenshot 2024-06-04 at 11.40.47-20240604-094057.png","id":"53d94215-9f02-4fd6-bd2a-1ad1d898e500","collection":"contentId-624164882","type":"file","height":1504}},{"type":"caption","content":[{"text":"Create a new project","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3.0.1 Project Settings","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you have created the project, make sure you have these settings checked.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":755,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":755,"alt":"image-20241022-100057.png","id":"ef462fc2-b750-4267-945d-bc0242c234df","collection":"contentId-624164882","type":"file","height":855}}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"3.1 Setup an application","type":"text"}]},{"type":"paragraph","content":[{"text":"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”.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2842,"alt":"Screenshot 2024-06-04 at 11.43.14-20240604-094401.png","id":"2b46c33e-ed95-4d72-b2de-f13f6f043736","collection":"contentId-624164882","type":"file","height":1504}},{"type":"caption","content":[{"text":"Create an application inside the project","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2842,"alt":"Screenshot 2024-06-04 at 11.49.05-20240604-094910.png","id":"44751a3a-44e2-41ac-9e53-1a499504f066","collection":"contentId-624164882","type":"file","height":1504}},{"type":"caption","content":[{"text":"Create an application - Step 1","type":"text"}]}]},{"type":"paragraph","content":[{"text":"In the second step, choose the Authentication Method “PKCE”. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2842,"alt":"Screenshot 2024-06-04 at 11.49.13-20240604-094919.png","id":"b7c10e0a-a542-40f2-8cc8-7fc19a618722","collection":"contentId-624164882","type":"file","height":1504}},{"type":"caption","content":[{"text":"Create an application - Step 2","type":"text"}]}]},{"type":"paragraph","content":[{"text":"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 “” with the base URL of your environment.","type":"text"}]},{"type":"paragraph","content":[{"text":"Redirect URIs","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"- https:///chat\n- https:///knowledge-upload\n- https:///theme\n- https:///admin","type":"text"}]},{"type":"paragraph","content":[{"text":"Post Logout URIs","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"- https:///chat\n- https:///knowledge-upload\n- https:///theme\n- https:///admin","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Development Mode","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"If working with a local setup for development, the Development Mode needs to be enabled to allow for ","type":"text"},{"text":"http","type":"text","marks":[{"type":"code"}]},{"text":" localhost URLs of the services (same for Redirect and Post Logout). The URLs for local development the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"- http://localhost:3003/chat\n- http://localhost:3004/knowledge-upload\n- http://localhost:3005/theme\n- http://localhost:3006/admin","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 14.02.12-20240606-120234.png","id":"7a2536d6-847b-4cfd-8f5b-c8dfba4bf7de","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Adding the Redirect and Post Logout URIs the the application","type":"text"}]}]},{"type":"paragraph","content":[{"text":"On the last step, review and confirm the configuration for the application and click on ","type":"text"},{"text":"“Create”.","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3.2 Configure application token settings","type":"text"}]},{"type":"paragraph","content":[{"text":"After the application has been created, navigate to the ","type":"text"},{"text":"“Token Settings”","type":"text","marks":[{"type":"em"}]},{"text":" section on the application overview page. Ensure the following settings are configured and click on ","type":"text"},{"text":"“Save”","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"“Auth Token Type”","type":"text","marks":[{"type":"em"}]},{"text":" is set to ","type":"text"},{"text":"JWT","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"“Add user roles to the access token”","type":"text","marks":[{"type":"em"}]},{"text":" is ","type":"text"},{"text":"enabled","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"“User roles inside ID Token”","type":"text","marks":[{"type":"em"}]},{"text":" is ","type":"text"},{"text":"enabled","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"“User info inside ID Token”","type":"text","marks":[{"type":"em"}]},{"text":" is ","type":"text"},{"text":"enabled","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 14.56.46-20240606-134015.png","id":"ea12aa3a-4070-482b-b250-c9aee146de0c","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Token configuration of the application","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3.3 Configure project roles","type":"text"}]},{"type":"paragraph","content":[{"text":"Roles are granted as authorizations to users in Zitadel to give access to certain features of Unique solution. ","type":"text"}]},{"type":"panel","attrs":{"panelIconId":"2139","panelIcon":":information_source:","panelIconText":"ℹ️","panelColor":"#DEEBFF","panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"All the roles and their descriptions can be found on the following page: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/513704008"}}]}]},{"type":"paragraph","content":[{"text":"Navigate to the ","type":"text"},{"text":"“Roles” ","type":"text","marks":[{"type":"em"}]},{"text":"section on the project click on “+ New” and add all roles defined on the “Roles and Permissions” page linked above.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The screenshot might be up to date and is not showing all roles that currently exist. It only serves as an example of roles added in a project. Refer to ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://unique-ch.atlassian.net/wiki/x/SICeHg"}},{"text":" and add all roles that are listed there to make sure you are up to date.","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 15.41.40-20240606-134352.png","id":"9f12ed93-017e-48b7-a053-eba8fd546884","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Roles on a project","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"3.4 Grant project to an organization","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"“+ New” ","type":"text","marks":[{"type":"em"}]},{"text":"button.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 15.44.37-20240606-134619.png","id":"24df68c2-d6cf-4abe-b262-1c4bb0b7af73","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Adding a grant for a project","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Search for the organization you want to add the grant for and continue. Select all the roles and save the grant.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 15.50.26-20240606-135029.png","id":"340f6bfe-d321-42cb-ad03-c4ecf142d9cb","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Granting the project to a selected organization","type":"text"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2844,"alt":"Screenshot 2024-06-06 at 15.51.15-20240606-135122.png","id":"3fe1d186-f091-4c08-b8d2-1d13ac4e78a4","collection":"contentId-624164882","type":"file","height":1506}},{"type":"caption","content":[{"text":"Selecting the roles that should be granted","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Creating additional (new) roles in Zitadel","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"When adding new roles, the following actions are required:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add the new role to the project on the “Cluster IAM” root organization (as described in the previous section).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Adding new roles is only necessary if Unique introduces new roles in a release.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"4. Set-up Service user","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"4.1 Scope Management Service User","type":"text"}]},{"type":"paragraph","content":[{"text":"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: ","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Zitadel, set-up the ","type":"text"},{"text":"scope-management","type":"text","marks":[{"type":"code"}]},{"text":" service user, following this documentation ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/588546089/Service+User+configuration#Creating-a-service-user"}},{"text":". This service user needs no Unique roles to function. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Zitadel, generate a Personal Access Token (PAT) for the created service user, details to be found here: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/588546089/Service+User+configuration#Generating-personal-access-token-(PAT)"}},{"text":". Copy the PAT after creation, you will need it in step 4 to store it in the Azure Key Vault.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Zitadel, give the ","type":"text"},{"text":"scope-management","type":"text","marks":[{"type":"code"}]},{"text":" service user, the ","type":"text"},{"text":"IAM Owner Viewer","type":"text","marks":[{"type":"code"}]},{"text":" role on an instance level. To switch to the instance, simply click on Default Setting at the top right in Zitadel:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":300,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":518,"alt":"image-20240826-095238.png","id":"522b70c2-d5a3-449a-83fc-ad43b3f53a86","collection":"contentId-624164882","type":"file","height":98}}]},{"type":"paragraph","content":[{"text":"Then add the Service user and give it the role under this button in Zitadel: ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":300,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":375,"alt":"image-20240826-095746.png","id":"1aa46c48-006e-47a7-ac94-fc2f3cf13983","collection":"contentId-624164882","type":"file","height":108}}]},{"type":"paragraph","content":[{"text":"After the role was assigned to the user, it should show up like this in the list of the users with instance roles: ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":736,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1017,"alt":"image-20240826-110925.png","id":"f0962ae6-b796-4a73-a328-764c99f2995a","collection":"contentId-624164882","type":"file","height":61}}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the Azure Key Vault, search for the keyvault that contains the secret ","type":"text"},{"text":"manual-zitadel-scope-mgmt-pat","type":"text","marks":[{"type":"code"}]},{"text":" and add the generated PAT from step 2 there as a value. ","type":"text"},{"type":"hardBreak"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"After setting the PAT in the Key Vault it is necessary to redeploy, so that the ","type":"text"},{"text":"scope-management","type":"text","marks":[{"type":"code"}]},{"text":"and the ","type":"text"},{"text":"user-sync","type":"text","marks":[{"type":"code"}]},{"text":" job can pull the new secret from the Key Vault. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"After performing the setup of the scope-management service user, the ","type":"text"},{"text":"user-sync","type":"text","marks":[{"type":"code"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"5. Adding Zitadel Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"ZITADEL Actions are custom scripts that you can define to run at specific points during the authentication and authorization processes. After an action was added, it needs to be used by assigning it to one of the available Trigger Types.","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Currently the following Actions need to be configured (as required).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action: ","type":"text"},{"text":"addGrant","type":"text","marks":[{"type":"code"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" Create a new ","type":"text"},{"text":"addGrant","type":"text","marks":[{"type":"code"}]},{"text":" action ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":514,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":514,"alt":"image-20241119-140109.png","id":"335eb080-58c2-4868-86c6-2644b1cd66a1","collection":"contentId-624164882","type":"file","height":722}}]},{"type":"paragraph","content":[{"text":" Note: add the appropriate roles based on needs","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"function addGrant(ctx, api) {\n api.userGrants.push({\n projectID: '',\n projectGrantID: '',\n roles: ['chat.chat.basic'] // default roles users get\n });\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"addGrant","type":"text","marks":[{"type":"code"}]},{"text":" actions needs to react on the Trigger Type “Post Creation” because we want to add the default roles for the user after creation.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":411,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":411,"alt":"image-20241119-141719.png","id":"f0601a05-5def-4f11-92a2-724a5c079959","collection":"contentId-624164882","type":"file","height":326}},{"type":"caption","content":[{"text":"This action will be triggered every time a user is created","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":" Action: ","type":"text"},{"text":"addUserGroupsMetadataEntra","type":"text","marks":[{"type":"code"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If Entra is used as an IDP, create the action ","type":"text"},{"text":"addUserGroupsMetadataEntra","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":505,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":505,"alt":"image-20241119-141553.png","id":"82483501-3cef-435a-bb0b-186add865a2a","collection":"contentId-624164882","type":"file","height":730}}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"const logger = require(\"zitadel/log\")\nconst http = require('zitadel/http')\n\nfunction addUserGroupsMetadataEntra(ctx, api) {\n logger.log('Writing group info on user metadata.');\n\n const claims = ctx.claimsJSON();\n const parsedGroups = JSON.parse(claims).groups;\n\n // Enable for debugging\n // logger.log('Claims: ' + JSON.stringify(claims));\n // logger.log('Parsed groups: ' + JSON.stringify(parsedGroups));\n\n // Get names with additional call to Graph API\n const batchRequests = [];\n for (const groupId of parsedGroups) {\n batchRequests.push({\n \"id\": groupId,\n \"method\": \"GET\",\n \"url\": `/groups/${groupId}`\n });\n }\n\n const graphApiBatchResponse = http.fetch('https://graph.microsoft.com/v1.0/$batch', {\n method: 'POST',\n headers: {\n \"Authorization\": `Bearer ${ctx.accessToken}`,\n \"Content-Type\": \"application/json\"\n },\n body: {\n requests: batchRequests\n }\n }).json();\n\n const entraGroups = [];\n for (const apiResponse of graphApiBatchResponse.responses) {\n const groupId = apiResponse.id;\n const groupName = apiResponse.body.displayName;\n\n entraGroups.push({\n \"id\": groupId,\n \"displayName\": groupName,\n });\n }\n\n // Check if groups are valid and do not contain empty string values\n if (entraGroups.some(group => group.id === \"\" || group.displayName === \"\")) {\n logger.log('Invalid groups found, skipping metadata update.');\n return;\n }\n\n // append metadata to user\n api.v1.user.appendMetadata(\"groups\", entraGroups);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"After you’ve added the action, you need to assign it to a trigger. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":412,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":412,"alt":"image-20241119-142034.png","id":"58e890d6-4e5d-4ed9-ab1a-dfa194ba7ee9","collection":"contentId-624164882","type":"file","height":332}},{"type":"caption","content":[{"text":"This action will be triggered every time a user logs in via SSO","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action: ","type":"text"},{"text":"addUserGroupsMetadataOidc","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Code:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"const logger = require(\"zitadel/log\")\n\nfunction addUserGroupsMetadataOidc(ctx, api) {\n logger.log('Writing group info on user metadata.');\n\n const claims = ctx.claimsJSON();\n const parsedGroups = JSON.parse(claims).groups;\n\n // Enable for debugging\n // logger.log('Claims: ' + JSON.stringify(claims));\n // logger.log('Parsed groups: ' + JSON.stringify(parsedGroups));\n\n // To sync we need need the external groups' ID and display name\n // Verify how the groups are sent on the ID token and adapt to the desired format.\n let groups = parsedGroups.map(group => {\n return {\n \"id\": group.id,\n \"displayName\": group.displayName,\n };\n });\n\n // Check if groups are valid and do not contain empty string values\n if (groups.some(group => group.id === \"\" || group.displayName === \"\")) {\n logger.log('Invalid groups found, skipping metadata update.');\n return;\n }\n\n // append metadata to user\n api.v1.user.appendMetadata(\"groups\", groups);\n}","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Flow Type:","type":"text","marks":[{"type":"strong"}]},{"text":" External Authentication","type":"text"},{"type":"hardBreak"},{"text":"Trigger Type:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Post Authentication","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Actions:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"addUserGroupsMetadataOidc","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph"},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action: ","type":"text"},{"text":"addMicrosoftUserDataEntra","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Code:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"const http = require('zitadel/http')\n\nfunction addMicrosoftUserDataEntra(ctx, api) {\n\n let country;\n let department;\n const profileApiResponse = http.fetch('https://graph.microsoft.com/v1.0/me?$select=country,department', {\n method: 'GET',\n headers: {\n \"Authorization\": `Bearer ${ctx.accessToken}`,\n \"Content-Type\": \"application/json\"\n }\n }).json();\n\n country = profileApiResponse.country || null;\n department = profileApiResponse.department || null;\n\n api.v1.user.appendMetadata(\"country\", country);\n api.v1.user.appendMetadata(\"department\", department);\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"More fields can be fetched from the Microsoft Graph API: ","type":"text"},{"text":"https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties","type":"text","marks":[{"type":"link","attrs":{"href":"https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties"}}]}]},{"type":"paragraph","content":[{"text":"Flow Type:","type":"text","marks":[{"type":"strong"}]},{"text":" External Authentication","type":"text"},{"type":"hardBreak"},{"text":"Trigger Type:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Post Authentication","type":"text","marks":[{"type":"em"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action: ","type":"text"},{"text":"addUserGroupsMetadataSaml","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Code:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"const logger = require(\"zitadel/log\")\n\nfunction addUserGroupsMetadataSaml(ctx, api) {\n logger.log('Writing group info on user metadata.');\n\n const sentGroups = ctx.v1.providerInfo?.attributes[\"groups\"];\n\n // Enable for debugging\n // logger.log('Parsed groups: ' + JSON.stringify(sentGroups));\n\n // To sync we need need the external groups' ID and display name\n // Verify how the groups are sent on the ID token and adapt to the desired format.\n let groups = sentGroups.map(group => {\n return {\n \"id\": group.id,\n \"displayName\": group.displayName,\n };\n });\n\n // Check if groups are valid and do not contain empty string values\n if (groups.some(group => group.id === \"\" || group.displayName === \"\")) {\n logger.log('Invalid groups found, skipping metadata update.');\n return;\n }\n\n // append metadata to user\n api.v1.user.appendMetadata(\"groups\", groups);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Flow Type:","type":"text","marks":[{"type":"strong"}]},{"text":" External Authentication","type":"text"},{"type":"hardBreak"},{"text":"Trigger Type:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Post Authentication","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Action:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"addUserGroupsMetadataSaml","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"This action needs an additional action:","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action: ","type":"text"},{"text":"prefilRegisterFromSAML","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Code:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"function prefilRegisterFromSAML(ctx, api) {\n\tif (ctx.v1.externalUser?.externalIdpId != \"xxxxxxx\") {\n return\n }\n let firstname = ctx.v1.providerInfo?.attributes[\"GivenName\"];\n let lastname = ctx.v1.providerInfo?.attributes[\"Surname\"];\n let email = ctx.v1.providerInfo?.attributes[\"emailaddress\"];\n \n \n if (firstname) {\n \tapi.setFirstName(firstname[0]);\n }\n if (lastname) {\n\t api.setLastName(lastname[0]);\n }\n if (email) {\n \tapi.setEmail(email[0]);\n\t api.setEmailVerified(true);\n\t api.setPreferredUsername(email[0]);\n }\n} ","type":"text"}]},{"type":"paragraph","content":[{"text":"Flow Type:","type":"text","marks":[{"type":"strong"}]},{"text":" External Authentication","type":"text"},{"type":"hardBreak"},{"text":"Trigger Type:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Post Authentication","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Actions:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"prefilRegisterFromSAML","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"Don’t forget to add the IDP ID in the code above. You will find it in the IDP settings when clicking on the IDP and getting the ID from the URL","type":"text"}]},{"type":"rule"},{"type":"paragraph"},{"type":"paragraph"},{"type":"paragraph"},{"type":"heading","attrs":{"level":1},"content":[{"text":"6. Configuring SSO","type":"text"}]},{"type":"paragraph","content":[{"text":"tbd - work in progress","type":"text"}]},{"type":"rule"},{"type":"table","attrs":{"layout":"default","width":633.0,"localId":"fe348793-08c4-4706-b24a-3f91ef1d96b7"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Author","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[523.0]},"content":[{"type":"paragraph","content":[{"type":"mention","attrs":{"id":"63eb588daf665dfde8905c67","text":"@Sandro Camastral"}},{"text":" ","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported