/ home / jugasit / jugasit.keycloak / 1.1.0 / module / user

jugasit.keycloak.user (1.1.0) — module

Allows administration of Keycloak users via Keycloak API

| "added in version" 1.0.0 of jugasit.keycloak"

Authors: Christoffer Reijer (@ephracis)

Install collection

Install with ansible-galaxy collection install jugasit.keycloak:==1.1.0

Add to requirements.yml

  collections:
    - name: jugasit.keycloak
      version: 1.1.0

Description

This module allows you to add, remove or modify Keycloak users via the Keycloak REST API. It requires access to the REST API via 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 U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).

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

Usage examples

Scanned by Steampunk Spotter

- name: Create a Keycloak realm user, authentication with credentials
  jugasit.keycloak.user:
    name: my-new-kc-user
    realm: MyCustomRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

Scanned by Steampunk Spotter

- name: Create a Keycloak realm user, authentication with token
  jugasit.keycloak.user:
    name: my-new-kc-user
    realm: MyCustomRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
  delegate_to: localhost

Scanned by Steampunk Spotter

- name: Delete a Keycloak user
  jugasit.keycloak.user:
    name: my-user-for-deletion
    state: absent
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

Scanned by Steampunk Spotter

- name: Create a keycloak user with some custom attributes
  jugasit.keycloak.user:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    name: my-new-user
    attributes:
        attrib1: value1
        attrib2: value2
        attrib3:
            - with
            - numerous
            - individual
            - list
            - items
  delegate_to: localhost

Inputs

    
email:
    description:
    - Email of the user.
    type: str

realm:
    default: master
    description:
    - Realm of the user.
    type: str

state:
    choices:
    - present
    - absent
    default: present
    description:
    - State of the user.
    - On C(present), the user will be created if it does not yet exist, or updated with
      the parameters you provide.
    - On C(absent), the user will be removed if it exists.
    type: str

token:
    description:
    - Authentication token for Keycloak API.
    type: str
    version_added: 1.0.0
    version_added_collection: jugasit.keycloak

groups:
    description:
    - List of groups the user should be a member of.
    elements: str
    type: list

enabled:
    default: true
    description:
    - Whether or not the user is enabled.
    type: bool

password:
    description:
    - Password to set for the user.
    - If user already exists, you must set C(update_secrets) to C(true) to change password.
    type: str

username:
    description:
    - Username of the user.
    - This parameter is required.
    required: true
    type: str

last_name:
    description:
    - Last name of the user.
    type: str

attributes:
    description:
    - A dict of key/value pairs to set as custom attributes for the user.
    - Values may be single values (e.g. a string) or a list of strings.
    type: dict

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

first_name:
    description:
    - First name of the user.
    type: str

http_agent:
    default: Ansible
    description:
    - Configures the HTTP User-Agent header.
    type: str
    version_added: 1.0.0
    version_added_collection: jugasit.keycloak

append_groups:
    default: true
    description:
    - If C(yes), then add the user to the groups specified in C(groups).
    - If C(no), then the module only adds the user to the groups specified in C(groups),
      removing them from all other groups.
    type: bool

auth_password:
    description:
    - Password to authenticate for API access with.
    - If the value is not specified in the task, the value of environment variable C(KEYCLOAK_PASSWORD)
      or C(SSO_PASSWORD) will be used instead.
    type: str

auth_username:
    description:
    - Username to authenticate for API access with.
    - If the value is not specified in the task, the value of environment variable C(KEYCLOAK_USERNAME)
      or C(SSO_USERNAME) will be used instead.
    type: str

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

email_verified:
    default: true
    description:
    - Whether or not the email has been verified for the user.
    type: bool

update_secrets:
    default: false
    description:
    - Whether or not to update the password if the user exists.
    type: bool

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

auth_keycloak_url:
    aliases:
    - url
    description:
    - URL to the Keycloak instance.
    - If the value is not specified in the task, the value of environment variable C(KEYCLOAK_URL)
      or C(SSO_URL) will be used instead.
    required: false
    type: str

auth_client_secret:
    description:
    - Client Secret to use in conjunction with I(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: 1.0.0
    version_added_collection: jugasit.keycloak

Outputs

end_state:
  description: Representation of user after module execution (sample is truncated).
  returned: on success
  sample:
    attributes: {}
    email: user1@example.com
    firstName: User
    id: 561703dd-0f38-45ff-9a5a-0c978f794547
    lastName: One
    username: user1
  type: dict
existing:
  description: Representation of existing user (sample is truncated).
  returned: always
  sample:
    attributes: {}
    email: user1@example.com
    firstName: User
    id: 561703dd-0f38-45ff-9a5a-0c978f794547
    lastName: '111'
    username: user1
  type: dict
msg:
  description: Message as to what action was taken.
  returned: always
  sample: User test1 has been updated
  type: str
proposed:
  description: Representation of proposed user.
  returned: always
  sample:
    lastName: One
  type: dict