Managing access

You can manage access to Event Endpoint Management by defining authentication and authorization rules. Authentication rules control login access, and authorization rules control what actions the user has permissions to take after logging in.

You can set up authentication in Event Endpoint Management in one of the following ways:

Create local definitions on the cluster where Event Endpoint Management runs.
Integrate with an external identity provider that follows the OpenID Connect (OIDC) standard, such as Keycloak, your existing corporate ID provider, or various public login services.
Integrate with the local Keycloak provided by a IBM Cloud Pak for Integration installation on the cluster.

After a user is authenticated, they are authorized to perform actions based on their assigned roles. You can set up authorization in one of the following ways:

Create local definitions to assign roles to specific users.
If you have used an OIDC provider for authentication, set up mappings to control roles through your OIDC provider.
If you have integrated with the IBM Cloud Pak for Integration identity provider (Keycloak), set up mappings to control roles through Keycloak.

For more information these options, see managing roles.

Important: Before you begin, ensure you have installed the Event Endpoint Management operator.

Setting up local authentication

You can use local authentication to define users explicitly with usernames and passwords in a Kubernetes secret on the cluster. Local authentication is best suited for testing, prototyping, and demonstration purposes.

Important: Despite local authentication being a valid internal OIDC provider with secure network traffic, the local authentication provider stores user credentials in a single JSON file as unencrypted strings. This makes local authentication simpler to set up than OIDC-based authentication, but passwords are at a higher risk of being exposed.

Using OpenShift Container Platform UI

Log in to the OpenShift Container Platform web console using your login credentials.
In the Installed Operators view, switch to the namespace where you installed your existing Event Manager instance. If you have not created one yet, follow the installation instructions to create an instance.
Edit the custom resource for the instance and add the spec.manager.authConfig section to include authType: LOCAL as follows:
```
apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
...
spec:
  ...
  manager:
    authConfig:
      authType: LOCAL
  ...
```
This will create two secrets:
- <custom-resource-name>-ibm-eem-user-credentials
- <custom-resource-name>-ibm-eem-user-roles
To add users and define their roles, update these secrets.
Expand Workloads in the navigation on the left and click Secrets. This lists the secrets available in this project (namespace).
To edit the secret <custom-resource-name>-ibm-eem-user-credentials with your local user credentials, go to Actions and click Edit Secret.

Edit the mappings, for example:

{
    "users": [
        {
            "username": "author1",
            "password": "Password1$"
        },
        {
            "username": "viewer1",
            "password": "Password2$"
        }
    ]
}

Click Save.
Similarly, edit the secret <custom-resource-name>-ibm-eem-user-roles to configure the roles and permissions of your users. For more information, see managing roles.

The changed configuration files are automatically picked up by the Event Manager instance after a few minutes and you can then log in with these users. For more information, see logging in to Event Endpoint Management.

Using the CLI

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Find the existing Event Manager instance that you want to configure. If you have not created one yet, create one by using one of the templates for OpenShift, or on other Kubernetes platforms.
Change to the namespace where your instance is installed.
Edit the custom resource for the instance as follows:
```
kubectl edit eventendpointmanagement/<custom-resource-name>
```
Edit the spec.manager.authConfig section to include authType: LOCAL as follows:
```
apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
...
spec:
  ...
  manager:
    authConfig:
       authType: LOCAL
  ...
```
This will create two secrets:
- <custom-resource-name>-ibm-eem-user-credentials
- <custom-resource-name>-ibm-eem-user-roles
To add users and define their roles, update these secrets.

Create a JSON file called myusers.json that contains the user credentials for your Event Manager instance, for example:

{
    "users": [
        {
            "username": "author1",
            "password": "Password1$"
        },
        {
            "username": "viewer1",
            "password": "Password2$"
        }
    ]
}

Obtain the Base64-encoded string representing the file content. For example, you can run the following command to obtain the string:
```
cat myusers.json | base64
```

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

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

where:

<custom-resource-name> is the name of your Event Manager 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-credentials --type='json' -p='[{"op" : "replace" ,"path" : "/data/user-credentials.json" ,"value" : "ewogICAgInVzZXJzIjogWwogICAgICAgIHsKICAgICAgICAgICAgInVzZXJuYW1lIjogImF1dGhvcjEiLAogICAgICAgICAgICAicGFzc3dvcmQiOiAiUGFzc3dvcmQxJCIKICAgICAgICB9LAogICAgICAgIHsKICAgICAgICAgICAgInVzZXJuYW1lIjogInZpZXdlcjEiLAogICAgICAgICAgICAicGFzc3dvcmQiOiAiUGFzc3dvcmQyJCIKICAgICAgICB9CiAgICBdCn0KCg=="}]'

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

