community.general.keycloak_user_execute_actions_email module – Send a Keycloak execute-actions email to a user

Note

This module is part of the community.general collection (version 12.0.0).

You might already have this collection installed if you are using the ansible package. 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 community.general.

To use it in a playbook, specify: community.general.keycloak_user_execute_actions_email.

New in community.general 12.0.0

Synopsis

  • Triggers the Keycloak endpoint execute-actions-email for a user. This sends an email with one or more required actions the user must complete (for example resetting the password).

  • If no actions list is provided, the default action UPDATE_PASSWORD is used.

  • You must supply either the user’s id or username. Supplying only username causes an extra lookup call.

  • This module always reports changed=true because sending an email is a side effect and cannot be made idempotent.

Parameters

Parameter

Comments

actions

list / elements=string

List of required actions to include in the email.

Default: ["UPDATE_PASSWORD"]

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_id

aliases: clientId

string

Optional client ID used for the redirect link.

connection_timeout

integer

added in community.general 4.5.0

Controls the HTTP connections timeout period (in seconds) to Keycloak API.

Default: 10

http_agent

string

added in community.general 5.4.0

Configures the HTTP User-Agent header.

Default: "Ansible"

id

string

The unique ID (UUID) of the user.

Mutually exclusive with username.

lifespan

integer

Optional lifespan (in seconds) for the action token (supported on newer Keycloak versions). Forwarded as query parameter if provided.

realm

string

The Keycloak realm where the user resides.

Default: "master"

redirect_uri

aliases: redirectUri

string

Optional redirect URI. Must be valid for the given client if client_id is set.

refresh_token

string

added in community.general 10.3.0

Authentication refresh token for Keycloak API.

token

string

added in community.general 3.0.0

Authentication token for Keycloak API.

username

string

Username of the user.

Mutually exclusive with id.

validate_certs

boolean

Verify TLS certificates (do not disable this in production).

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

action_group

Action group: community.general.keycloak

Use group/community.general.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: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Password reset email (default action) with 1h lifespan
  community.general.keycloak_user_execute_actions_email:
    username: johndoe
    realm: MyRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: ADMIN
    auth_password: SECRET
    lifespan: 3600
  delegate_to: localhost

- name: Multiple required actions using token auth
  community.general.keycloak_user_execute_actions_email:
    username: johndoe
    actions:
      - UPDATE_PASSWORD
      - VERIFY_EMAIL
    realm: MyRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
  delegate_to: localhost

- name: Email by user id with redirect
  community.general.keycloak_user_execute_actions_email:
    id: 9d59aa76-2755-48c6-b1af-beb70a82c3cd
    client_id: my-frontend
    redirect_uri: https://app.example.com/post-actions
    actions:
      - UPDATE_PASSWORD
    realm: MyRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: ADMIN
    auth_password: SECRET
  delegate_to: localhost

Return Values

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

Key

Description

actions

list / elements=string

List of actions included in the email.

Returned: success

user_id

string

The user ID the email was (or would be, in check mode) sent to.

Returned: success

Authors

  • Marius Bertram (@mariusbertram)