Skip to content

Commit

Permalink
docs: updated faq due to keycloak process change (#180)
Browse files Browse the repository at this point in the history 
* docs: updated faq due to keycloak process change

---------

Co-authored-by: Phil Schneider <[email protected]>
Co-authored-by: Evelyn Gurschler <[email protected]>
  • Loading branch information
@MaximilianHauer @Phil91 @evegufy
3 people authored Nov 28, 2024
1 parent 537bfe8 commit 7f5075a
Show file tree
Hide file tree
Showing 3 changed files with 72 additions and 95 deletions.
161 changes: 66 additions & 95 deletions docs/admin/technical-documentation/11. FAQ.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -14,125 +14,96 @@ 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. Portal 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`](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/admin/Version%20Upgrade), if necessary

#### 3. Update documentation for company role(s)

- [Roles&Rights Matrix](/docs/admin/technical-documentation/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 - centralidp; 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.

For the scenario of sql, the relevant sql can get found below:
#### 2. Update keycloak base image

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}');

2nd 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}');

3rd connect role with company role collection

INSERT INTO portal.user_role_assigned_collections
(user_role_id, user_role_collection_id)
VALUES ('{user_roles.id}', '{user_role_collections.id}');
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 seeding.

3. Update keycloak base image
#### 3. Portal DB changes for composite roles

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 seeding.
It is only possible to assign the new technical user role via the technical user administration of the portal if it is also added to the portal database.

4. Update documentation
#### 4. Update documentation for business role(s)

- [Roles&Rights Matrix](/docs/admin/technical-documentation/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 - centralidp; 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"**

To transform the created "role" to an actual role, since currently its a single permission only; click on **Composite Roles** "ON".

![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.

![ClientRoles](/docs/static/client-roles.png)
- And click **Add** on the right hand side
- Enter the respective role name (_keep in mind the role naming convention_)
- Click **Save**

2. Create the same role inside the portal db (either via a delta migration job) or via sql.
To transform the created "role" to a composite role, since currently its a single permission only;

For the scenario of sql, the relevant sql can get found below:

1st create the role
- Go to **Action**
- click **Add associated roles**
- select the role(s) you want to add
- press **Assign**

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
#### 2. Update keycloak base image

INSERT INTO portal.user_role_descriptions
(user_role_id, language_short_name, description)
VALUES
('(user_roles.id)', '{de}', '{description}'),
('(user_roles.id)', '{en}', '{description}');
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 seeding.

3. Update Keycloak base image
#### 3. Portal DB changes for composite roles

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 seeding.
It is only possible to assign the new technical user role via the technical user administration of the portal if it is also added to the portal database.

4. Update documentation
#### 4. Update documentation for technical role(s)

- [Roles&Rights Matrix](/docs/admin/technical-documentation/06.%20Roles%20&%20Rights%20Concept.md#253b-technical-user-accounts)

Expand All @@ -141,22 +112,20 @@ The [CX-Central realm file](/import/realm-config/generic/catenax-central/CX-Cent

## What is the difference between roles & permission

In the concept of the roles and rights management we are differentiating between roles and permissions.
In the concept of the roles and rights management we are differentiating between `composite roles` and `roles`.

Permissions are the lowest level which a user can have. Several permissions are collected to a role.
`Roles` are the lowest level which a user can have. Several `roles` are collected to a `composite role`.

The assignment of rights to an actual user is happening on the role level itself.
The assignment of rights to an actual user is happening on the `composite role` level itself.

## How to setup technical user authentication

Technical user/service accounts should get created as standalone client to clearly differentiate applications from technical users.
Technical user/service accounts should get created as standalone client to clearly differentiate applications from technical users.
Each OIDC client has a built-in service account which allows it to obtain an access token.
This is covered in the OAuth 2.0 specification under Client Credentials Grant. To use this feature you must set the Access Type of your client to confidential. Make sure that you have configured your client credentials.

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

- Access Type: confidential
Expand All @@ -167,23 +136,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 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

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>
Binary file added docs/static/new_user_get_uuid.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions docs/static/new_user_get_uuid.png.license
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 7f5075a

Please sign in to comment.