Managing access

You can manage access to your Event Processing instance 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 Processing in one of the following ways:

Create local definitions on the cluster where Event Processing runs.
Integrate with an external identity provider that follows the OpenID Connect (OIDC) standard, such as Keycloak, or various public login services.

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.
Define mappings to custom roles in the OIDC provider if you have used an OIDC provider for authentication. For more information these options, see managing roles.

Important: Before you begin, ensure you have installed the Event Processing 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 Processing 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.authoring.authConfig section to include authType: LOCAL as follows:
```
apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
  #...
spec:
  #...
  authoring:
    authConfig:
      authType: LOCAL
  #...
```
This will create two secrets:
- <custom-resource-name>-ibm-ep-user-credentials
- <custom-resource-name>-ibm-ep-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-ep-user-credentials with your local user credentials, go to Actions and click Edit Secret.

Edit the mappings, for example:

{
    "users": [
        {
            "username": "user1",
            "password": "Password1$"
        },
        {
            "username": "user2",
            "password": "Password2$"
        }
    ]
}

Click Save.
Similarly, edit the secret <custom-resource-name>-ibm-ep-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 Processing instance after a few minutes and you can then log in with these users. For more information, see logging in to Event Processing.

Using the CLI

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Find the existing Event Processing 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:
1. Run the following command to edit the custom resource:
```
kubectl edit eventprocessing/<custom-resource-name>
```
2. Edit the spec.authoring.authConfig section to include authType: LOCAL as follows:
```
apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
   # ...
spec:
   # ...
  authoring:
    authConfig:
        authType: LOCAL
   # ...
```
This will create two secrets:
- <custom-resource-name>-ibm-ep-user-credentials
- <custom-resource-name>-ibm-ep-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 Processing instance, for example:

{
    "users": [
        {
          "username": "user1",
          "password": "Password1$"
        },
        {
          "username": "user2",
          "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-ep-user-credentials secret with the local user credentials by running the following command:

kubectl patch secret <custom-resource-name>-ibm-ep-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 Processing instance.
<your-base64-value> is the Base64-encoded string returned from the previous command.

For example:

kubectl patch secret quick-start-ep-ibm-ep-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-ep-user-credentials -o json

Important: For security reasons, delete the local file you created.
Similarly, edit the secret <custom-resource-name>-ibm-ep-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 Processing instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Processing.

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 Processing UI URLs. If you have already installed Event Processing, 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 Processing 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 Processing instance and add the spec.authoring.authConfig section to include the following settings for OIDC:

apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
  # ...
spec:
  # ...
  authoring:
    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 Processing.
Edit the secret <custom-resource-name>-ibm-ep-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 Processing instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Processing.

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 Processing will run:

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

Find the existing Event Processing 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 eventprocessing/<custom-resource-name>

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

apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
  # ...
spec:
  #...
  authoring:
    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 Processing.
Edit the secret <custom-resource-name>-ibm-ep-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 Processing instance after a few minutes, and you can then log in with these users. For more information, see logging in to Event Processing.

Setting up OIDC-based authentication with custom certificates

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

For example:

apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
metadata:
  name: custom-certs-auth
  namespace: ep
spec:
  #...
  authoring:
    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
        - # ...