# keycloak_user – Create and configure a user in Keycloak — Keycloak Ansible Collection documentation

# 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)