Skip to content

Replace RHSSO with RHBK #1909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Replace RHSSO with RHBK #1909

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e09ad6e
Replace RHSSO with RHBK
mrrajan Aug 4, 2025
82e73b0
Removed the hardcoded client secret for cli
mrrajan Aug 4, 2025
e6fae3e
Reference to official RHBK guide
mrrajan Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
320 changes: 211 additions & 109 deletions docs/book/modules/admin/pages/infrastructure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,94 +353,79 @@ NOTE: The `--devel` flag is currently necessary as the Helm chart has a pre-rele

Install the following Red Hat services:

* Red Hat Single Sign-on (SSO) operator as the OpenID Connect (OIDC) provider.
* Red Hat Build of Keycloak (RHBK) operator as the OpenID Connect (OIDC) provider.
* Red Hat OpenShift Data Foundation operator as the storage provider.
* Red Hat Build of Opentelemetry for tracing and metrics.

=== Manual setup

=== Red Hat Single Sign-on operator
=== Red Hat Build of Keycloak Operator

* Install Single Sign-on operator with deployment https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html/server_installation_and_configuration_guide/operator#installing-operator[guide].
* Navigate to the related Keycloak instance of RHSSO operator and login to the Admin console with valid credentials.
* Install and Deploy Red Hat Build of Keycloak Operator with https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.2/html/operator_guide/index[guide].

Complete the following steps to configure Keycloak:

[[_realm_creation]]
==== Realm Creation

* Create a new **Realm** within your Keycloak instance.

[[_role_definition]]
==== Role Definition

* Create a custom role, for example, `trust-admin`.
* Assign the `trust-admin` role to the default roles for your newly created realm.
* Navigate to **Realm Settings** -> **Roles** tab -> Select the `default-roles-{your-realm-name}` role -> **Role Mappings** tab -> **Assign Role** to add `trust-admin`.

[[_client_scope_definition]]
==== Client Scope Definition

* Create the following **Client Scopes** with the `openid-connect` protocol:
** `read:document`
** `create:document`
** `update:document`
** `delete:document`

[[_assign_role_to_client_scope]]
==== Assign Roles to Client Scopes
[[_keycloak_usage_]]
==== Retrieve Admin Credentials
* Retrieve the Admin console username and password using the below commands,
+
[source, bash]
----
oc get secret example-kc-initial-admin -n $NAMESPACE -o jsonpath='{.data.username}' | base64 --decode
oc get secret example-kc-initial-admin -n $NAMESPACE -o jsonpath='{.data.password}' | base64 --decode
----
* On Openshift console, Go to Networking -> Routes
* Retrieve the Route of keycloak

* After creating the Client Scopes in <<_client_scope_definition,Client Scope Definition>>, navigate to each individual **Client Scope**.
* Select the **Scope** tab within each Client Scope's settings.
* Move the `trust-admin` role (created in <<_role_definition,Role Definition>>) from the Available Roles to the Assigned Roles for each scope.
==== Configuring Keycloak
Complete the following steps to configure Keycloak for RHTPA

[[_client_import]]
==== Client Import
[[_keycloak_bin_download]]
===== Download Keycloak
* https://www.keycloak.org/downloads[Download] and extract Keycloak binary

* Go to Keycloak administration console -> Go to **Clients** section.
* Click the **Create** button -> then **Import**.
* Select and import the following client configuration files:
** `frontend.json`
[[_keycloak_clients]]
===== Keycloak Clients
* Create two keycloak client json files `client-frontend.json` and `client-cli.json` with the below content
** `client-frontend.json`
+
[source, json]
----
{
"clientId": "frontend",
"clientAuthenticatorType": "client-secret",
"enabled": true,
"publicClient": true,
"implicitFlowEnabled": true,
"standardFlowEnabled": true,
"directAccessGrantsEnabled": false,
"serviceAccountsEnabled": false,
"fullScopeAllowed": true,
"webOrigins": [
"*"
],
"defaultClientScopes": [
"basic",
"email",
"profile",
"roles",
"web-origins",
"create:document",
"read:document",
"update:document",
"delete:document"
],
"optionalClientScopes": [
"address",
"microprofile-jwt",
"offline_access",
"phone"
],
"attributes": {
"access.token.lifespan": "300",
"post.logout.redirect.uris": "+"
}
"clientId": "frontend",
"clientAuthenticatorType": "client-secret",
"enabled": true,
"publicClient": true,
"implicitFlowEnabled": true,
"standardFlowEnabled": true,
"directAccessGrantsEnabled": false,
"serviceAccountsEnabled": false,
"fullScopeAllowed": true,
"webOrigins": [
"*"
],
"defaultClientScopes": [
"basic",
"email",
"profile",
"roles",
"web-origins",
"create:document",
"read:document",
"update:document",
"delete:document"
],
"optionalClientScopes": [
"address",
"microprofile-jwt",
"offline_access",
"phone"
],
"attributes": {
"access.token.lifespan": "300",
"post.logout.redirect.uris": "+"
}
}
----
** `cli.json`
** `client-cli.json`
+
[source, json]
----
Expand All @@ -455,64 +440,181 @@ Complete the following steps to configure Keycloak:
"serviceAccountsEnabled": true,
"fullScopeAllowed": true,
"defaultClientScopes": [
"basic",
"email",
"profile",
"roles",
"web-origins",
"create:document",
"read:document",
"update:document",
"delete:document"
"basic",
"email",
"profile",
"roles",
"web-origins",
"create:document",
"read:document",
"update:document",
"delete:document"
],
"optionalClientScopes": [
"address",
"microprofile-jwt",
"offline_access",
"phone"
"address",
"microprofile-jwt",
"offline_access",
"phone"
],
"attributes": {
"access.token.lifespan": "300",
"post.logout.redirect.uris": "+"
"access.token.lifespan": "300",
"post.logout.redirect.uris": "+"
}
}
----

