Before creating new roles, check once for which level/purpose the role is needed
- Company Role
- Portal Role
- App Role
- Technical User Role
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:
- 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:
- create migration
- update "version_upgrade" details open the file
- update Roles&Rights Matrix
Portal roles can get added easily if following steps are considered/followed.
- Create the 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)
- 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".
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.
-
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:
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}');
- Update keycloak base image
The CX-Central realm file needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
- Update documentation
-
Roles&Rights Matrix https://github.com/eclipse-tractusx/portal-iam/docs/static/portal-application-overview.png; or https://github.com/eclipse-tractusx/portal-iam/docs/static/registration-application-overview.png
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 roles are similar like portal user roles created/managed and enhanced by the platform owner.
- Create the roles inside Keycloak - central idp; realm: CX-Central inside the client "technical_role_management"
- open the client via the left side menu Clients
- 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".
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.
- 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:
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
INSERT INTO portal.user_role_descriptions
(user_role_id, language_short_name, description)
VALUES
('(user_roles.id)', '{de}', '{description}'),
('(user_roles.id)', '{en}', '{description}');
- Update Keycloak base image
The CX-Central realm file needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
- Update documentation
In the concept of the roles and rights management we are differentiating between roles and permissions.
Permissions are the lowest level which a user can have. Several permissions are collected to a role.
The assignment of rights to an actual user is happening on the role level itself.
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.
-
Create the respective OIDC client, with respective setting
- Access Type: confidential
- Standard Flow: disabled
- Direct Access Grant: disabled
- Service Accounts: enabled
- Add Mapper "BPN" to the user
- 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
After saving the config, the client gets automatically a service user account created which is used as "technical user"
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}'
This work is licensed under the Apache-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