keycloak_user_execute_actions_email – Send a Keycloak execute-actions email to a user

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

New in middleware_automation.keycloak 3.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	Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: 10
http_agent string	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	Authentication refresh token for Keycloak API.
token string	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: middleware_automation.keycloak.keycloak	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: none	Will return 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
  middleware_automation.keycloak.keycloak_user_execute_actions_email:
    username: johndoe
    realm: MyRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com
    auth_realm: master
    auth_username: ADMIN
    auth_password: SECRET
    lifespan: 3600
  delegate_to: localhost

- name: Multiple required actions using token auth
  middleware_automation.keycloak.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
    token: TOKEN
  delegate_to: localhost

- name: Email by user id with redirect
  middleware_automation.keycloak.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_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)