[[_user_management]]
==== User Management

* Go to the **Users** section and add a new user.
* Go to the **Role Mapping** tab for this user, and assign the `trust-admin` role to the user.
* Under the **Credentials** tab, set a password for this user.

[[_cli_client_secret]]
==== Retrieve CLI Client Secret

* Navigate to the **Clients** section and select the `cli` client that you imported in <<_client_import,Client Import>>.
* Go to the **Credentials** tab.
* Retrieve the **secret** displayed here. This secret is essential for the Helm chart installation.
[[_keycloak_config_script]]
===== Create Realm, Roles, clients, client scopes and users
* Update the shell script below with the appropriate Keycloak configurations to create the Realm, roles, clients, client scopes, and users
* Execute the script to apply the changes
+
++++
<details>
<summary>Click here to show the bash script</summary>
<pre><code class="language bash">
[source, bash]
----
#!/bin/bash

# --- Configuration Variables ---
# The path to your kcadm.sh script.
KCADM_PATH="Path/to/kcadm.sh" # ---> 1

# Keycloak server connection details
KEYCLOAK_URL="<Keycloak URL>" # ---> 2
KEYCLOAK_ADMIN="<Keycloak admin username>" # ---> 3
KEYCLOAK_ADMIN_PASSWORD="<Keycloak admin password>" # ---> 4

# Realm settings
REALM="trust"

# Role name
TRUSTD_ROLE_NAME="trustd"

# Admin username
TRUSTED_ADMIN_USERNAME="admin" # ---> 5
# Admin user password
TRUSTED_ADMIN_PASSWORD="admin123456" # ---> 6

# Directory containing client JSON files
INIT_DATA="/path/to/client/json/" # ---> 7

CLIENTS=("cli" "frontend")

# Exit on interrupt
trap break INT

while ! "$KCADM_PATH" config credentials --server "$KEYCLOAK_URL" --realm master --user "$KEYCLOAK_ADMIN" --password "$KEYCLOAK_ADMIN_PASSWORD" &> /dev/null; do
echo "Waiting for Keycloak to start up..."
sleep 5
done

echo "Keycloak ready"

# Create/update realm
REALM_OPTS=()
REALM_OPTS+=(-s enabled=true)
REALM_OPTS+=(-s "displayName=Trusted Content")
REALM_OPTS+=(-s registrationAllowed=true)
REALM_OPTS+=(-s resetPasswordAllowed=true)
REALM_OPTS+=(-s loginWithEmailAllowed=false)

if "$KCADM_PATH" get "realms/${REALM}" &> /dev/null; then
# exists -> update
"$KCADM_PATH" update "realms/${REALM}" "${REALM_OPTS[@]}"
else
# need to create
"$KCADM_PATH" create realms -s "realm=${REALM}" "${REALM_OPTS[@]}"
fi

# Create realm roles
"$KCADM_PATH" create roles -r "$REALM" -s name="$TRUSTD_ROLE_NAME" || true
# add TRUSTD_ROLE_NAME as default role
"$KCADM_PATH" add-roles -r "$REALM" --rname "default-roles-${REALM}" --rolename "$TRUSTD_ROLE_NAME"

MANAGER_ID=$("$KCADM_PATH" get roles -r "$REALM" --fields id,name --format csv --noquotes | grep ",$TRUSTD_ROLE_NAME" | awk -F ',' '{print $1}')

# Create scopes
# shellcheck disable=SC2043
for i in read:document; do
"$KCADM_PATH" create client-scopes -r "$REALM" -s "name=$i" -s protocol=openid-connect || true
done

for i in create:document update:document delete:document; do
"$KCADM_PATH" create client-scopes -r "$REALM" -s "name=$i" -s protocol=openid-connect || true
ID=$("$KCADM_PATH" get client-scopes -r "$REALM" --fields id,name --format csv --noquotes | grep ",${i}" | awk -F ',' '{print $1}')
# add all scopes to the TRUSTD_ROLE_NAME role
"$KCADM_PATH" create "client-scopes/${ID}/scope-mappings/realm" -r "$REALM" -b '[{"name":"$TRUSTD_ROLE_NAME", "id":"'"${MANAGER_ID}"'"}]' || true
done