kubectl edit secret/<custom-resource-name>-ibm-eem-user-credentials -o json

Important: For security reasons, delete the local file you created.
Similarly, edit the secret <custom-resource-name>-ibm-eem-user-roles to configure the roles and permissions of your users. For more information, see managing roles.

Note: The patch replaces a path of "/data/user-mapping.json" not "/data/user-credentials.json" for this secret.

The changed configuration files are automatically picked up by the Event Manager instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Endpoint Management.

Setting up OpenID Connect (OIDC)-based authentication

You can authenticate users from an OIDC Identification Provider as follows. By using OIDC authentication, you can centralize authentication across all your applications, providing a more secure setup than local authentication.

Before you start, ensure you retrieve the following configuration values for your OIDC provider:

Client ID
Client Secret
OIDC Provider base URL

Note: Ensure you have the right permission in your organization to retrieve these values or set up an OIDC client with your provider. You might need to contact your security administrator for permission or to set up a new OIDC client.

If your OIDC provider does not implement the Open ID Connect Discovery standard, ensure you also have the following values:

The tokenPath used by that provider (this extends the OIDC Provider base URL noted earlier).
The authorizationPath used by that provider, which also extends the base URL.
Optional: The endSessionPath for that provider, which also extends the base URL.

When creating an OIDC client in your provider, it will ask for redirect URLs for logging in to the UI, and potentially for logging out as well. Ensure you set these URLs to the appropriate Event Endpoint Management UI URLs. If you have already installed Event Endpoint Management, then see step 8 in the UI steps for the value of these URLs before proceeding. Otherwise, add the URL http://www.example.com/, and proceed with creating the client. You can update the redirect URLs in a later step.

Using OpenShift Container Platform UI

If you do not already have one, access your OIDC provider and create a client.
Retrieve the following required configuration values from your client:
- Client ID
- Client Secret
- OIDC Provider base URL
Log in to the OpenShift Container Platform web console using your login credentials.
In the Installed Operators view, switch to the namespace where you installed your existing Event Manager instance. If you have not created one yet, follow the installation instructions to create an instance.
Click the + button in the navigation on the top. The text editor opens.

Paste the following Secret YAML into the editor:

 kind: Secret
 apiVersion: v1
 metadata:
   name: oidc-secret
   namespace: <your_namespace>
 data:
   client-id: <base_64_encoded_client_id>
   client-secret: <base_64_encoded_client_secret>
 type: Opaque

Edit the custom resource for your existing Event Manager instance and add the spec.manager.authConfig section to include the following settings for OIDC:

 apiVersion: events.ibm.com/v1beta1
 kind: EventEndpointManagement
 ...
 spec:
   ...
   manager:
     authConfig:
       authType: OIDC
       oidcConfig:
         clientIDKey: client-id
         clientSecretKey: client-secret
         discovery: true
         secretName: oidc-secret
         site: <oidc_provider_base_url>
   ...

Note: The values of clientIDKey and clientSecretKey must match the keys in the secret created in previous step. The oidc_provider_base_url is the URL for your OIDC provider where discovery is performed, with /.well-known/openid-configuration removed from the end of the path. If there is no discovery endpoint, the URL preceding the required path is used.

Important: If your OIDC provider does not support OIDC Discovery, add the following parameters in the oidcConfig section:

 discovery: false
 tokenPath: (required) <path to the token endpoint of this provider>
 authorizationPath: (required) <path to the authorization endpoint of this provider>
 endSessionPath: (optional) <path to the end session endpoint of this provider for logging out>

After your instance reports Ready in its status field, retrieve the UI URL from the status information in the custom resource, open the client configuration of your OIDC provider, and update the redirect URLs to include the following addresses:

For logging in:
```
 https://<ui_url>/callback
```
For logging out (if supported by your OIDC provider):
```
 https://<ui_url>/logout/callback
```
Users defined in your OIDC provider will now be able to log in. For more information, see logging in to Event Endpoint Management.
Edit the secret <custom-resource-name>-ibm-eem-user-roles to configure roles and permissions for your users. For more information, see managing roles.

The changed configuration files are automatically picked up by the Event Manager instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Endpoint Management.

Using the CLI

If you do not already have one, access your OIDC provider and create a client.
Retrieve the following required configuration values from your client:
- Client ID
- Client Secret
- OIDC Provider base URL
Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

Run the following command to create a secret containing the OIDC credentials, in the namespace where your Event Endpoint Management will run:

cat <<EOF | kubectl apply -f -
kind: Secret
apiVersion: v1
metadata:
  name: oidc-secret
  namespace: <namespace_for_your_eem_instance>
data:
  client-id: <base_64_encoded_client_id>
  client-secret: <base_64_encoded_client_secret>
