# keycloak_user_execute_actions_email – Send a Keycloak execute-actions email to a user — Keycloak Ansible Collection documentation

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