# keycloak_realm_key – Allows administration of Keycloak realm keys using Keycloak API — Keycloak Ansible Collection documentation

# keycloak_realm_key – Allows administration of Keycloak realm keys using Keycloak API

Note

This module is part of the middleware_automation.keycloak collection.

It is not included in `ansible-core`. To check whether it is installed, run `ansible-galaxy collection list`.

To install it, use: `ansible-galaxy collection install middleware_automation.keycloak`.

To use it in a playbook, specify: `middleware_automation.keycloak.keycloak_realm_key`.

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows the administration of Keycloak realm keys using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles.

- The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation at https://www.keycloak.org/docs-api/latest/rest-api/index.html. Aliases are provided so camelCased versions can be used as well.

- This module is unable to detect changes to the actual cryptographic key after importing it. However, if some other property is changed alongside the cryptographic key, then the key also changes as a side-effect, as the JSON payload needs to include the private key. This can be considered either a bug or a feature, as the alternative would be to always update the realm key whether it has changed or not.

## Parameters

Parameter | Comments
--- | ---
auth_client_id string | OpenID Connect client_id to authenticate to the API with. Default: `"admin-cli"`
auth_client_secret string | Client Secret to use in conjunction with auth_client_id (if required).
auth_keycloak_url aliases: url string / required | URL to the Keycloak instance.
auth_password aliases: password string | Password to authenticate for API access with.
auth_realm string | Keycloak realm name to authenticate to for API access.
auth_username aliases: username string | Username to authenticate for API access with.
config dictionary | Dict specifying the key and its properties.

active

boolean

Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the `state` parameter.

Choices:

- `false`

- `true` ← (default)

algorithm

string

Key algorithm.