type: Opaque
EOF

Find the existing Event Manager instance that you want to configure. If you have not created one yet, create one by using one of the templates for OpenShift, or on other Kubernetes platforms.

Edit the custom resource for the instance as follows:

kubectl edit eventendpointmanagement/<custom-resource-name>

Edit the spec.manager.authConfig section and add the spec.manager.authConfig section to include the following settings for OIDC:

   apiVersion: events.ibm.com/v1beta1
   kind: EventEndpointManagement
   ...
   spec:
     ...
     manager:
       authConfig:
         authType: OIDC
         oidcConfig:
           clientIDKey: client-id
           clientSecretKey: client-secret
           discovery: true
           secretName: oidc-secret
           site: <oidc_provider_base_url>

Important: If your OIDC provider does not support OIDC Discovery, add the following parameters in the oidcConfig section:

 discovery: false
 tokenPath: (required) <path to the token endpoint of this provider>
 authorizationPath: (required) <path to the authorization endpoint of this provider>
 endSessionPath: (optional) <path to the end session endpoint of this provider for logging out>

After your instance reports Ready in its status field, retrieve the UI URL from the status information in the custom resource, open the client configuration of your OIDC provider, and update the redirect URLs to include the following addresses:

For logging in:
```
 https://<ui_url>/callback
```
For logging out (if supported by your OIDC provider):
```
 https://<ui_url>/logout/callback
```
Users defined in your OIDC provider will now be able to log in. For more information, see logging in to Event Endpoint Management.
Edit the secret <custom-resource-name>-ibm-eem-user-roles to configure roles and permissions for your users. For more information, see managing roles.

The changed configuration files are automatically picked up by the Event Manager instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Endpoint Management.

Setting up OIDC-based authentication with custom certificates

If your OIDC provider uses TLS certificates that are not publicly trusted, you can extend the EventEndpointManagement custom resource to include references to certificates that the Event Manager instance can use to trust the OIDC provider.

For example:

apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
metadata:
  name: custom-certs-auth
  namespace: eem
spec:
  ...
  manager:
    authConfig:
      authType: OIDC
      oidcConfig:
        clientIDKey: client-id
        clientSecretKey: client-secret
        discovery: true
        secretName: oidc-secret
        site: <oidc_provider_base_url>
    tls:
      trustedCertificates:
        - secretName: oidc-ca
          certificate: ca.crt
        - ...

IBM Cloud Pak for Integration: Setting up Keycloak authentication

You can authenticate users by using the Keycloak provided by IBM Cloud Pak for Integration. This means that you can configure user access to all capabilities within Cloud Pak for Integration by using the same Keycloak instance.

Using OpenShift Container Platform UI

Log in to the OpenShift Container Platform web console using your login credentials.
In the Installed Operators view, change to the namespace where you installed your existing Event Manager instance. If you have not created one yet, follow the installation instructions to create an instance.

Edit the custom resource for the instance and add the spec.manager.authConfig section to include authType: INTEGRATION_KEYCLOAK as follows:

apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
# ...
spec:
  # ...
  manager:
    authConfig:
      authType: INTEGRATION_KEYCLOAK
  # ...

Edit the secret <custom-resource-name>-ibm-eem-user-roles to configure roles and permissions for your users. For more information, see managing roles.

Using the CLI

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Find the existing Event Manager instance that you want to configure. If you have not created one yet, create one by using one of the templates for OpenShift, or for other Kubernetes platforms.
Change to the namespace where your instance is installed.

Edit the EventEndpointManagement custom resource for the instance as follows:

kubectl edit eventendpointmanagement/<custom-resource-name>

Edit the spec.manager.authConfig section to include authType: INTEGRATION_KEYCLOAK as follows:

apiVersion: events.ibm.com/v1beta1
kind: EventEndpointManagement
# ...
spec:
 # ...
  manager:
    authConfig:
       authType: INTEGRATION_KEYCLOAK
 # ...

Edit the secret <custom-resource-name>-ibm-eem-user-roles to configure roles and permissions for your users. For more information, see managing roles.
Optional: If you want to use the Event Endpoint Management Admin API, you must enable offline access. Add the environment variable EI_AUTH_OAUTH2_ADDITIONAL_SCOPES to the EventEndpointManagement custom resource as follows:
```
spec:
  manager:
    template:
      pod:
        spec:
          containers:
            - name: manager
              env:
                - name: EI_AUTH_OAUTH2_ADDITIONAL_SCOPES
                  value: 'email,profile,offline_access'
```
Note: If you enable offline access with this environment variable, all users must have the offline_access scope as a prerequisites to be able to access the Event Endpoint Management UI.