docs: updated faq due to keycloak process change

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
+

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
+<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,23 +220,25 @@ 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 bon 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
 
 This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
 
 - 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: <https://github.com/eclipse-tractusx/portal-iam>