keycloak_user – Create and configure a user in Keycloak

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_user.

New in middleware_automation.keycloak 3.0.0

Synopsis

• This module creates, removes, or updates Keycloak users.

Parameters

Parameter	Comments
access dictionary	List user access.
attributes list / elements=dictionary	List of user attributes.
name string	Name of the attribute.
state string	Control whether the attribute must exists or not. Choices: "present" ← (default) "absent"
values list / elements=string	Values for the attribute as list.
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 string	Username to authenticate for API access with.
client_consents aliases: clientConsents list / elements=dictionary	Client Authenticator Type. Default: []
client_id aliases: clientId string / required	Client ID of the client role. Not the technical ID of the client.
roles list / elements=string / required	List of client roles to assign to the user.
connection_timeout integer	Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: 10
credentials list / elements=dictionary	User credentials. Default: []
temporary boolean	If true, the users are required to reset their credentials at next login. Choices: false ← (default) true
type string / required	Credential type.
value string / required	Value of the credential.
disableable_credential_types aliases: disableableCredentialTypes list / elements=string	List user Credential Type. Default: []
email string	User email.
email_verified aliases: emailVerified boolean	Set or reset the emailVerified flag of the user. When email_verified_behavior=no_defaults, the default value of this option becomes null and that causes the module not to change any existing value for that attribute. Choices: false true
email_verified_behavior string added in middleware_automation.keycloak 3.0.0	The email_verified option used to have a default value. This caused problems when the user expects different behavior from keycloak by default. The default value of this option is compatibility, which will ensure that the old default value for email_verified is used. When set to no_defaults, the module will not change existing values of email_verified if no value is specified. Choices: "compatibility" ← (default) "no_defaults"
enabled boolean	Enabled user. Choices: false true
federated_identities aliases: federatedIdentities list / elements=string	List of IDPs of user. Default: []
federation_link aliases: federationLink string	Federation Link.
first_name aliases: firstName string	The user's first name.
force boolean	If true, allows to remove user and recreate it. Choices: false ← (default) true
groups list / elements=dictionary	List of groups for the user. Groups can be referenced by their name, like staff, or their path, like /staff/engineering. The path syntax allows you to reference subgroups, which is not possible otherwise. Using the path is possible since middleware_automation.keycloak 3.0.0. Default: []
name string	Name of the group.
state string	Control whether the user must be member of this group or not. Choices: "present" ← (default) "absent"
http_agent string	Configures the HTTP User-Agent header. Default: "Ansible"
id string	ID of the user on the Keycloak server if known.
last_name aliases: lastName string	The user's last name.
origin string	User origin.
realm string	The name of the realm in which is the client. Default: "master"
refresh_token string	Authentication refresh token for Keycloak API.
required_actions aliases: requiredActions list / elements=string	Set or reset a user's required actions.
self string	User self administration.
service_account_client_id aliases: serviceAccountClientId string	Description of the client Application.
state string	Control whether the user should exists or not. Choices: "present" ← (default) "absent"
token string	Authentication token for Keycloak API.
username string / required	Username for the user.
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: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

• The module does not modify the user ID of an existing user.

Examples

- name: Create a user user1
  middleware_automation.keycloak.keycloak_user:
    auth_keycloak_url: http://localhost:8080
    auth_username: admin
    auth_password: password
    realm: master
    username: user1
    firstName: user1
    lastName: user1
    email: user1
    enabled: true
    emailVerified: false
    credentials:
      - type: password
        value: password
        temporary: false
    attributes:
      - name: attr1
        values:
          - value1
        state: present
      - name: attr2
        values:
          - value2
        state: absent
    groups:
      - name: group1
        state: present
    state: present

- name: Re-create a User
  middleware_automation.keycloak.keycloak_user:
    auth_keycloak_url: http://localhost:8080
    auth_username: admin
    auth_password: password
    realm: master
    username: user1
    firstName: user1
    lastName: user1
    email: user1
    enabled: true
    emailVerified: false
    credentials:
      - type: password
        value: password
        temporary: false
    attributes:
      - name: attr1
        values:
          - value1
        state: present
      - name: attr2
        values:
          - value2
        state: absent
    groups:
      - name: group1
        state: present
    state: present

- name: Re-create a User
  middleware_automation.keycloak.keycloak_user:
    auth_keycloak_url: http://localhost:8080
    auth_username: admin
    auth_password: password
    realm: master
    username: user1
    firstName: user1
    lastName: user1
    email: user1
    enabled: true
    emailVerified: false
    credentials:
      - type: password
        value: password
        temporary: false
    attributes:
      - name: attr1
        values:
          - value1
        state: present
      - name: attr2
        values:
          - value2
        state: absent
    groups:
      - name: group1
        state: present
    state: present
    force: true

- name: Remove User
  middleware_automation.keycloak.keycloak_user:
    auth_keycloak_url: http://localhost:8080
    auth_username: admin
    auth_password: password
    realm: master
    username: user1
    state: absent

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 user after module execution. Returned: on success
existing dictionary	Representation of the existing user. Returned: on success
proposed dictionary	Representation of the proposed user. Returned: on success
user_created boolean	Indicates whether a user was created. Returned: in success

Authors

• Philippe Gauthier (@elfelip)