keycloak_organization – Allows administration of Keycloak organizations 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_organization.

New in middleware_automation.keycloak 3.1.0

Synopsis

• This module allows you to add, remove or modify Keycloak organizations using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client 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 client 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.

• Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API.

• Organizations are available in Keycloak 26 and later. The realm must have organizations enabled (organizations_enabled=true in the middleware_automation.keycloak.keycloak_realm module) before this module can be used.

• When updating an organization, where possible provide the organization ID to the module. This removes a lookup to the API to translate the name into the organization ID.

Parameters

Parameter	Comments
alias string	URL-friendly alias for the organization. If not provided during creation, defaults to the organization name if URL-safe. The alias is immutable once set and cannot be changed on update.
attributes dictionary	A dict of key/value pairs to set as custom attributes for the organization. Values may be single values (for example a string) or a list of strings.
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.
connection_timeout integer	Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: 10
description string	Description of the organization.
domains list / elements=dictionary	List of internet domains associated with the organization. A domain name can only belong to one organization within a realm.
name string / required	The domain name (e.g. example.com).
verified boolean	Whether the domain has been verified. Choices: false ← (default) true
enabled boolean	Whether the organization is enabled. Disabled organizations block member authentication. Choices: false true
http_agent string	Configures the HTTP User-Agent header. Default: "Ansible"
id string	The unique identifier for this organization. This parameter is not required for updating or deleting an organization but providing it reduces the number of API calls required.
name string	Name of the organization. This parameter is required when creating a new organization.
realm string	The Keycloak realm under which this organization resides. Default: "master"
refresh_token string	Authentication refresh token for Keycloak API.
state string	State of the organization. On present, the organization is created if it does not yet exist, or updated with the parameters you provide. On absent, the organization is removed if it exists. Choices: "present" ← (default) "absent"
token string	Authentication token for Keycloak API.
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.1.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: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create a Keycloak organization
  middleware_automation.keycloak.keycloak_organization:
    name: my-org
    description: My Organization
    enabled: true
    realm: MyRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Create a Keycloak organization with domains
  middleware_automation.keycloak.keycloak_organization:
    name: acme-corp
    description: Acme Corporation
    enabled: true
    domains:
      - name: acme.com
      - name: acme.org
        verified: true
    realm: MyRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Update a Keycloak organization
  middleware_automation.keycloak.keycloak_organization:
    name: my-org
    description: Updated description
    realm: MyRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Delete a Keycloak organization
  middleware_automation.keycloak.keycloak_organization:
    name: my-org
    state: absent
    realm: MyRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

Return Values

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

Key	Description
end_state complex	Representation of the organization after module execution. Returned: on success
alias string	URL-friendly alias of the organization. Returned: always Sample: "my-org"
attributes dictionary	Attributes applied to this organization. Returned: always Sample: {"attr1": ["val1", "val2"]}
description string	Description of the organization. Returned: always Sample: "My Organization"
domains list / elements=string	Domains associated with the organization. Returned: always Sample: [{"name": "example.com", "verified": false}]
enabled boolean	Whether the organization is enabled. Returned: always Sample: true
id string	GUID that identifies the organization. Returned: always Sample: "23f38145-3195-462c-97e7-97041ccea73e"
name string	Name of the organization. Returned: always Sample: "my-org"
msg string	Message as to what action was taken. Returned: always

Authors

• Chris Brown (@chribro)