community.general.keycloak_authz_permission (8.5.0) — module

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

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. U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
name:
    description:
    - Name of the authorization permission to create.
    required: true
    type: str

realm:
    description:
    - The name of the Keycloak realm the Keycloak client is in.
    required: true
    type: str

state:
    choices:
    - present
    - absent
    default: present
    description:
    - State of the authorization permission.
    - On V(present), the authorization permission will be created (or updated if it exists
      already).
    - On V(absent), the authorization permission will be removed if it exists.
    type: str

token:
    description:
    - Authentication token for Keycloak API.
    type: str
    version_added: 3.0.0
    version_added_collection: community.general

scopes:
    default: []
    description:
    - Scope names to attach to this permission.
    - Resource-based permissions cannot have scopes attached to them.
    elements: str
    required: false
    type: list

policies:
    default: []
    description:
    - Policy names to attach to this permission.
    elements: str
    required: false
    type: list

client_id:
    description:
    - The clientId of the keycloak client that should have the authorization scope.
    - This is usually a human-readable name of the Keycloak client.
    required: true
    type: str

resources:
    default: []
    description:
    - Resource names to attach to this permission.
    - Scope-based permissions can only include one resource.
    - Resource-based permissions can include multiple resources.
    elements: str
    required: false
    type: list

auth_realm:
    description:
    - Keycloak realm name to authenticate to for API access.
    type: str

http_agent:
    default: Ansible
    description:
    - Configures the HTTP User-Agent header.
    type: str
    version_added: 5.4.0
    version_added_collection: community.general

description:
    description:
    - The description of the authorization permission.
    required: false
    type: str

auth_password:
    aliases:
    - password
    description:
    - Password to authenticate for API access with.
    type: str

auth_username:
    aliases:
    - username
    description:
    - Username to authenticate for API access with.
    type: str

auth_client_id:
    default: admin-cli
    description:
    - OpenID Connect C(client_id) to authenticate to the API with.
    type: str

validate_certs:
    default: true
    description:
    - Verify TLS certificates (do not disable this in production).
    type: bool

permission_type:
    choices:
    - resource
    - scope
    description:
    - The type of authorization permission.
    - On V(scope) create a scope-based permission.
    - On V(resource) create a resource-based permission.
    required: true
    type: str

auth_keycloak_url:
    aliases:
    - url
    description:
    - URL to the Keycloak instance.
    required: true
    type: str

decision_strategy:
    choices:
    - UNANIMOUS
    - AFFIRMATIVE
    - CONSENSUS
    default: UNANIMOUS
    description:
    - The decision strategy to use with this permission.
    required: false
    type: str

auth_client_secret:
    description:
    - Client Secret to use in conjunction with O(auth_client_id) (if required).
    type: str

connection_timeout:
    default: 10
    description:
    - Controls the HTTP connections timeout period (in seconds) to Keycloak API.
    type: int
    version_added: 4.5.0
    version_added_collection: community.general

Outputs

end_state:
  contains:
    decisionStrategy:
      description: The decision strategy to use.
      returned: when O(state=present)
      sample: UNANIMOUS
      type: str
    description:
      description: Description of the authorization permission.
      returned: when O(state=present)
      sample: Resource Permission
      type: str
    id:
      description: ID of the authorization permission.
      returned: when O(state=present)
      sample: 9da05cd2-b273-4354-bbd8-0c133918a454
      type: str
    logic:
      description: The logic used for the permission (part of the payload, but has
        a fixed value).
      returned: when O(state=present)
      sample: POSITIVE
      type: str
    name:
      description: Name of the authorization permission.
      returned: when O(state=present)
      sample: ResourcePermission
      type: str
    policies:
      description: IDs of policies attached to this permission.
      returned: when O(state=present)
      sample:
      - 9da05cd2-b273-4354-bbd8-0c133918a454
      type: list
    resources:
      description: IDs of resources attached to this permission.
      returned: when O(state=present)
      sample:
      - 49e052ff-100d-4b79-a9dd-52669ed3c11d
      type: list
    scopes:
      description: IDs of scopes attached to this permission.
      returned: when O(state=present)
      sample:
      - 9da05cd2-b273-4354-bbd8-0c133918a454
      type: list
    type:
      description: Type of the authorization permission.
      returned: when O(state=present)
      sample: resource
      type: str
  description: Representation of the authorization permission after module execution.
  returned: on success
  type: complex
msg:
  description: Message as to what action was taken.
  returned: always
  type: str