Configure users

For certain capabilities the IBM Industry Solutions Workbench relies also on functions that are available through the OpenShift web console. Therefore, it might also be necessary to set up users in OpenShift despite the common setup of users in an OIDC-compliant Identity Provider (e.g. Keycloak).

Note:

The authentication mechanism of deployed projects is only dependent on OIDC-compliant Identity Provider settings.

Overview

IBM Industry Solutions Workbench users:

These users are typically involved in the design and development process of a project. They are mainly configured in the attached Identity and Access Management system (IAM), that also serves as the main OIDC-compliant Identity Provider. For configuring system users, please see IAM user configuration and the underlying user role model.

OpenShift users:

Some capabilities of IBM Industry Solutions Workbench also require that users, that are involved in the process of developing projects, also need certain permissions on dedicated OpenShift namespaces. For configurations in the OpenShift cluster please see OpenShift User Configuration.

End users of deployed projects:

These users are able to call the published API operations of a deployed project. They are mainly configured in the attached Identity and Access Management system (IAM), respectively Keycloak, that also serves as the main OIDC-compliant Identity Provider. For configuring users, please see IAM user configuration.

IAM user configuration

This configuration is done in the admin area of your IAM provider.

Prerequisites

A user with admin rights for the IAM provider.

Realm model

A realm manages a set of users, credentials, and roles. A user always belongs to a realm. So realms are isolated from one another. We differentiate between two kinds of realms:

One is needed for the Solution Designer and Solution Hub components
One is needed for each k5-project So if you have three k5-projects in place, you could have configured and use up to four realms. It's also possible to use only one realm for the Solution Designer and Solution Hub components and one for every k5-project. That would be useful if all users should have access to all components and all running projects within the k5-projects for example.

Create new users

Open your IAM provider's admin console, e.g. https://identity.apps.openshift-01.example.cloud
Choose a realm
Open Users -> Add user
Input parameters are
- Username
- Email
- First Name
- Last Name
Save the new user

Note:

The email address is necessary for the GitLab/IAM integration to work.

Set user's initial password

Open the created user
Go to Credentials
Create initial New Password and confirm it
Activate flag Temporary, so that the user has to change the password with the first login
Press Reset Password

Assign roles to users

Go to Role Mappings
Select necessary Available Roles
Press Add selected > to assign the roles (see User role model)

User role model

Warning:

The roles and permissions used in IBM Industry Solutions Workbench are a combination of the user role itself and the permissions in the corresponding Git repository. So in any case check also the permissions set in the Git repository.

To access any project handled by IBM Industry Solutions Workbench you will need to set up a Git access token that has at least read rights for the repositories you want to work on and store it in your user settings. The permissions of this Git user will be used to define what this user is allowed to do in Solution Designer or Solution Hub. On top of the Git permissions there are some permissions based on the user role set in IBM Industry Solutions Workbench.

The roles are completely independent of each other, that means you will in any case need at least the role dc_user to access either Solution Designer or Solution Hub. Then you add the roles according to your role in the team and the actions you need to perform.

Example: To create a new user in the role of a business analyst you need to assign the dc_user and the dc_analyst role.

Roles overview


Name	Description
`dc_user`	Minimum permissions to access Solution Designer and its local marketplace. Can also create and delete projects if this user has the Git permissions to create and delete projects.
`dc_developer`	Acts as a CLI user and source code developer inside Solution Designer. Will be able to pull and push code to a project related repository.
`dc_analyst`	Is allowed to edit projects and to make changes to the design model (Domain Service Projects). Git write permission also needed to alter projects.
`dc_admin`	Acts as an admin user for Solution Designer. Has the permissions to read and delete projects from Solution Designer. In addition, this role maintains the Git repositories and the pipelines.
`tm_admin`	Can view or alter values in the configuration management that are related to Kafka- or event topic bindings.
`cm_admin`	Acts as an admin user for the configuration management in Solution Hub. A user with this role has the permission to use all APIs in the Solution Hub.
`sr-admin`	Acts as an admin user who has full access to schema registry.
`sr-developer`	Acts as a developer user who can create, read, update, and delete operations in schema registry, except configuring global rules.
`sr-readonly`	Acts as a readonly user who has only access to read and search operations in schema registry.

Permissions

Solution Designer roles

dc_user:

