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.6.1).

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
Parameters
Attributes
Examples
Return Values

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)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/keycloak_user_execute_actions_email_module.html