The values `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `RSA1_5`, `RSA-OAEP`, `RSA-OAEP-256` have been added in middleware_automation.keycloak 8.2.0.

The values `HS256`, `HS384`, `HS512` (for HMAC), `ES256`, `ES384`, `ES512` (for ECDSA), and `AES` have been added in middleware_automation.keycloak 12.4.0.

The values `ECDH_ES`, `ECDH_ES_A128KW`, `ECDH_ES_A192KW`, `ECDH_ES_A256KW` (for ECDH key exchange), and `Ed25519`, `Ed448` (for EdDSA signing) have been added in middleware_automation.keycloak 12.4.0.

For `provider_id=rsa`, `provider_id=rsa-generated`, and `provider_id=java-keystore`, defaults to `RS256`.

For `provider_id=rsa-enc` and `provider_id=rsa-enc-generated`, must be one of `RSA1_5`, `RSA-OAEP`, `RSA-OAEP-256` (required, no default).

For `provider_id=hmac-generated`, must be one of `HS256`, `HS384`, `HS512` (required, no default).

For `provider_id=ecdsa-generated`, must be one of `ES256`, `ES384`, `ES512` (required, no default).

For `provider_id=ecdh-generated`, must be one of `ECDH_ES`, `ECDH_ES_A128KW`, `ECDH_ES_A192KW`, `ECDH_ES_A256KW` (required, no default).

For `provider_id=eddsa-generated`, this option is not used (the algorithm is determined by `config.elliptic_curve`).

For `provider_id=aes-generated`, this option is not used (AES is always used).

Choices:

- `"RS256"` ← (default)

- `"RS384"`

- `"RS512"`

- `"PS256"`

- `"PS384"`

- `"PS512"`

- `"RSA1_5"`

- `"RSA-OAEP"`

- `"RSA-OAEP-256"`

- `"HS256"`

- `"HS384"`

- `"HS512"`

- `"ES256"`

- `"ES384"`

- `"ES512"`

- `"AES"`

- `"ECDH_ES"`

- `"ECDH_ES_A128KW"`

- `"ECDH_ES_A192KW"`

- `"ECDH_ES_A256KW"`

- `"Ed25519"`

- `"Ed448"`

certificate string | A certificate signed with the private key as an ASCII string. Contents of the key must match `config.algorithm` and `provider_id`. If you want Keycloak to automatically generate a certificate using your private key then set this to an empty string. Required when `provider_id` is `rsa` or `rsa-enc`. Not used for auto-generated providers.

elliptic_curve

string

The elliptic curve to use for ECDSA, ECDH, or EdDSA keys.

For `provider_id=ecdsa-generated` and `provider_id=ecdh-generated`, valid values are `P-256`, `P-384`, `P-521`. Default is `P-256`.

For `provider_id=eddsa-generated`, valid values are `Ed25519`, `Ed448`. Default is `Ed25519`.

Choices:

- `"P-256"`

- `"P-384"`

- `"P-521"`

- `"Ed25519"`

- `"Ed448"`

enabled

boolean

Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the `state` parameter.

Choices:

- `false`

- `true` ← (default)

key_alias string | Alias of the key within the keystore. Required when `provider_id=java-keystore`.
key_password string | Password for the key within the keystore. If not specified, the `config.keystore_password` is used. Only applicable to `provider_id=java-keystore`.
key_size integer | The size of the generated key in bits. Only applicable to `provider_id=rsa-generated` and `provider_id=rsa-enc-generated`. Valid values are `1024`, `2048`, `4096`. Default is `2048`.
keystore string | Path to the Java Keystore file on the Keycloak server filesystem. Required when `provider_id=java-keystore`.
keystore_password string | Password for the Java Keystore. Required when `provider_id=java-keystore`.
priority integer / required | The priority of the key.

private_key

string

The private key as an ASCII string. Contents of the key must match `config.algorithm` and `provider_id`.

Please note that the module cannot detect whether the private key specified differs from the current state's private key. Use `force=true` to force the module to update the private key if you expect it to be updated.

Required when `provider_id` is `rsa` or `rsa-enc`. Not used for auto-generated providers.

secret_size integer | The size of the generated secret key in bytes. Only applicable to `provider_id=hmac-generated` and `provider_id=aes-generated`. Valid values are `16`, `24`, `32`, `64`, `128`, `256`, `512`. Default is `64` for HMAC, `16` for AES.
connection_timeout integer | Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: `10`

force

boolean

Enforce the state of the private key and certificate. This is not automatically the case as this module is unable to determine the current state of the private key and thus cannot trigger an update based on an actual divergence. That said, a private key update may happen even if force is false as a side-effect of other changes.

Choices:

- `false` ← (default)

- `true`

http_agent string | Configures the HTTP User-Agent header. Default: `"Ansible"`
name string / required | Name of the realm key to create.
parent_id string / required | The parent_id of the realm key. In practice the name of the realm.

provider_id

string

The name of the "provider ID" for the key.

The value `rsa-enc` has been added in middleware_automation.keycloak 8.2.0.

The value `java-keystore` has been added in middleware_automation.keycloak 12.4.0. This provider imports keys from a Java Keystore (JKS or PKCS12) file located on the Keycloak server filesystem.

The values `rsa-generated`, `hmac-generated`, `aes-generated`, and `ecdsa-generated` have been added in middleware_automation.keycloak 3.0.0. These are auto-generated key providers where Keycloak manages the key material.

The values `rsa-enc-generated`, `ecdh-generated`, and `eddsa-generated` have been added in middleware_automation.keycloak 3.0.0. These correspond to the auto-generated key providers available in Keycloak 26.

Choices:

- `"rsa"` ← (default)

- `"rsa-enc"`

- `"java-keystore"`

- `"rsa-generated"`

- `"rsa-enc-generated"`

- `"hmac-generated"`

- `"aes-generated"`

- `"ecdsa-generated"`

- `"ecdh-generated"`

- `"eddsa-generated"`

refresh_token string | Authentication refresh token for Keycloak API.

state

string

State of the keycloak realm key.

On `present`, the realm key is created (or updated if it exists already).

On `absent`, the realm key is removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

token string | Authentication token for Keycloak API.

update_password

string

Controls when passwords are sent to Keycloak for `java-keystore` provider.

`always` - Always send passwords. Keycloak will update the component even if passwords have not changed. Use when you need to ensure passwords are updated.

`on_create` - Only send passwords when creating a new component. When updating an existing component, send the masked value to preserve existing passwords. This makes the module idempotent for password fields.

This is necessary because Keycloak masks passwords in API responses (returns `**********`), making comparison impossible.

Has no effect for providers other than `java-keystore`.

Choices:

- `"always"` ← (default)

- `"on_create"`

validate_certs

boolean

Verify TLS certificates (do not disable this in production).

Choices:

- `false`

- `true` ← (default)

## Attributes

Attribute | Support | Description
--- | --- | ---
action_group | Action group: middleware_automation.keycloak.keycloak added in middleware_automation.keycloak 3.0.0 | Use `group/middleware_automation.keycloak.keycloak` in `module_defaults` to set defaults for this module.
check_mode | Support: full | Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode | Support: partial | Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

## Notes

Note

- Current value of the private key cannot be fetched from Keycloak. Therefore comparing its desired state to the current state is not possible.

- If `config.certificate` is not explicitly provided it is dynamically created by Keycloak. Therefore comparing the current state of the certificate to the desired state (which may be empty) is not possible.

- Due to the private key and certificate options the module is not fully idempotent. You can use `force=true` to force the module to ensure updating if you know that the private key might have changed.

- For auto-generated providers (`rsa-generated`, `rsa-enc-generated`, `hmac-generated`, `aes-generated`, `ecdsa-generated`, `ecdh-generated`, `eddsa-generated`), Keycloak manages the key material automatically. The `config.private_key` and `config.certificate` options are not used.

- For `java-keystore` provider, the `config.keystore_password` and `config.key_password` values are returned masked by Keycloak. Therefore comparing their current state to the desired state is not possible. Use `update_password=on_create` for idempotent playbooks, or use `update_password=always` (default) if you need to ensure passwords are updated.

## Examples

    - name: Manage Keycloak realm key (certificate autogenerated by Keycloak)
      middleware_automation.keycloak.keycloak_realm_key:
        name: custom
        state: present
        parent_id: master
        provider_id: rsa
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          private_key: "{{ private_key }}"
          certificate: ""
          enabled: true
          active: true
          priority: 120
          algorithm: RS256

    - name: Manage Keycloak realm key and certificate
      middleware_automation.keycloak.keycloak_realm_key:
        name: custom
        state: present
        parent_id: master
        provider_id: rsa
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          private_key: "{{ private_key }}"
          certificate: "{{ certificate }}"
          enabled: true
          active: true
          priority: 120
          algorithm: RS256

    - name: Create HMAC signing key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: hmac-custom
        state: present
        parent_id: master
        provider_id: hmac-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: HS256
          secret_size: 64

    - name: Create AES encryption key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: aes-custom
        state: present
        parent_id: master
        provider_id: aes-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          secret_size: 16

    - name: Create ECDSA signing key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: ecdsa-custom
        state: present
        parent_id: master
        provider_id: ecdsa-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: ES256
          elliptic_curve: P-256

    - name: Create RSA signing key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: rsa-auto
        state: present
        parent_id: master
        provider_id: rsa-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: RS256
          key_size: 2048

    - name: Remove default HMAC key
      middleware_automation.keycloak.keycloak_realm_key:
        name: hmac-generated
        state: absent
        parent_id: myrealm
        provider_id: hmac-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          priority: 100

    - name: Create RSA encryption key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: rsa-enc-auto
        state: present
        parent_id: master
        provider_id: rsa-enc-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: RSA-OAEP
          key_size: 2048

    - name: Create ECDH key exchange key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: ecdh-custom
        state: present
        parent_id: master
        provider_id: ecdh-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: ECDH_ES
          elliptic_curve: P-256

    - name: Create EdDSA signing key (auto-generated)
      middleware_automation.keycloak.keycloak_realm_key:
        name: eddsa-custom
        state: present
        parent_id: master
        provider_id: eddsa-generated
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        config:
          enabled: true
          active: true
          priority: 100
          elliptic_curve: Ed25519

    - name: Import key from Java Keystore (always update passwords)
      middleware_automation.keycloak.keycloak_realm_key:
        name: jks-imported
        state: present
        parent_id: master
        provider_id: java-keystore
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        # update_password: always is the default - passwords are always sent to Keycloak
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: RS256
          keystore: /opt/keycloak/conf/keystore.jks
          keystore_password: "{{ keystore_password }}"
          key_alias: mykey
          key_password: "{{ key_password }}"

    - name: Import key from Java Keystore (idempotent - only set password on create)
      middleware_automation.keycloak.keycloak_realm_key:
        name: jks-idempotent
        state: present
        parent_id: master
        provider_id: java-keystore
        auth_keycloak_url: http://localhost:8080
        auth_username: keycloak
        auth_password: keycloak
        auth_realm: master
        update_password: on_create  # Only send passwords when creating, preserve existing on update
        config:
          enabled: true
          active: true
          priority: 100
          algorithm: RS256
          keystore: /opt/keycloak/conf/keystore.jks
          keystore_password: "{{ keystore_password }}"
          key_alias: mykey
          key_password: "{{ key_password }}"

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---
end_state dictionary | Representation of the keycloak_realm_key after module execution. Returned: on success
config dictionary | Realm key configuration. Returned: when `state=present` Sample: `{"active": ["true"], "algorithm": ["RS256"], "enabled": ["true"], "priority": ["140"]}`
id string | ID of the realm key. Returned: when `state=present` Sample: `"5b7ec13f-99da-46ad-8326-ab4c73cf4ce4"`
key_info dictionary | Cryptographic key metadata fetched from the realm keys endpoint. Only returned for `java-keystore` provider when `state=present` and not in check mode. This includes the key ID (kid) and certificate fingerprint, which can be used to detect if the actual cryptographic key changed. Returned: when `provider_id=java-keystore` and `state=present`
certificate_fingerprint string | SHA256 fingerprint of the certificate in colon-separated hex format. Returned: success Sample: `"A1:B2:C3:D4:E5:F6:..."`
kid string | The key ID (kid) - unique identifier for the cryptographic key. Returned: success Sample: `"bN7p5Nc_V2M7N_-mb5vVSRVPKq5qD_OuARInB9ofsJ0"`
status string | The key status (ACTIVE, PASSIVE, DISABLED). Returned: success Sample: `"ACTIVE"`
valid_to integer | Certificate expiration timestamp in milliseconds since epoch. Returned: success Sample: `1801789047000`
name string | Name of the realm key. Returned: when `state=present` Sample: `"mykey"`
parentId string | ID of the realm this key belongs to. Returned: when `state=present` Sample: `"myrealm"`
providerId string | The ID of the key provider. Returned: when `state=present` Sample: `"rsa"`
providerType string | The type of provider. Returned: when `state=present`
msg string | Message as to what action was taken. Returned: always

### Authors

- Samuli Seppänen (@mattock)

- Ivan Kokalović (@koke1997)