# Create and configure the cli client
for client in "${CLIENTS[@]}"; do
ID=$("$KCADM_PATH" get clients -r "$REALM" --query exact=true --query "clientId=${client}" --fields id --format csv --noquotes)
CLIENT_OPTS=()
if [[ -n "$ID" ]]; then
# TODO: replace with update once https://github.com/keycloak/keycloak/issues/12484 is fixed
"$KCADM_PATH" delete "clients/${ID}" -r "$REALM"
"$KCADM_PATH" create clients -r "$REALM" -f "${INIT_DATA}/client-${client}.json" "${CLIENT_OPTS[@]}"
else
"$KCADM_PATH" create clients -r "$REALM" -f "${INIT_DATA}/client-${client}.json" "${CLIENT_OPTS[@]}"
fi
# now set the client-secret
ID=$("$KCADM_PATH" get clients -r "$REALM" --query exact=true --query "clientId=${client}" --fields id --format csv --noquotes)
if [ "${client}" == "cli" ]; then
"$KCADM_PATH" add-roles -r "$REALM" --uusername service-account-${client} --rolename "$TRUSTD_ROLE_NAME"
fi
done
# Create user
ID=$("$KCADM_PATH" get users -r "$REALM" --query exact=true --query "username=$TRUSTED_ADMIN_USERNAME" --fields id --format csv --noquotes)
# the next check might seem weird, but that's just Keycloak reporting a "user not found" in two different ways
if [[ -n "$ID" && "$ID" != "[]" ]]; then
"$KCADM_PATH" update "users/$ID" -r "$REALM" -s enabled=true
else
"$KCADM_PATH" create users -r "$REALM" -s "username=$TRUSTED_ADMIN_USERNAME" -s enabled=true -s email=test@example.com -s emailVerified=true -s firstName=Admin -s lastName=Admin
fi

# set role
"$KCADM_PATH" add-roles -r "$REALM" --uusername "$TRUSTED_ADMIN_USERNAME" --rolename "$TRUSTD_ROLE_NAME"

# set password
ID=$("$KCADM_PATH" get users -r "$REALM" --query exact=true --query "username=$TRUSTED_ADMIN_USERNAME" --fields id --format csv --noquotes)
"$KCADM_PATH" update "users/${ID}/reset-password" -r "$REALM" -s type=password -s "value=${TRUSTED_ADMIN_PASSWORD}" -s temporary=false -n

echo Keycloak initialization complete
----
</code></pre>
</details>
++++
+
**References:**
+
. _KCADM_PATH:_ Update the KCADM path from <<_keycloak_bin_download, downaloded>> directory
. _KEYCLOAK_URL:_ Keycloak URL from <<_keycloak_usage_,operator>>
. _KEYCLOAK_ADMIN:_ Keycloak ADMIN username from <<_keycloak_usage_,operator>>
. _KEYCLOAK_ADMIN_PASSWORD:_ Keycloak ADMIN password from <<_keycloak_usage_,operator>>
. _TRUSTED_ADMIN_USERNAME:_ RHTPA application admin username. By default `admin`
. _TRUSTED_ADMIN_PASSWORD:_ RHTPA application admin password. By default `admin123456`
. _INIT_DATA:_ Location of keycloak <<_keycloak_clients,clients>> json files

[[_frontend_redirect_uris]]
==== Configure Frontend Redirect URIs

* Navigate to the **Clients** section and select the `frontend` client that you imported in <<_client_import,Client Import>>.
* In the **Valid Redirect URIs** field, add the application URL that will be used after the Helm installation which is `https://server{appDomain}`.
===== Configure Frontend Redirect URIs

* Navigate Keycloak admin console. Go to the **Clients** section and select the `frontend` client imported in <<_client_import,Client Import>>.
* Add the application URL to the **Valid Redirect URIs** field, Which is `https://server{appDomain}`. For example, `https://server-tpa.apps.ocp.cluster.net`

[NOTE]
Failure to update this field will result in a redirect URI error during application login.

==== Usage

For the RHTPA installation, the following OIDC values are retrieved from your Keycloak (RH-SSO) configuration:
For the RHTPA installation, the following OIDC values are retrieved from your Keycloak configuration:

* **issuerURL**: `_keycloakURL_/realms/<<_realm_creation,Realm name>>`
* **issuerURL**: `_keycloakURL_/realms/_<Realm name>_`
* **cli**: Retrieve the **Client Secret** from the Keycloak admin console by navigating to **Clients** -> **cli** -> **Credentials** tab.
* **frontend**: `empty object as {}`

[NOTE]
This means no secret or specific configuration is needed for the OIDC setup to install RHTPA.

* **cli**: Retrieve the **Client Secret** from the Keycloak admin console by navigating to **Clients** -> **cli** -> **Credentials** tab.

[[rhodf_operator_installation]]
=== Red Hat OpenShift Data Foundation Operator Configuration

Expand Down
Loading