Configuring authentication

Configure authentication for the platform hub and attached capabilities by running the Keycloak setup script.

IBM Concert platform uses Keycloak for identity and access management in self-hosted deployments. The platform hub deployment includes a containerized Keycloak server and a PostgreSQL database. You can use this default Keycloak instance or bring your own.

The Keycloak setup script configures authentication for the platform hub and all capabilities that are attached to it. You run this script after you install the platform hub and capability products because the script requires the product URLs.

This script runs the following tasks:

Creates a realm, the Keycloak container that holds the platform's users, roles, and sign-in settings.
Registers the platform as a client so it can authenticate users through Keycloak.
Defines two default roles that govern access within the platform: administrator and user.
Creates the default local administrator

Before you begin

The default instance of Keycloak includes temporary credentials by default. The setup script uses these credentials to initialize the instance and create the first admin user. You can replace the temporary credentials with permanent credentials at any time, either before or after you run the script. These credentials apply only to the Keycloak user interface (UI). The credentials for accessing platform capabilities are configured separately in the setup script.

To replace the credentials before you run the script, complete the following optional steps.

Run the following command to get the pod name for the default Keycloak instance.
```
kubectl get pods | grep "ibm-solis-embedded-keycloak" | awk '{print $1}'
```
Run the following command to retrieve the temporary credentials.
Replace ibm-solis-embedded-keycloak-xxx with the pod name that you retrieved in the previous step.
```
kubectl exec -it ibm-solis-embedded-keycloak-xxx -n $HUB_NS -- env | grep KC_BOOT
```
The output provides the credentials in the following format:
```
KC_BOOTSTRAP_ADMIN_PASSWORD=xxxx
KC_BOOTSTRAP_ADMIN_USERNAME=xxxx
```
Go to the Keycloak admin console by using an ingress or route-based URL.
- For Kubernetes deployments, construct the URL based on the host and port where you installed the platform hub.
```
https://<hub-host>:<hub-port>/sys/internal/kc/
```
- For Red Hat OpenShift deployments, construct the URL by using the Red Hat OpenShift Container Platform route for the platform hub.
```
https://<ocp-route>/sys/internal/kc/
```
For more information about the platform hub ingress, see Installing the platform hub: Step 5: Expose the ingress or route.
Log in to the console by using the credentials that you obtained in step 2.
- You will see a banner notification that prompts you to create a permanent admin account
Confirm that the master realm is selected as the current realm.
- If you don't see the current realm label, open the sidebar navigation and click Manage realms. Then select master.
In the sidebar navigation, click Users.
Click Add user.
Enter a username in the required field and click Create.
- The other fields are optional.
Go to the Credentials tab and click Set password.
Enter a password and set the Temporary toggle to Off.
This option creates a permanent password for the user.
Click Save.
Log out of the Keycloak admin console and log back in with your new username and password.
- The temporary password notification no longer appears.

If you don't replace these credentials before you run the script, you are prompted to replace them when it completes.

The platform includes a default Keycloak instance. You can use this instance or bring your own:

Set up the default Keycloak instance.
Bring your own Keycloak instance.

Set up the default Keycloak instance

The platform hub deployment includes a containerized Keycloak server and a PostgreSQL database. You can use the default settings in this instance of Keycloak to configure platform authentication

Go to the directory that contains the setup-keycloak.sh setup script:
```
cd $INSTALL_DIR/ibm-platform-hub/bin
```
Or, if you used the Concert product installer:
```
cd $INSTALL_DIR/concert-hub/bin
```

Run the setup script with the required parameters:

./setup-keycloak.sh \
  --kc-url=https://{HUB_HOST}:{HUB_PORT}/sys/internal/kc \
  --namespace={NAMESPACE} \
  --product-url=https://{PRODUCT_HOST}:{PRODUCT_PORT} \
  --username={USERNAME} \
  --password={PASSWORD}

If you already removed the temporary bootstrap admin and created a permanent Keycloak admin user, include your Keycloak admin credentials.

./setup-keycloak.sh \
  --kc-url=https://{HUB_HOST}:{HUB_PORT}/sys/internal/kc \
  --namespace={NAMESPACE} \
  --product-url=https://{PRODUCT_HOST}:{PRODUCT_PORT} \
  --username={USERNAME} \
  --password={PASSWORD} \
  --kc-admin-username={KC_ADMIN_USERNAME} \
  --kc-admin-password={KC_ADMIN_PASSWORD}

Specify the following values:

