Managing user groups

In Event Endpoint Management 11.6.3 and later, after you configure access to your Event Manager instance, you can configure Event Endpoint Management to access and utilize user groups that are provided by an external identity provider. This means that Event Endpoint Management can recognize and manage the user groups that are established by your organization’s administrators to control visibility to Event Endpoint Management components such as options.

Note: Access to user groups is available with OpenID Connect (OIDC) authentication only.

Accessing user groups

You can set up access to user groups by using a custom identifier. To use a custom identifier, you must configure your Event Manager instance to set where it can find the groups property. During login, Event Endpoint Management checks for the configured property in the user information received from the OIDC provider in the following order:

ID token
Access Token
User Info

To configure the custom property (claim) to use, set the userGroupClaimPointer. If required, set 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:
     # ...
        userGroupClaimPointer: <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 that you use must refer to a string or a list of strings. Do not use forward slashes (/) in the property names. Forward slashes are used as a JSON path separator, but will fail to work correctly if present in a property name.

To configure the userGroupClaimPointer field, use the /auth/protected/userinfo endpoint to view all attributes determined about you from your login, ID token, access token (if it is a JWT), or user information endpoint. Set the URL path to /auth/protected/userinfo to display these attributes, which helps you configure the userGroupClaimPointer field correctly.

Determine the required path from the source that you are interested in. For example, consider the following /auth/protected/userinfo response:

{
  ...
  "attributes": {
    "idToken": {
      "data": {
        "roles": ["my-role"]
      }
    },
    "accessToken": {
      "groups": ["my-group"]
    },
    "userInfo": {
      "meta": {
        "organization": "hr"
      }
    }
  }
}

If you want to map groups from the user info, set the userGroupClaimPointer value to /meta/organization. This path is derived from the userInfo source, which contains the organization value that you need.

Note: This data includes your PII and you must not share it with others or IBM support.

Example configuration

The following example describes how to set up user groups.

An OIDC provider always provides an ID token, but you might receive additional data from the provider, and you can use this data as the source for a user group.

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 that returns the following additional user information when requested:

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

Complete the following steps to assign access:

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
}
```
Add the path to the required property (in this example, /data/group) to the userGroupClaimPointer field in the EventEndpointManagement custom resource as follows:
```
userGroupClaimPointer: /data/group
```

Note: Event Endpoint Management checks multiple sources for the configured property. If it does not find the /data/group field in the ID token, it checks for it next in the Access Token, then finally it checks 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, assume that the user has no groups.

Retrieving user groups for the Admin API

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

Important: If you access user groups by using a custom identifier, additional configuration is required to ensure that Admin API users have their groups read and see the correct options in the catalog. This is because 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"]

You must use an offline_access token to retrieve user groups.

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

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 must 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, an Admin API user cannot use groups, and will see public options only.