Keycloak Commands

Overview

The netapi keycloak command group provides CLI access to Keycloak Admin REST API.

Prerequisites

Load identity secrets before using Keycloak commands:

eval "$(dsec source d000 dev/identity)"

Realm Commands

list-realms

List all realms:

netapi keycloak list-realms

get-realm

Get realm details as JSON:

netapi keycloak get-realm domusdigitalis

import-realm

Import a realm from JSON file:

netapi keycloak import-realm /path/to/realm.json

export-realm

Export a realm to JSON:

# To stdout
netapi keycloak export-realm domusdigitalis

# To file
netapi keycloak export-realm domusdigitalis -o /tmp/realm-backup.json

delete-realm

Delete a realm (with confirmation):

netapi keycloak delete-realm testrealm

# Skip confirmation
netapi keycloak delete-realm testrealm --force

User Commands

list-users

List users in a realm:

netapi keycloak list-users domusdigitalis

# Search for specific user
netapi keycloak list-users domusdigitalis -s evanusmodestus

Group Commands

list-groups

List all groups in a realm:

netapi keycloak list-groups domusdigitalis

create-group

Create a new group:

netapi keycloak create-group domusdigitalis ise-super-admin

delete-group

Delete a group:

netapi keycloak delete-group domusdigitalis ise-helpdesk

# Skip confirmation
netapi keycloak delete-group domusdigitalis ise-helpdesk --force

user-groups

List groups a user belongs to:

netapi keycloak user-groups domusdigitalis evanusmodestus
Example Output
      Groups for 'evanusmodestus'
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Name            ┃ Path             ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ gitea-admin     │ /gitea-admin     │
│ ise-super-admin │ /ise-super-admin │
│ nas-admin       │ /nas-admin       │
└─────────────────┴──────────────────┘

add-user-to-group

Add a user to a group:

netapi keycloak add-user-to-group domusdigitalis evanusmodestus ise-super-admin

remove-user-from-group

Remove a user from a group:

netapi keycloak remove-user-from-group domusdigitalis evanusmodestus ise-helpdesk

Client Commands

list-clients

List all clients in a realm:

netapi keycloak list-clients domusdigitalis

get-client-secret

Get the secret for an OIDC client:

netapi keycloak get-client-secret domusdigitalis gitea

regenerate-client-secret

Generate a new secret for an OIDC client:

netapi keycloak regenerate-client-secret domusdigitalis gitea

SAML Commands

get-saml-metadata

Get SAML IdP metadata for ISE integration:

# To stdout
netapi keycloak get-saml-metadata domusdigitalis

# To file
netapi keycloak get-saml-metadata domusdigitalis -o /tmp/keycloak-metadata.xml

Integration Examples

ISE SAML Integration

Complete workflow for ISE SAML setup:

eval "$(dsec source d000 dev/identity)"

# Create ISE admin groups
netapi keycloak create-group domusdigitalis ise-super-admin
netapi keycloak create-group domusdigitalis ise-read-only
netapi keycloak create-group domusdigitalis ise-helpdesk

# Add user to admin group
netapi keycloak add-user-to-group domusdigitalis evanusmodestus ise-super-admin

# Get SAML metadata for ISE import
netapi keycloak get-saml-metadata domusdigitalis -o /tmp/keycloak-metadata.xml

Gitea OIDC Integration

eval "$(dsec source d000 dev/identity)"

# Get client secret for Gitea
netapi keycloak get-client-secret domusdigitalis gitea

# If compromised, regenerate
netapi keycloak regenerate-client-secret domusdigitalis gitea

Backup Commands

backup

Backup all realms to local storage or NAS:

# Backup all realms
netapi keycloak backup

# Backup and upload to NAS
netapi keycloak backup --upload-nas

# Specify NAS destination
netapi keycloak backup --upload-nas --nas-folder /Backups/keycloak
Sample Output
╭──────────────────────────────────────────────────╮
│               Keycloak Realm Backup              │
╰──────────────────────────────────────────────────╯
  Host: https://keycloak-01.inside.domusdigitalis.dev:8443
  Realms: 2

  ✓ domusdigitalis → keycloak-01-inside-domusdigitalis-dev-domusdigitalis-20260124-185721.json
  ✓ master → keycloak-01-inside-domusdigitalis-dev-master-20260124-185721.json

✓ Exported 2 realms
  Timestamp: 2026-01-24T18:57:22.272408

Uploading to Synology NAS...
  ✓ keycloak-01-inside-domusdigitalis-dev-domusdigitalis-20260124-185721.json
  ✓ keycloak-01-inside-domusdigitalis-dev-master-20260124-185721.json
✓ Uploaded 2 files to /Backups/keycloak

Options:

Option Short Description

--upload-nas

-u

Upload to Synology NAS

--nas-folder

NAS destination folder

NAS Upload Requirements

For --upload-nas to work, load storage secrets:

dsource d000 dev/storage

Required variables in dev/storage:

Variable Description

SYNOLOGY_IP

NAS IP address

SYNOLOGY_USER

API username

SYNOLOGY_PASS

API password

KEYCLOAK_BACKUP_PATH

Destination folder (default: /keycloak_backups)

Manual Backup and Restore

For single-realm operations:

# Backup single realm
netapi keycloak export-realm domusdigitalis -o ~/backups/domusdigitalis-$(date +%Y%m%d).json

# Restore realm (after delete or on new server)
netapi keycloak import-realm ~/backups/domusdigitalis-20260118.json