# keycloak_userprofile – Allows managing Keycloak User Profiles — Keycloak Ansible Collection documentation

# keycloak_userprofile – Allows managing Keycloak User Profiles

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_userprofile`.

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows you to create, update, or delete Keycloak User Profiles using the Keycloak API. You can also customize the “Unmanaged Attributes” with it.

- The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation at https://www.keycloak.org/docs-api/24.0.5/rest-api/index.html. For compatibility reasons, the module also accepts the camelCase versions of the options.

## Parameters

Parameter | Comments
--- | ---
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 aliases: username string | Username to authenticate for API access with.
config dictionary | The configuration of the User Profile Provider.
kc_user_profile_config aliases: kcUserProfileConfig list / elements=dictionary | Define a declarative User Profile. See EXAMPLES for more context.
attributes list / elements=dictionary | A list of attributes to be included in the User Profile.
annotations dictionary | Annotations for the attribute.
display_name aliases: displayName string / required | The display name of the attribute.
group string | Specifies the User Profile group where this attribute is added.

multivalued

boolean

Whether the attribute can have multiple values.

Choices:

- `false` ← (default)

- `true`

name string / required | The name of the attribute.
permissions dictionary | The permissions for viewing and editing the attribute.
edit list / elements=string | The roles that can edit the attribute. Supported values are `admin` and `user`. Default: `["admin", "user"]`
view list / elements=string | The roles that can view the attribute. Supported values are `admin` and `user`. Default: `["admin", "user"]`
required dictionary | The roles that require this attribute.
roles list / elements=string | The roles for which this attribute is required. Supported values are `admin` and `user`. Default: `["user"]`
selector dictionary | Selector when the attribute should be added.
scopes list / elements=string | Scopes to which the attribute should be added.
validations dictionary | The validations to be applied to the attribute.
double dictionary | The double validation for the attribute.
email dictionary | The email validation for the attribute.
integer dictionary | The integer validation for the attribute.
iso_date aliases: isoDate dictionary | The iso-date validation for the attribute.
length dictionary | The length validation for the attribute.
max integer / required | The maximum length of the attribute.
min integer | The minimum length of the attribute.
local_date aliases: localDate dictionary | The local-date validation for the attribute.
multivalued dictionary | The multivalued validation for the attribute.
max integer / required | The maximum amount of values of the attribute.
min integer | The minimum amount of values of the attribute.
options dictionary | Validation to ensure the attribute matches one of the provided options.
pattern dictionary | The pattern validation for the attribute using regular expressions.
person_name_prohibited_characters aliases: personNameProhibitedCharacters dictionary | The prohibited characters validation for person name attributes.
up_username_not_idn_homograph aliases: upUsernameNotIdnHomograph dictionary | The validation to prevent IDN homograph attacks in usernames.
uri dictionary | The URI validation for the attribute.
username_prohibited_characters aliases: usernameProhibitedCharacters dictionary | The prohibited characters validation for the username attribute.
groups list / elements=dictionary | A list of attribute groups to be included in the User Profile.
annotations dictionary | The annotations included in the group.
display_description aliases: displayDescription string | The display description for the group.
display_header aliases: displayHeader string / required | The display header for the group.
name string / required | The name of the group.

unmanaged_attribute_policy

aliases: unmanagedAttributePolicy

string

Policy for unmanaged attributes.

Choices:

- `"ENABLED"`

- `"ADMIN_EDIT"`

- `"ADMIN_VIEW"`

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"`
parent_id aliases: parentId, realm string / required | The parent ID of the realm key. In practice the ID (name) of the realm.

provider_id

aliases: providerId

string

The name of the provider ID for the key (supported value is `declarative-user-profile`).

Choices:

- `"declarative-user-profile"` ← (default)

provider_type

aliases: providerType

string

Component type for User Profile (only supported value is `org.keycloak.userprofile.UserProfileProvider`).

Choices:

- `"org.keycloak.userprofile.UserProfileProvider"` ← (default)

refresh_token string | Authentication refresh token for Keycloak API.

state

string

State of the User Profile provider.

On `present`, the User Profile provider is created if it does not yet exist, or updated with the parameters you provide.