This is the minimum required role to access Solution Designer or Solution Hub and should be added to every user of IBM Industry Solutions Workbench. The role itself doesn't let the user delete projects but depending on the Git permissions this role may have the right to also delete Git repositories and therefore has the right to delete projects also in IBM Industry Solutions Workbench .

dc_developer:

This role is intended for the developers in your team and adds permissions to work with the Solution CLI and to push and pull implementation code to the Git repository. Pushing code to the repository also requires write permissions in the corresponding Git repository. Furthermore, this role adds permissions to "Commit" changes on application composition projects to the Git repository.

Additionally, this role is permitted to:

add, edit or delete Paths, Operations including the associated Parameters, Request Bodies and Responses in existing API Namespaces
add, edit or delete Commands and Schemas to root entities in existing Domain Namespaces
add, edit or delete API Dependencies in existing Integration Namespaces
edit the Documentation sections in a project

Note:

This role should also have write permissions in the corresponding Git repository to be able to perform the intended tasks.

dc_analyst:

This role is intended for the Business Expert/Analyst of your team and allows modelling inside Domain Service Projects. It adds permissions to "Commit" changes on application composition projects to the Git repository.

Additionally, this role is permitted to:

Write comments
add, edit or delete any type of namespace within Domain Service Project
create, edit or delete database collections
edit the Documentation sections in a project

Note:

This role should also have write permissions in the corresponding Git repository to be able to perform the intended tasks.

dc_admin:

The dc_admin is the admin role inside Solution Designer and has all permissions included in the previous roles.

Warning:

In case a user with dc_admin privileges deletes a project within Solution Designer without having the permissions in the connected Git repository, the related Git project has to be deleted manually at the remote Git provider.

mp_user:

This role is needed to export projects to the local marketplace to make them available for other users to import as project template.

mp_manager:

The mp_manager role is intended to administer the local marketplace and has the permission to delete project templates from the marketplace.

Solution Hub roles

tm_admin:

Required for managing event topic bindings and creating new event topics on Kafka brokers (depending on broker configuration)

cm_admin:

This role is required to access the deployment target configurations and the runtime configurations for single service deployments. It has also permissions to manage Kafka- and event topic bindings and any other feature inside Solution Hub.

Schema Registry roles

sr-admin:

This role is required to have full access to all create, read, update, and delete operations in schema registry.

sr-developer:

This role grants access to create, read, update, and delete operations, except configuring global rules in schema registry. This role can configure artifact rules.

sr-readonly:

This role grants access in schema registry to read and search operations only. This role cannot configure any rules.

OpenShift users configuration

This configuration is done in the RedHat OpenShift cluster. It enables the users to use the integrated capabilities that are provided by the OpenShift console without restrictions.

Show pipelines and pipeline runs

Within Solution Designer, the user is provided with some links to directly access the shown artifact in the OpenShift web console. These links will only work, if the user can log in to the OpenShift web console and has the necessary permissions on the OpenShift cluster. To show pipelines and the pipeline runs including the logs, it is required that a user has the following permission set:

rules:
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - tekton.dev
    resources:
      - tasks
      - taskruns
      - pipelines
      - pipelineruns
      - pipelineresources
      - conditions

The permissions only need to be granted to users in those projects, that are stuffed with a k5-project and where projects will get deployed.

Show topology, pods and logs

In order to view the application composition using the Topology view, a user needs at least the following permission set:

rules:
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - ''
    resources:
      - pods
      - pods/log
      - pods/status
      - replicationcontrollers
      - services
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - apps.openshift.io
    resources:
      - deploymentconfigs
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - apps
    resources:
      - deployments
      - daemonsets
      - replicasets
      - statefulsets
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - route.openshift.io
    resources:
      - routes
  - verbs:
      - get
      - list
      - watch
    apiGroups:
      - build.openshift.io
    resources:
      - buildconfigs
      - builds

The permissions only need to be granted to users in those projects, that are stuffed with a k5-project and where projects will get deployed.

Example configuration / recommendation

Note:

We recommend grouping users in groups. Instead of defining extra roles for topology view and/or pipeline artifacts, one can also use the predefined cluster-role view.

oc adm policy add-user-to-role view username

Tip:

Permissions can be granted cluster-wide or on a per-project basis. For security reasons, we recommend to grant only the least minimal necessary permission set to users.