Parameter	Description
`kc-url`	Specify the Keycloak URL that includes the host and port where you installed the platform hub, for example `https://<hub_host>:<hub_port>/sys/internal/kc` For Red Hat OpenShift deployments, Specify your platform hub route instead of host and port, for example, `https://<ocp route>/sys/internal/kc`
`namespace`	Specify the Kubernetes namespace where you deployed the platform hub. If you set `$HUB_NS` when you installed the platform hub, specify that environment variable here.
`product-url`	Specify the hostname and port where you installed a capability product, such as Concert Observe. If you installed the platform on Red Hat OpenShift, specify the Red Hat OpenShift Container Platform route (`https://{your-ocp-route}`).
`username`	Specify the admin username for the platform. You created this username when you ran the setup script to install the platform hub.
`password`	Specify the admin password for the platform. You created this password when you ran the setup script to install the platform hub.
`kc-admin-username`, `kc-admin-password`	If you already removed the temporary bootstrap admin and created a permanent Keycloak admin user, specify your Keycloak admin credentials.

Optional: Log in to the Keycloak admin console and add more redirect URIs for your capabilities.

Note: This step is applicable only when you need to login to multiple capabilities.
1. Log in to the Keycloak admin console.
2. Click Add valid redirect URIs.
3. Add the redirect URI:
  - Use https://<host>/platform_hub/* to log in if the product is available at default port 443, as shown in the following example:
```
https://<instana-hostname>/platform_hub/*
```
  - Use https://<host>:<port>/platform_hub/* to log in if the product is not available at default port 443, as shown in the following example:
```
https://<instana-hostname>:12443/platform_hub/*
```

Bring your own Keycloak instance

Alternatively, you can bring your own existing Keycloak instance to set up user management

Go to the directory that contains the setup-keycloak.sh setup script:
```
cd $INSTALL_DIR/ibm-platform-hub/bin
```
Or, if you used the Concert product installer:
```
cd concert-hub/bin
```

Run the setup script with the required parameters.

./setup-keycloak.sh \
  --kc-url=https://{HUB_HOST}:{HUB_PORT}/sys/internal/kc \
  --namespace={NAMESPACE} \
  --product-url=https://{PRODUCT_HOST}:{PRODUCT_PORT} \
  --username={USERNAME} \
  --password={PASSWORD} \
  --kc-admin-username={BYO_KC_ADMIN_USERNAME} \
  --kc-admin-password={BYO_KC_ADMIN_PASSWORD}

Parameter	Description
`kc-url`	Specify the Keycloak URL that includes the host and port where you installed the platform hub, for example `https://<hub_host>:<hub_port>/sys/internal/kc` For Red Hat OpenShift deployments, Specify your platform hub route instead of host and port, for example, `https://<ocp route>/sys/internal/kc`
`namespace`	Specify the Kubernetes namespace where you deployed the platform hub. If you set `$HUB_NS` when you installed the platform hub, specify that environment variable here.
`product-url`	Specify the hostname and port where you installed a capability product, such as Concert Observe. If you installed the platform on Red Hat OpenShift, specify the Red Hat OpenShift Container Platform route (`https://{your-ocp-route}`).
`username`	Specify the admin username for the platform. You created this username when you ran the setup script to install the platform hub.
`password`	Specify the admin password for the platform. You created this password when you ran the setup script to install the platform hub.
`kc-admin-username`, `kc-admin-password`	Specify the username and password for your existing Keycloak instance.

Optional: Log in to the Keycloak admin console and add more redirect URIs for your capabilities

Note: This step is applicable only when you need to login to multiple capabilities.
1. Log in to the Keycloak admin console
2. Click Add valid redirect URIs.
3. Add the redirect URI:
  - Use https://<host>/platform_hub/* to log in if the product is available at default port 443, as shown in the following example:
```
https://<observe-hostname>/platform_hub/*
```
  - Use https://<host>:<port>/platform_hub/* to log in if the product is not available at default port 443, as shown in the following example:
```
https://<observe-hostname>:12443/platform_hub/*
```
Configure the platform to use your existing Keycloak instance.
1. Follow the Keycloak documentation to locate the certificate file for your Keycloak instance.
2. Run the following command to attach your TLS certificate to the platform:
```
$INSTALL_DIR/ibm-platform-hub/bin/kc-tls-attach-k8s $HUB_NS <keycloak-hostname> <tls-cert-file>
```
  - Replace <keycloak-hostname> with your Keycloak hostname.
  - Replace <tls-cert-file> with the relative path to your certificate file.
After you complete the configuration, access the UI by using a configured capability URL. The UI uses OIDC authentication and it routes you to the Keycloak UI for login.

Next steps

Test the integration and assigned roles by logging in to your Concert platform capabilities with the user credentials you specified in the Keycloak setup.
Log in to the Keycloak admin console to create more users and groups and manage access to the platform. For more information, see the Keycloak documentation.
Complete the platform post-installation setup. See Post-installation tasks and next steps.