Managing user roles

After configuring access to your Event Endpoint Management instance, you must specify roles for your users to determine their permissions.

Event Endpoint Management supports the following roles:

  • viewer: Assigns users viewer access to the Event Endpoint Management UI and shared resources
  • author: Assigns users viewer access to the Event Endpoint Management UI and shared resources. This role also gives users permissions to create and share their own resources.

Note: You must assign at least one of these roles to each user.

You can set up authorization in one of the following ways:

  1. Assign each user their roles individually.
  2. If using an OIDC provider for authentication, define mappings to custom roles in your OIDC provider.

Assigning roles to users

Users are assigned roles in Event Endpoint Management through user mapping, where an identifier for the user or a group of users is mapped to a role or set of roles. The mappings are defined in a configuration file that is exposed through the Kubernetes secret <custom-resource-name>-ibm-eem-user-roles. By default, this file requires separate mapping information for each user.

The following example shows a user mappings file:

{
  "mappings": [
    {
      "id": "author1",
      "roles": [
        "author"
      ]
    },
    {
      "id": "viewer1",
      "roles": [
        "viewer"
      ]
    }
  ]
}

Using OpenShift Container Platform web console

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand Workloads in the navigation on the left and click Secrets. This lists the secrets available in this project (namespace).
  3. To edit the secret <custom-resource-name>-ibm-eem-user-roles with your role mappings, go to Actions, and click Edit Secret.
  4. Edit the mappings, as described in the setting up roles per user or setting up roles by using a custom identifier sections depending on your use case.
  5. Click Save.

Using the CLI

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. Create a JSON file called myroles.json that contains the user role mappings for your Event Endpoint Management instance as described in the setting up roles per user or setting up roles by using a custom identifier sections depending on your use case.

  3. Obtain the Base64-encoded string representing the file content. For example, you can run the following command to obtain the string:

    cat myroles.json | base64

  4. Patch the <custom-resource-name>-ibm-eem-user-roles secret with the local user credentials by running the following command:

    kubectl patch secret <custom-resource-name>-ibm-eem-user-roles --type='json' -p='[{"op" : "replace" ,"path" : "/data/user-mapping.json" ,"value" : "<your-Base64-value>"}]'

    Where:

    • <custom-resource-name> is the name of your Event Endpoint Management instance.
    • <your-Base64-value> is the Base64-encoded string returned from the previous command.

    For example:

    kubectl patch secret quick-start-manager-ibm-eem-user-roles --type='json' -p='[{"op" : "replace" ,"path" : "/data/user-mapping.json" ,"value" : "ewogICJtYXBwaW5ncyI6IFsKICAgIHsKICAgICAgImlkIjogImF1dGhvcjEiLAogICAgICAicm9sZXMiOiBbCiAgICAgICAgImF1dGhvciIKICAgICAgXQogICAgfSwKICAgIHsKICAgICAgImlkIjogInZpZXdlcjEiLAogICAgICAicm9sZXMiOiBbCiAgICAgICAgInZpZXdlciIKICAgICAgXQogICAgfQogIF0KfQo="}]'

    Note: Alternatively, edit the secret directly and replace the Base64 value associated with data.user-mapping.json. To edit the secret directly, run the following command:

    kubectl edit secret/<custom-resource-name>-ibm-eem-user-roles -o json
  5. Important: For security reasons, delete the local file you created.

Note: The changed configuration file is automatically picked up by the Event Endpoint Management instance after a few minutes.

Setting up roles per user

This is the default set up, where the id in the mappings file is the unique identifier of the user:

  • When using local authentication, it is the username for the user as set in the <custom-resource-name>-ibm-eem-user-credentials secret (for more information, see managing access).

  • When using OIDC-based authentication, it is the user’s subject. You can retrieve this either directly from your OIDC provider, or by logging in to the Event Endpoint Management UI and setting the path to /auth/protected/userinfo in the URL.

The following example shows a user mappings file:

"mappings": [
    {
    "id": "author1",
    "roles": [
      "author"
    ]
  }
    ]

Setting up roles by using a custom identifier

Using a custom identifier is a more advanced configuration only available with OIDC-based authentication. It means you can map users to their roles through a custom property (claim) associated with the user in the configured OIDC provider.

To use a custom identifier, you must configure your Event Endpoint Management instance to set where it can find the property to use for the mapping. During log in, Event Endpoint Management checks for the configured property in the user information received from the OIDC provider in the following order:

  1. ID token
  2. Access Token
  3. User Info

