From e569a921f3cec9d966515baf2447e1cc6142115a Mon Sep 17 00:00:00 2001 From: Felix Grzelka Date: Tue, 26 May 2026 13:01:09 +0000 Subject: [PATCH] fix docs --- plugins/modules/keycloak_realm_user_info.py | 197 +++----------------- 1 file changed, 31 insertions(+), 166 deletions(-) diff --git a/plugins/modules/keycloak_realm_user_info.py b/plugins/modules/keycloak_realm_user_info.py index 5a7edb2357..1ba47ef9f2 100644 --- a/plugins/modules/keycloak_realm_user_info.py +++ b/plugins/modules/keycloak_realm_user_info.py @@ -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