On `absent`, the User Profile provider is removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

token string | Authentication token for Keycloak API.

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 added in middleware_automation.keycloak 3.0.0 | 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: full | Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

## Notes

Note

- Currently, only a single `declarative-user-profile` entry is supported for `provider_id` (design of the Keyckoak API). However, there can be multiple `config.kc_user_profile_config[].attributes[]` entries.

## Examples

    - name: Create a Declarative User Profile with default settings
      middleware_automation.keycloak.keycloak_userprofile:
        state: present
        parent_id: master
        config:
          kc_user_profile_config:
            - attributes:
                - name: username
                  displayName: ${username}
                  validations:
                    length:
                      min: 3
                      max: 255
                    username_prohibited_characters: {}
                    up_username_not_idn_homograph: {}
                  annotations: {}
                  permissions:
                    view:
                      - admin
                      - user
                    edit: []
                  multivalued: false
                - name: email
                  displayName: ${email}
                  validations:
                    email: {}
                    length:
                      max: 255
                  annotations: {}
                  required:
                    roles:
                      - user
                  permissions:
                    view:
                      - admin
                      - user
                    edit: []
                  multivalued: false
                - name: firstName
                  displayName: ${firstName}
                  validations:
                    length:
                      max: 255
                    person_name_prohibited_characters: {}
                  annotations: {}
                  required:
                    roles:
                      - user
                  permissions:
                    view:
                      - admin
                      - user
                    edit: []
                  multivalued: false
                - name: lastName
                  displayName: ${lastName}
                  validations:
                    length:
                      max: 255
                    person_name_prohibited_characters: {}
                  annotations: {}
                  required:
                    roles:
                      - user
                  permissions:
                    view:
                      - admin
                      - user
                    edit: []
                  multivalued: false
                - name: testAttribute
                  displayName: ${testAttribute}
                  validations:
                    integer:
                      min: 0
                      max: 255
                  annotations: {}
                  required:
                    roles:
                      - user
                  permissions:
                    view:
                      - admin
                      - user
                    edit: []
                  multivalued: false
              groups:
                - name: user-metadata
                  displayHeader: User metadata
                  displayDescription: Attributes, which refer to user metadata
                  annotations: {}

    - name: Delete a Keycloak User Profile Provider
      keycloak_userprofile:
        state: absent
        parent_id: master

    # Unmanaged attributes are user attributes not explicitly defined in the User Profile
    # configuration. By default, unmanaged attributes are "Disabled" and are not
    # available from any context such as registration, account, and the
    # administration console. By setting "Enabled", unmanaged attributes are fully
    # recognized by the server and accessible through all contexts, useful if you are
    # starting migrating an existing realm to the declarative User Profile
    # and you don't have yet all user attributes defined in the User Profile configuration.
    - name: Enable Unmanaged Attributes
      middleware_automation.keycloak.keycloak_userprofile:
        state: present
        parent_id: master
        config:
          kc_user_profile_config:
            - unmanagedAttributePolicy: ENABLED

    # By setting "Only administrators can write", unmanaged attributes can be managed
    # only through the administration console and API, useful if you have already
    # defined any custom attribute that can be managed by users but you are unsure
    # about adding other attributes that should only be managed by administrators.
    - name: Enable ADMIN_EDIT on Unmanaged Attributes
      middleware_automation.keycloak.keycloak_userprofile:
        state: present
        parent_id: master
        config:
          kc_user_profile_config:
            - unmanagedAttributePolicy: ADMIN_EDIT

    # By setting `Only administrators can view`, unmanaged attributes are read-only
    # and only available through the administration console and API.
    - name: Enable ADMIN_VIEW on Unmanaged Attributes
      middleware_automation.keycloak.keycloak_userprofile:
        state: present
        parent_id: master
        config:
          kc_user_profile_config:
            - unmanagedAttributePolicy: ADMIN_VIEW

## Return Values

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

Key | Description
--- | ---
data dictionary | The data returned by the Keycloak API. Returned: when state is present
msg string | The output message generated by the module. Returned: always Sample: `"UserProfileProvider created successfully"`

### Authors

- Eike Waldt (@yeoldegrove)