Note: If the property is not found, Event Endpoint Management will attempt to map the user directly by using their subject (as mentioned in setting up roles per user).

To configure the custom property (claim) to use, set the authorizationClaimPointer and the additionalScopes fields in the spec.manager.authConfig.oidcConfig section of your EventEndpointManagement custom resource:

apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
# ...
spec:
  # ...
  manager:
    authConfig:
      authType: OIDC
      oidcConfig:
     # ...
        authorizationClaimPointer: <required "/" separated JSON path to the location of the required property>
        additionalScopes: <optional additional scopes to be requested during OIDC-based authentication to retrieve additional properties>
#...

Note: The property being mapped must either be a string or a list of strings.

Example configuration

The following example describes how to set up roles for a custom identifier called developer.

An OIDC provider always provides an ID token, but you might receive additional data from the provider, and you can use this data for mapping user roles to the roles in Event Endpoint Management.

The OIDC provider might store additional user information that can be returned to the client (in this case, Event Endpoint Management) if the client asks for it by requesting the appropriate scope.

For example, the provider supports a data scope which returns the following additional user information when requested:

{
  "data": {
    "group": "test",
    "roles": ["developer", "manager"]
  }
}

With a single mapping in the user mappings file, you can assign viewer access to Event Endpoint Management for all users that have the developer role (the custom identifier as listed in the roles field of the updated ID token).

Complete the following steps to assign access:

  1. Configure Event Endpoint Management to request this additional user information by adding the mentioned data scope to the additionalScopes field in your EventEndpointManagement custom resource:

    additionalScopes: ["data"]

    This setting means that the next time the user logs in, their ID token will also include the additional information from data:

    {
  "sub": "user-xyz-123",
  "name": "xyz-123",
  "data": {
    "group": "test",
    "roles": ["developer", "manager"]
},
...
"exp": 123456
}

  2. Add the path to the required property (in this example, /data/roles) to the authorizationClaimPointer field in the EventEndpointManagement custom resource as follows:

    authorizationClaimPointer: /data/roles

  3. Update the role mappings file as follows to map the developer role as an id to have the Event Endpoint Management viewer role:

    {
  "mappings": [
    {
      "id": "developer",
      "roles": [
        "viewer"
      ]
    }
  ]
}

    This instructs Event Endpoint Management to look inside the ID token for the value at /data/roles, and it will then be able to map the developer role in the OIDC provider to the viewer role in Event Endpoint Management by using the mappings file.

    This means that any user who is known to the OIDC provider and has the developer role will be able to use Event Endpoint Management.

Note: Event Endpoint Management checks multiple sources for the configured property. If it does not find the /data/roles field in the ID token, it will check for it next in the Access Token, then finally it will check in the response to the User Info API, which is available in all OIDC providers. Event Endpoint Management uses the value from the first match. If no match is found, it defaults to checking for the user’s subject directly in the mappings file.

Retrieving roles for the Admin API

When using the Event Endpoint Management Admin API, the access token for the API has the same permissions as the user who created it.

If you have set up roles per user, the permissions are assigned by using the same role mappings file as mentioned earlier without any additional configuration. However, instead of mapping information from the OIDC log in flow, the role is mapped by using the owner of the token.

Important: If you have set up roles by using a custom identifier, additional configuration is required to ensure Admin API users have the expected permissions. This is because to map users to roles, a custom property in OIDC is used instead of the unique user subject (the owner of the token).

Event Endpoint Management supports the use of the OIDC scope offline_access, and you can configure Event Endpoint Management to request this additional property by adding the offline_access scope to additionalScopes in your EventEndpointManagement custom resource:

additionalScopes: ["offline_access"]

The offline_access scope allows Event Endpoint Management to refresh user information and retrieve up-to-date ID and Access tokens for users previously logged in to the Event Endpoint Management UI (even when they are no longer logged in to the UI).

These tokens are then used to perform user mapping as described earlier, assigning the correct permissions to the token being used.

Important: Some OIDC providers allow the length of time before offline access expires to be configured. In such cases, the offline access might expire before the Event Endpoint Management token expires. If this happens, the user will have to log back in to the UI to enable Event Endpoint Management to refresh offline access.

Note: Not all OIDC providers support the offline_access scope. Also, you might not want to give Event Endpoint Management permission to perform offline access. In either of these cases, to continue to use the Admin API, reference each user individually in the user mappings file.