Skip to content

Latest commit

 

History

History
160 lines (103 loc) · 7.11 KB

11. FAQ.md

File metadata and controls

160 lines (103 loc) · 7.11 KB

FAQ

How to create 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.

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

2. Additionally needed

3. Update documentation for company role(s)

Portal Role(s)

Portal roles can get added easily if following steps are executed.

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)
  • 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;

  • Go to Action
  • click Add associated roles
  • select the role(s) you want to add
  • press Assign

2. 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 seeding.

3. Portal DB changes for composite roles

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 for business role(s)

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 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 convention)
  • Click Save

To transform the created "role" to a composite role, since currently its a single permission only;

  • Go to Action
  • click Add associated roles
  • select the role(s) you want to add
  • press Assign

2. 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 seeding.

3. Portal DB changes for composite roles

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 for technical role(s)

What is the difference between roles & permission

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

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

    Bpn

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

NOTICE

This work is licensed under the Apache-2.0.