Keycloak Realm Management

1. Overview

The domusdigitalis realm is the unified identity namespace for all applications.

2. Realm Structure

Setting Value

Realm Name

domusdigitalis

Display Name

DomusDigitalis Identity

SSL Required

external

Registration

Disabled (admin-only)

Brute Force Protection

Enabled

3. Groups

Group Purpose ISE Admin Group

ise-super-admin

Full ISE administrative access

Super Admin

ise-read-only

ISE read-only access

Read Only Admin

ise-helpdesk

ISE helpdesk/support access

Helpdesk Admin

ise-ers-admin

ISE ERS API access only

ERS Admin

nas-admin

Synology NAS administrative access

Super Admin

gitea-admin

Gitea administrative access

N/A

gitea-user

Standard Gitea user access

N/A

4. Import Realm via REST API

Do NOT use docker run …​ import with volume mounts. This causes H2 database permission errors. Use the REST API method below.

4.1. Step 1: Copy Realm JSON to Host

scp ise-realm.json keycloak-01:/tmp/

4.2. Step 2: Copy into Container

ssh keycloak-01 'sudo docker cp /tmp/ise-realm.json keycloak:/tmp/ise-realm.json'

4.3. Step 3: Import via REST API

ssh keycloak-01 'TOKEN=$(curl -ks https://localhost:8443/realms/master/protocol/openid-connect/token \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=<ADMIN_PASSWORD>" \
  -d "grant_type=password" | grep -o "\"access_token\":\"[^\"]*" | cut -d\" -f4) && \
curl -ks -X POST https://localhost:8443/admin/realms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @/tmp/ise-realm.json \
  -w "\nHTTP Code: %{http_code}\n"'
Expected Output
HTTP Code: 201

4.4. Verify Import

ssh keycloak-01 'TOKEN=$(curl -ks https://localhost:8443/realms/master/protocol/openid-connect/token \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=<ADMIN_PASSWORD>" \
  -d "grant_type=password" | grep -o "\"access_token\":\"[^\"]*" | cut -d\" -f4) && \
curl -ks https://localhost:8443/admin/realms \
  -H "Authorization: Bearer $TOKEN" | grep -o "\"realm\":\"[^\"]*\""'
Expected Output
"realm":"domusdigitalis"
"realm":"master"

5. Export Realm

ssh keycloak-01 'TOKEN=$(curl -ks https://localhost:8443/realms/master/protocol/openid-connect/token \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=<ADMIN_PASSWORD>" \
  -d "grant_type=password" | jq -r .access_token) && \
curl -ks https://localhost:8443/admin/realms/domusdigitalis \
  -H "Authorization: Bearer $TOKEN" > /tmp/realm-export.json'

6. Update Existing Realm

This overwrites realm configuration. User data is preserved, but client configurations will be reset.

 
ssh keycloak-01 'TOKEN=$(curl -ks https://localhost:8443/realms/master/protocol/openid-connect/token \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=<ADMIN_PASSWORD>" \
  -d "grant_type=password" | grep -o "\"access_token\":\"[^\"]*" | cut -d\" -f4) && \
curl -ks -X PUT https://localhost:8443/admin/realms/domusdigitalis \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @/tmp/ise-realm.json \
  -w "\nHTTP Code: %{http_code}\n"'

7. Delete Realm

ssh keycloak-01 'TOKEN=$(curl -ks https://localhost:8443/realms/master/protocol/openid-connect/token \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=<ADMIN_PASSWORD>" \
  -d "grant_type=password" | grep -o "\"access_token\":\"[^\"]*" | cut -d\" -f4) && \
curl -ks -X DELETE https://localhost:8443/admin/realms/domusdigitalis \
  -H "Authorization: Bearer $TOKEN" \
  -w "\nHTTP Code: %{http_code}\n"'
Expected Output
HTTP Code: 204

8. Post-Import Tasks

After importing the realm:

  1. Change user passwords - Default users have temporary: true

  2. Generate OIDC client secrets - For Gitea, NAS, iPSK Manager

  3. Download SAML metadata - For ISE configuration

  4. Configure ISE SAML IdP - See ISE Admin Portal SSO

8.1. Download SAML Metadata

curl -k https://keycloak-01.inside.domusdigitalis.dev:8443/realms/domusdigitalis/protocol/saml/descriptor \
  -o keycloak-saml-metadata.xml

9. Related