Skip to content

Latest commit

 

History

History
192 lines (123 loc) · 8.89 KB

File metadata and controls

192 lines (123 loc) · 8.89 KB

FAQ

How to crete new roles

Before creating new roles, check once for which level/purpose the role is needed

  1. Company Role
  2. Portal Role
  3. App Role
  4. Technical User Role

Company Role(s)

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 Role(s)

Portal roles can get added easily if following steps are considered/followed.

  1. 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".

CompositeRoles

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

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

  1. Update documentation

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.

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"
  • 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".

CompositeRoles

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

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

  1. Update documentation

What is the difference between roles & permission

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.

How to setup technical user authentication

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
    • Standard Flow: disabled
    • Direct Access Grant: disabled
    • Service Accounts: enabled
    • Add Mapper "BPN" to the user

    Bpn

    • 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"

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

NOTICE

This work is licensed under the Apache-2.0.