community.general.keycloak_userprofile module – Allows managing Keycloak User Profiles

Note

This module is part of the community.general collection (version 9.5.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_userprofile.

New in community.general 9.4.0

Synopsis

• This module allows you to create, update, or delete Keycloak User Profiles via 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 will be 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"]
validations dictionary	The validations to be applied to the attribute.
email dictionary	The email 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.
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 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"
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)
state string	State of the User Profile provider. On present, the User Profile provider will be created if it does not yet exist, or updated with the parameters you provide. On absent, the User Profile provider will be removed if it exists. Choices: "present" ← (default) "absent"
token string added in community.general 3.0.0	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
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
  community.general.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
          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
  community.general.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
  community.general.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
  community.general.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 Sample: {"...": null}
msg string	The output message generated by the module. Returned: always Sample: "UserProfileProvider created successfully"

Authors

• Eike Waldt (@yeoldegrove)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication