community.general.keycloak_realm_key module – Allows administration of Keycloak realm keys via Keycloak API
Note
This module is part of the community.general collection (version 8.6.4).
You might already have this collection installed if you are using the ansible
package.
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 community.general
.
To use it in a playbook, specify: community.general.keycloak_realm_key
.
New in community.general 7.5.0
Synopsis
This module allows the administration of Keycloak realm keys via the Keycloak REST API. It requires access to the REST API via 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/8.0/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 will also get changed 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.
If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current state of the certificate to the desired state (which may be empty) is not possible.
Parameters
Parameter |
Comments |
---|---|
OpenID Connect Default: |
|
Client Secret to use in conjunction with |
|
URL to the Keycloak instance. |
|
Password to authenticate for API access with. |
|
Keycloak realm name to authenticate to for API access. |
|
Username to authenticate for API access with. |
|
Dict specifying the key and its properties. |
|
Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the Choices:
|
|
Key algorithm. The values Choices:
|
|
A certificate signed with the private key as an ASCII string. Contents of the key must match If you want Keycloak to automatically generate a certificate using your private key then set this to an empty string. |
|
Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the Choices:
|
|
The priority of the key. |
|
The private key as an ASCII string. Contents of the key must match Please note that the module cannot detect whether the private key specified differs from the current state’s private key. Use |
|
Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: |
|
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:
|
|
Configures the HTTP User-Agent header. Default: |
|
Name of the realm key to create. |
|
The parent_id of the realm key. In practice the ID (name) of the realm. |
|
The name of the “provider ID” for the key. The value Choices:
|
|
State of the keycloak realm key. On On Choices:
|
|
Authentication token for Keycloak API. |
|
Verify TLS certificates (do not disable this in production). Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: partial |
Will return details on what has changed (or possibly needs changing in |
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 certificate is not explicitly provided it will be 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 always update if you know that the private key might have changed.
Examples
- name: Manage Keycloak realm key (certificate autogenerated by Keycloak)
community.general.keycloak_realm_key:
name: custom
state: present
parent_id: master
provider_id: rsa
auth_keycloak_url: http://localhost:8080/auth
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
community.general.keycloak_realm_key:
name: custom
state: present
parent_id: master
provider_id: rsa
auth_keycloak_url: http://localhost:8080/auth
auth_username: keycloak
auth_password: keycloak
auth_realm: master
config:
private_key: "{{ private_key }}"
certificate: "{{ certificate }}"
enabled: true
active: true
priority: 120
algorithm: RS256
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Representation of the keycloak_realm_key after module execution. Returned: on success |
|
Realm key configuration. Returned: when Sample: |
|
The type of provider. Returned: when |
|
Message as to what action was taken. Returned: always |