-
Notifications
You must be signed in to change notification settings - Fork 16
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: updated faq due to keycloak process change #180
base: main
Are you sure you want to change the base?
Changes from all commits
96202d7
9830d5d
03264c7
53d0015
dc59bfb
dba5b47
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 | ||
|
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 | ||
|
||
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Might be better to remove the way via sql entirely as that makes it seem as we somehow suggest that but from a good practice point of view, we should only propagate the way via updating the portal seeding data, which here is called delta migration job as that the only sustainable way, via sql might be useful for a short test but nothing else |
||
|
||
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 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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might be better to remove the way via sql entirely as that makes it seem as we somehow suggest that but from a good practice point of view, we should only propagate the way via updating the portal seeding data, which here is called
delta migration job
as that the only sustainable way, via sql might be useful for a short test but nothing else