diff --git a/docs/static/new_user_get_uuid.png b/docs/static/new_user_get_uuid.png new file mode 100644 index 00000000..8597383e Binary files /dev/null and b/docs/static/new_user_get_uuid.png differ diff --git a/docs/static/new_user_get_uuid.png.license b/docs/static/new_user_get_uuid.png.license new file mode 100644 index 00000000..d8f89abc --- /dev/null +++ b/docs/static/new_user_get_uuid.png.license @@ -0,0 +1,6 @@ +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: Copyright (c) 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-iam + diff --git a/docs/technical documentation/11. FAQ.md b/docs/technical documentation/11. FAQ.md index c8140fa5..6912fb35 100644 --- a/docs/technical documentation/11. FAQ.md +++ b/docs/technical documentation/11. FAQ.md @@ -1,6 +1,6 @@ # FAQ -## How to crete new roles +## How to create new roles Before creating new roles, check once for which level/purpose the role is needed @@ -14,129 +14,183 @@ Before creating new roles, check once for which level/purpose the role is needed To add a new company role, a couple of steps need to get followed. Different to Portal/App/Technical User Roles, it is not needed to do any update inside the IdP. -DB Table Changes: +#### 1. DB Table Changes -- add new company role inside the table company_roles -- if the new company role should be selectable for company registrations, set the role inside table company_role_registration_data to "true"; otherwise "false" -- add description of the new company role inside table company_role_descriptions -- create a new user role collection inside user_role_collections to define selectable user roles for the company role -- add description of the new collection inside table user_role_collection_descriptions -- map user roles to the new created collection via table user_role_assigned_collections -- connect the new company role with the new role collection via "company_role_assigned_role_collections" -- new or existing agreements to be linked to the new company role via table "agreement_assigned_company_roles" +- add new company role inside the table `company_roles` +- if the new company role should be selectable for company registrations, set the role inside table `company_role_registration_data` to `true`; otherwise `false` +- add description of the new company role inside table `company_role_descriptions` +- create a new user role collection inside `user_role_collections` to define selectable user roles for the company role +- add description of the new collection inside table `user_role_collection_descriptions` +- map user roles to the new created collection via table `user_role_assigned_collections` +- connect the new company role with the new role collection via `company_role_assigned_role_collections` +- new or existing agreements to be linked to the new company role via table `agreement_assigned_company_roles` -Additionally needed: +#### 2. Additionally needed - create migration -- update "version_upgrade" details [open the file](https://github.com/eclipse-tractusx/portal-assets/blob/v1.6.1/developer/Technical%20Documentation/Version%20Upgrade/portal-upgrade-details.md) -- update Roles&Rights Matrix +- update `version_upgrade` details [open the file](https://github.com/eclipse-tractusx/portal-assets/blob/v1.6.1/developer/Technical%20Documentation/Version%20Upgrade/portal-upgrade-details.md) + +#### 3. Update documentation for company role(s) + +- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application) ### Portal Role(s) -Portal roles can get added easily if following steps are considered/followed. +Portal roles can get added easily if following steps are executed. -1. Create the roles inside keycloak - central idp; realm: CX-Central inside the respective client +#### 1. Create the business roles inside keycloak - central idp; realm: CX-Central inside the respective client - open the client via the left side menu **Clients** -- select the respective client (Cl2-CX-Portal or Cl1-CX-Registration) +- select the respective client (`Cl2-CX-Portal` or `Cl1-CX-Registration`) - Open the tab **Roles** -- And click "Add" on the right hand side +- And click **Add** on the right hand side - Enter the respective role name (keep in mind the role naming conversation) -- Click **"Save"** +- Click **"Save** -To transform the created "role" to an actual role, since currently its a single permission only; click on **Composite Roles** "ON". +To transform the created "role" to an actual role, since currently its a single permission only; - ![CompositeRoles](/docs/static/composite-roles.png) - - Afterwards select the respective permissions which should get collected under the new created role/composite role by selecting the client in which the relevant permissions are located. - Note: permissions of multiple clients can get assigned to one composite role without any troubles/issues. +- Go to **Action** +- click **Add associated roles** +- select the role(s) you want to add +- press **Assign** - ![ClientRoles](/docs/static/client-roles.png) - -2. Create the same role inside the portal db (either via a delta migration job) or via sql. +#### 2. Create the business role inside the portal db (either via a delta migration job) or via sql + +For the scenario of sql, the relevant sql can get found below: - For the scenario of sql, the relevant sql can get found below: +1st to get the role id move into your browser open the user role configuration and copy the second UUID from the url. - 1st create the role - - INSERT INTO portal.user_roles - (id, user_role, offer_id, last_editor_id) - VALUES ('{uuid}', '{user role name}', '{offer.id of portal or registration}', '{operator user uuid}'); + ![ClientRoles](/docs/static/new_user_get_uuid.png) -2nd add role description in german and english +2nd create the role - INSERT INTO portal.user_role_descriptions - (user_role_id, language_short_name, description) - VALUES - ('(user_roles.id)', '{de}', '{description}'), - ('(user_roles.id)', '{en}', '{description}'); +```sql +INSERT INTO portal.user_roles( +id, user_role, offer_id, last_editor_id) +VALUES ('copied uuid from url', 'Name of your Keycloak Role', 'offerID of portal or registration', null); +``` -3rd connect role with company role collection +3rd add role description in german and english - INSERT INTO portal.user_role_assigned_collections - (user_role_id, user_role_collection_id) - VALUES ('{user_roles.id}', '{user_role_collections.id}'); +```sql +INSERT INTO portal.user_role_descriptions +(user_role_id, language_short_name, description) +VALUES +('(user_roles.id)', '{de}', '{description}'), +('(user_roles.id)', '{en}', '{description}'); +``` -3. Update keycloak base image +4th connect role with company role collection. + +get the id for the user role collection from the following sql. + +```sql +SELECT CR.label, CRARC.user_role_collection_id +FROM portal.company_role_assigned_role_collections as CRARC +JOIN portal.company_roles as CR on id = company_role_id; +``` + +copy the necessary id and execute the INSERT statement with it. + +```sql +INSERT INTO portal.user_role_assigned_collections( +user_role_id, user_role_collection_id) +VALUES ('copied uuid from url', 'copied user_role_collection_id from query'); +``` + +#### 3. Update keycloak base image The [CX-Central realm file](../../import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding. -4. Update documentation +#### 4. Update documentation for business role(s) - [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application) ### App Role(s) -App roles are managed by app provider by the portal user interface. It should be strictly forbidden to add / change any app roles in any other way. Reason: app roles are (beside that they are in the ownership of the app provider) impacting not only a Keycloak client and portal db; additionally apps have app clients registered in Keycloak and each client need to get enhanced with the new roles where human errors are very likely possible. +App roles are managed by app provider by the portal user interface. + +**It should be strictly forbidden to add / change any app roles in any other way.** + +>**_Reason:_** +>app roles are (beside that they are in the ownership of the app provider) impacting not only a Keycloak client and portal db; additionally apps have app clients registered in Keycloak and each client need to get enhanced with the new roles where human errors are very likely possible. ### Technical User Role(s) Technical user roles are similar like portal user roles created/managed and enhanced by the platform owner. -1. Create the roles inside Keycloak - central idp; realm: CX-Central inside the client "technical_role_management" +#### 1. Create the technical roles inside keycloak - central idp; realm: CX-Central inside the respective client - open the client via the left side menu **Clients** +- select the respective client (`technical_roles_management`) - Open the tab **Roles** -- And click "Add" on the right hand side -- Enter the respective role name (keep in mind the role naming conversation) -- Click **"Save"** +- And click **Add** on the right hand side +- Enter the respective role name (_keep in mind the role naming convention_) +- Click **Save** -To transform the created "role" to an actual role, since currently its a single permission only; click on **Composite Roles** "ON". +To transform the created "role" to an actual role, since currently its a single permission only; - ![CompositeRoles](/docs/static/composite-roles.png) - - Afterwards select the respective permissions which should get collected under the new created role/composite role by selecting the client in which the relevant permissions are located. - Note: permissions of multiple clients can get assigned to one composite role without any troubles/issues. +- Go to **Action** +- click **Add associated roles** +- select the role(s) you want to add +- press **Assign** - ![ClientRoles](/docs/static/client-roles.png) +#### 2. Create the technical role inside the portal db (either via a delta migration job) or via sql -2. Create the same role inside the portal db (either via a delta migration job) or via sql. +- Go to **Action** +- click **Add associated roles** +- select the role(s) you want to add +- press **Assign** For the scenario of sql, the relevant sql can get found below: - - 1st create the role - - INSERT INTO portal.user_roles - (id, user_role, offer_id, last_editor_id) - VALUES ('{uuid}', '{user role name}', '{offer.id of technical_user_management}', '{operator user uuid}'); -2nd add role description in german and english +1st to get the role id move into your browser open the user role configuration and copy the second UUID from the url. + + ![ClientRoles](/docs/static/new_user_get_uuid.png) + +2nd create the role + +```sql +INSERT INTO portal.user_roles( +id, user_role, offer_id, last_editor_id) +VALUES ('copied uuid from url', 'Name of your Keycloak Role', 'offerID of Technical User Management', null); +``` + +3rd add role description in german and english - INSERT INTO portal.user_role_descriptions - (user_role_id, language_short_name, description) - VALUES - ('(user_roles.id)', '{de}', '{description}'), - ('(user_roles.id)', '{en}', '{description}'); +```sql +INSERT INTO portal.user_role_descriptions +(user_role_id, language_short_name, description) +VALUES +('(user_roles.id)', '{de}', '{description}'), +('(user_roles.id)', '{en}', '{description}'); +``` -3. Update Keycloak base image +4th connect role with company role collection. + +get the id for the user role collection from the following sql. + +```sql +SELECT CR.label, CRARC.user_role_collection_id +FROM portal.company_role_assigned_role_collections as CRARC +JOIN portal.company_roles as CR on id = company_role_id; +``` + +copy the necessary id and execute the INSERT statement with it. + +```sql +INSERT INTO portal.user_role_assigned_collections( +user_role_id, user_role_collection_id) +VALUES ('copied uuid from url', 'copied user_role_collection_id from query'); +``` + +#### 3. Update keycloak base image The [CX-Central realm file](../../import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding. -4. Update documentation +#### 4. Update documentation for technical role(s) -- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253b-technical-user-accounts) - -- [Technical User Creation - End User documentation]([/docs/technical%20documentation/04%20User%20Management.md](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/03.%20User%20Management/03.%20Technical%20User/02.%20Create%20Technical%20User.md#available-technical-user-roles)) +- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application) ## What is the difference between roles & permission @@ -154,7 +208,7 @@ This is covered in the OAuth 2.0 specification under Client Credentials Grant. T In tab Service Account Roles you can configure the roles available to the service account retrieved on behalf of this client. -https://github.com/keycloak/keycloak-documentation/blob/main/server_admin/topics/clients/oidc/service-accounts.adoc + - Create the respective OIDC client, with respective setting @@ -166,18 +220,20 @@ https://github.com/keycloak/keycloak-documentation/blob/main/server_admin/topics ![Bpn](/docs/static/bpn.png) - - Add a bpn into the user account 8when using the existing api endpoints; the bon is added automatically based on the company bpn of the acting user + - Add a bpn into the user account when using the existing api endpoints; the bpn is added automatically based on the company bpn of the acting user After saving the config, the client gets automatically a service user account created which is used as "technical user" ## Retrieve token for service account - curl --location --request POST '{Keycloak URL}/auth/realms/{realm}/protocol/openid-connect/token' \ - --header 'Content-Type: application/x-www-form-urlencoded' \ - --data-urlencode 'client_secret={secret} \ - --data-urlencode 'grant_type=client_credentials' \ - --data-urlencode 'scope=openid' \ - --data-urlencode 'client_id={clientId}' +```text +curl --location --request POST '{Keycloak URL}/auth/realms/{realm}/protocol/openid-connect/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_secret={secret} \ +--data-urlencode 'grant_type=client_credentials' \ +--data-urlencode 'scope=openid' \ +--data-urlencode 'client_id={clientId}' +``` ## NOTICE @@ -185,4 +241,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC - SPDX-License-Identifier: Apache-2.0 - SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/portal-iam +- Source URL: