community.general.keycloak_authz_permission module – Allows administration of Keycloak client authorization permissions 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_authz_permission
.
New in community.general 7.2.0
Synopsis
This module allows the administration of Keycloak client authorization permissions via the Keycloak REST API. Authorization permissions are only available if a client has Authorization enabled.
There are some peculiarities in JSON paths and payloads for authorization permissions. In particular POST and PUT operations are targeted at permission endpoints, whereas GET requests go to policies endpoint. To make matters more interesting the JSON responses from GET requests return data in a different format than what is expected for POST and PUT. The end result is that it is not possible to detect changes to things like policies, scopes or resources - at least not without a large number of additional API calls. Therefore this module always updates authorization permissions instead of attempting to determine if changes are truly needed.
This module 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 options used by Keycloak. The Authorization Services paths and payloads have not officially been documented by the Keycloak project. https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/
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. |
|
The clientId of the keycloak client that should have the authorization scope. This is usually a human-readable name of the Keycloak client. |
|
Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: |
|
The decision strategy to use with this permission. Choices:
|
|
The description of the authorization permission. |
|
Configures the HTTP User-Agent header. Default: |
|
Name of the authorization permission to create. |
|
The type of authorization permission. On On Choices:
|
|
Policy names to attach to this permission. Default: |
|
The name of the Keycloak realm the Keycloak client is in. |
|
Resource names to attach to this permission. Scope-based permissions can only include one resource. Resource-based permissions can include multiple resources. Default: |
|
Scope names to attach to this permission. Resource-based permissions cannot have scopes attached to them. Default: |
|
State of the authorization permission. 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: none |
Will return details on what has changed (or possibly needs changing in |
Examples
- name: Manage scope-based Keycloak authorization permission
community.general.keycloak_authz_permission:
name: ScopePermission
state: present
description: Scope permission
permission_type: scope
scopes:
- file:delete
policies:
- Default Policy
client_id: myclient
realm: myrealm
auth_keycloak_url: http://localhost:8080/auth
auth_username: keycloak
auth_password: keycloak
auth_realm: master
- name: Manage resource-based Keycloak authorization permission
community.general.keycloak_authz_permission:
name: ResourcePermission
state: present
description: Resource permission
permission_type: resource
resources:
- Default Resource
policies:
- Default Policy
client_id: myclient
realm: myrealm
auth_keycloak_url: http://localhost:8080/auth
auth_username: keycloak
auth_password: keycloak
auth_realm: master
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Representation of the authorization permission after module execution. Returned: on success |
|
Description of the authorization permission. Returned: when Sample: |
|
ID of the authorization permission. Returned: when Sample: |
|
The logic used for the permission (part of the payload, but has a fixed value). Returned: when Sample: |
|
IDs of policies attached to this permission. Returned: when Sample: |
|
IDs of resources attached to this permission. Returned: when Sample: |
|
IDs of scopes attached to this permission. Returned: when Sample: |
|
Message as to what action was taken. Returned: always |
Authors
Samuli Seppänen (@mattock)