ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-07-07 02:58:54 +00:00
Code Activity

fix docs

Browse source
This commit is contained in:
Felix Grzelka 2026-05-26 13:01:09 +00:00
parent ad73928dd1
commit e569a921f3
1 changed files with 31 additions and 166 deletions
Download patch file Download diff file Expand all files Collapse all files

197
plugins/modules/keycloak_realm_user_info.py
View file

@ -7,220 +7,85 @@
from __future__ import annotations
DOCUMENTATION = r"""
module: keycloak_realm_rolemapping
module: keycloak_realm_users
short_description: Allows administration of Keycloak realm role mappings into groups with the Keycloak API
short_description: Retrieve users from a Keycloak realm using the Keycloak API
version_added: 8.2.0
description:
- This module allows you to add, remove or modify Keycloak realm role mappings into groups with the Keycloak REST API. It
requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite
access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client
definition with the scope tailored to your needs and a user having the expected roles.
- The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
at U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
- Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and are returned that way
by this module. You may pass single values for attributes when calling the module, and this is translated into a list
suitable for the API.
- When updating a group_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API
to translate the name into the role ID.
- This module retrieves all users from a specified Keycloak realm using the Keycloak REST API.
- Access to the REST API is performed via OpenID Connect. The user and client used must have the necessary permissions.
- Authentication can be performed either with username/password or with a token.
- The names of module options are snake_case versions of the camelCase ones found in the Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
attributes:
check_mode:
support: full
diff_mode:
support: full
action_group:
version_added: 10.2.0
support: none
options:
state:
description:
- State of the realm_rolemapping.
- On C(present), the realm_rolemapping is created if it does not yet exist, or updated with the parameters you provide.
- On C(absent), the realm_rolemapping is removed if it exists.
default: 'present'
type: str
choices:
- present
- absent
realm:
type: str
description:
- They Keycloak realm under which this role_representation resides.
- The Keycloak realm from which users should be retrieved.
default: 'master'
group_name:
type: str
description:
- Name of the group to be mapped.
- This parameter is required (can be replaced by gid for less API call).
parents:
type: list
description:
- List of parent groups for the group to handle sorted top to bottom.
- Set this if your group is a subgroup and you do not provide the GID in O(gid).
elements: dict
suboptions:
id:
type: str
description:
- Identify parent by ID.
- Needs less API calls than using O(parents[].name).
- A deep parent chain can be started at any point when first given parent is given as ID.
- Note that in principle both ID and name can be specified at the same time but current implementation only always
use just one of them, with ID being preferred.
name:
type: str
description:
- Identify parent by name.
- Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
- When giving a parent chain with only names it must be complete up to the top.
- Note that in principle both ID and name can be specified at the same time but current implementation only always
use just one of them, with ID being preferred.
gid:
type: str
description:
- ID of the group to be mapped.
- This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API
calls required.
roles:
description:
- Roles to be mapped to the group.
type: list
elements: dict
suboptions:
name:
type: str
description:
- Name of the role_representation.
- This parameter is required only when creating or updating the role_representation.
id:
type: str
description:
- The unique identifier for this role_representation.
- This parameter is not required for updating or deleting a role_representation but providing it reduces the number
of API calls required.
extends_documentation_fragment:
- community.general._keycloak
- community.general._keycloak.actiongroup_keycloak
- community.general._attributes
author:
- Gaëtan Daubresse (@Gaetan2907)
- Marius Huysamen (@mhuysamen)
- Alexander Groß (@agross)
- Your Name (@yourgithub)
"""
EXAMPLES = r"""
- name: Map a client role to a group, authentication with credentials
community.general.keycloak_realm_rolemapping:
- name: List all users in the "MyCustomRealm" realm using username/password authentication
community.general.keycloak_realm_users:
realm: MyCustomRealm
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
state: present
group_name: group1
roles:
- name: role_name1
id: role_id1
- name: role_name2
id: role_id2
delegate_to: localhost
- name: Map a client role to a group, authentication with token
community.general.keycloak_realm_rolemapping:
- name: List all users in the "MyCustomRealm" realm using a token
community.general.keycloak_realm_users:
realm: MyCustomRealm
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
token: TOKEN
state: present
group_name: group1
roles:
- name: role_name1
id: role_id1
- name: role_name2
id: role_id2
delegate_to: localhost
- name: Map a client role to a subgroup, authentication with token
community.general.keycloak_realm_rolemapping:
realm: MyCustomRealm
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
token: TOKEN
state: present
group_name: subgroup1
parents:
- name: parent-group
roles:
- name: role_name1
id: role_id1
- name: role_name2
id: role_id2
delegate_to: localhost
- name: Unmap realm role from a group
community.general.keycloak_realm_rolemapping:
realm: MyCustomRealm
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
state: absent
group_name: group1
roles:
- name: role_name1
id: role_id1
- name: role_name2
id: role_id2
delegate_to: localhost
"""
RETURN = r"""
msg:
description: Message as to what action was taken.
description: Status message about the action performed.
returned: always
type: str
sample: "Role role1 assigned to group group1."
sample: "Got users in realm MyCustomRealm"
proposed:
description: Representation of proposed client role mapping.
users:
description: List of users in the specified realm.
returned: always
type: dict
sample: {"clientId": "test"}
type: list
elements: dict
sample:
- id: "1234-5678-90"
username: "user1"
email: "user1@example.com"
- id: "2345-6789-01"
username: "user2"
email: "user2@example.com"
existing:
description:
- Representation of existing client role mapping.
- The sample is truncated.
changed:
description: Indicates if any changes were made (always False, as this is a read-only operation).
returned: always
type: dict
sample:
{
"adminUrl": "http://www.example.com/admin_url",
"attributes": {
"request.object.signature.alg": "RS256"
}
}
end_state:
description:
- Representation of client role mapping after module execution.
- The sample is truncated.
returned: on success
type: dict
sample:
{
"adminUrl": "http://www.example.com/admin_url",
"attributes": {
"request.object.signature.alg": "RS256"
}
}
type: bool
sample: false
"""
from ansible.module_utils.basic import AnsibleModule