keycloak_user_rolemapping: Provide an example using realm roles

datahattrick commented 1 year ago

Summary

When going over the keycloak user role mapping module, it was not immediately clear reading the documentation that by not specifying a client_id or cid variables, that it would then map realm roles. To help clarify it would be helpful to have an example in the documentation such as:

- name: Map a realm role to a user, authentication with credentials
  community.general.keycloak_user_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: present
    user_id: user1Id
    roles:
      - name: realm_role_name1
        id: realm_role_id1
      - name: realm_role_name2
        id: realm_role_id2
  delegate_to: localhost

This will help make it clear that by skipping the cid, client_id variables it will look at realm roles. Another suggestion would be making it clearer in the description of cid, client_id or the roles description itself.

Issue Type

Documentation Report

Component Name

keycloak_user_rolemapping

Ansible Version

$ ansible --version

Community.general Version

$ ansible-galaxy collection list community.general

Collection        Version
----------------- -------
community.general 7.2.0

Configuration

$ ansible-config dump --only-changed

OS / Environment

No response

Additional Information

When this improvement is applied, it will make the use of keycloak_user_rolemapping more clear in its use and that it is capable of assigning realm roles.