From 27c34b150f86793d06d04507e3c46d3feef254b6 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 7 Jan 2025 09:31:59 +1300 Subject: [PATCH] jk*: style adjustments (#9529) * jk*: style adjustments * Apply suggestions from code review * fix return yamls --- plugins/modules/jenkins_build.py | 2 +- plugins/modules/jenkins_job.py | 2 +- .../keycloak_authz_authorization_scope.py | 15 +- .../modules/keycloak_authz_custom_policy.py | 16 +- plugins/modules/keycloak_authz_permission.py | 26 +-- .../modules/keycloak_authz_permission_info.py | 15 +- plugins/modules/keycloak_client.py | 154 ++++++++++-------- .../modules/keycloak_client_rolemapping.py | 46 +++--- plugins/modules/keycloak_client_rolescope.py | 15 +- plugins/modules/keycloak_clientscope.py | 40 ++--- plugins/modules/keycloak_clientscope_type.py | 7 +- plugins/modules/keycloak_clientsecret_info.py | 17 +- .../keycloak_clientsecret_regenerate.py | 19 ++- plugins/modules/keycloak_clienttemplate.py | 58 ++++--- plugins/modules/keycloak_component.py | 13 +- plugins/modules/keycloak_component_info.py | 6 +- plugins/modules/keycloak_group.py | 49 +++--- plugins/modules/keycloak_identity_provider.py | 28 ++-- plugins/modules/keycloak_realm.py | 18 +- plugins/modules/keycloak_realm_info.py | 9 +- plugins/modules/keycloak_realm_key.py | 61 ++++--- .../keycloak_realm_keys_metadata_info.py | 4 +- plugins/modules/keycloak_realm_rolemapping.py | 39 +++-- plugins/modules/keycloak_role.py | 26 +-- plugins/modules/keycloak_user_federation.py | 119 ++++++++------ plugins/modules/keycloak_user_rolemapping.py | 36 ++-- plugins/modules/keycloak_userprofile.py | 17 +- plugins/modules/keyring.py | 4 +- plugins/modules/keyring_info.py | 4 +- plugins/modules/kibana_plugin.py | 2 +- plugins/modules/krb_ticket.py | 20 ++- 31 files changed, 487 insertions(+), 400 deletions(-) diff --git a/plugins/modules/jenkins_build.py b/plugins/modules/jenkins_build.py index a909eab690..cec8fcc490 100644 --- a/plugins/modules/jenkins_build.py +++ b/plugins/modules/jenkins_build.py @@ -126,7 +126,7 @@ user: type: str sample: admin url: - description: Url to connect to the Jenkins server. + description: URL to connect to the Jenkins server. returned: success type: str sample: https://jenkins.mydomain.com diff --git a/plugins/modules/jenkins_job.py b/plugins/modules/jenkins_job.py index f539e569e8..93d922ed22 100644 --- a/plugins/modules/jenkins_job.py +++ b/plugins/modules/jenkins_job.py @@ -154,7 +154,7 @@ user: type: str sample: admin url: - description: Url to connect to the Jenkins server. + description: URL to connect to the Jenkins server. returned: success type: str sample: https://jenkins.mydomain.com diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py index cd1ff57afc..16f4149d68 100644 --- a/plugins/modules/keycloak_authz_authorization_scope.py +++ b/plugins/modules/keycloak_authz_authorization_scope.py @@ -17,13 +17,14 @@ short_description: Allows administration of Keycloak client authorization scopes version_added: 6.6.0 description: - - This module allows the administration of Keycloak client Authorization Scopes using the Keycloak REST API. Authorization Scopes are only available - if a client has Authorization enabled. - - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 realm 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 options used by Keycloak. The Authorization Services paths and payloads - have not officially been documented by the Keycloak project. U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). + - This module allows the administration of Keycloak client Authorization Scopes using the Keycloak REST API. Authorization + Scopes are only available if a client has Authorization enabled. + - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 + realm 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 options used by Keycloak. The Authorization Services + paths and payloads have not officially been documented by the Keycloak project. + U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_authz_custom_policy.py b/plugins/modules/keycloak_authz_custom_policy.py index ef6c9b0973..c20adbc03f 100644 --- a/plugins/modules/keycloak_authz_custom_policy.py +++ b/plugins/modules/keycloak_authz_custom_policy.py @@ -17,13 +17,15 @@ short_description: Allows administration of Keycloak client custom Javascript po version_added: 7.5.0 description: - - This module allows the administration of Keycloak client custom Javascript using the Keycloak REST API. Custom Javascript policies are only - available if a client has Authorization enabled and if they have been deployed to the Keycloak server as JAR files. - - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 realm 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 options used by Keycloak. The Authorization Services paths and payloads - have not officially been documented by the Keycloak project. U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). + - This module allows the administration of Keycloak client custom Javascript using the Keycloak REST API. Custom Javascript + policies are only available if a client has Authorization enabled and if they have been deployed to the Keycloak server + as JAR files. + - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 + realm 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 options used by Keycloak. The Authorization Services + paths and payloads have not officially been documented by the Keycloak project. + U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_authz_permission.py b/plugins/modules/keycloak_authz_permission.py index e4ab9fe14d..aee1b1a50f 100644 --- a/plugins/modules/keycloak_authz_permission.py +++ b/plugins/modules/keycloak_authz_permission.py @@ -17,18 +17,20 @@ version_added: 7.2.0 short_description: Allows administration of Keycloak client authorization permissions using Keycloak API description: - - This module allows the administration of Keycloak client authorization permissions using the Keycloak REST API. Authorization permissions are - only available if a client has Authorization enabled. - - There are some peculiarities in JSON paths and payloads for authorization permissions. In particular POST and PUT operations are targeted - at permission endpoints, whereas GET requests go to policies endpoint. To make matters more interesting the JSON responses from GET requests - return data in a different format than what is expected for POST and PUT. The end result is that it is not possible to detect changes to things - like policies, scopes or resources - at least not without a large number of additional API calls. Therefore this module always updates authorization - permissions instead of attempting to determine if changes are truly needed. - - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 realm 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 options used by Keycloak. The Authorization Services paths and payloads - have not officially been documented by the Keycloak project. U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). + - This module allows the administration of Keycloak client authorization permissions using the Keycloak REST API. Authorization + permissions are only available if a client has Authorization enabled. + - There are some peculiarities in JSON paths and payloads for authorization permissions. In particular POST and PUT operations + are targeted at permission endpoints, whereas GET requests go to policies endpoint. To make matters more interesting the + JSON responses from GET requests return data in a different format than what is expected for POST and PUT. The end result + is that it is not possible to detect changes to things like policies, scopes or resources - at least not without a large + number of additional API calls. Therefore this module always updates authorization permissions instead of attempting to + determine if changes are truly needed. + - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 + realm 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 options used by Keycloak. The Authorization Services + paths and payloads have not officially been documented by the Keycloak project. + U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_authz_permission_info.py b/plugins/modules/keycloak_authz_permission_info.py index 6851abb311..b57b7675a0 100644 --- a/plugins/modules/keycloak_authz_permission_info.py +++ b/plugins/modules/keycloak_authz_permission_info.py @@ -17,13 +17,14 @@ version_added: 7.2.0 short_description: Query Keycloak client authorization permissions information description: - - This module allows querying information about Keycloak client authorization permissions from the resources endpoint using the Keycloak REST - API. Authorization permissions are only available if a client has Authorization enabled. - - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 realm 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 options used by Keycloak. The Authorization Services paths and payloads - have not officially been documented by the Keycloak project. U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). + - This module allows querying information about Keycloak client authorization permissions from the resources endpoint using + the Keycloak REST API. Authorization permissions are only available if a client has Authorization enabled. + - This module requires access to the REST API using OpenID Connect; the user connecting and the realm 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 + realm 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 options used by Keycloak. The Authorization Services + paths and payloads have not officially been documented by the Keycloak project. + U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/). attributes: action_group: version_added: 10.2.0 diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index 6b19711e3d..68696fd404 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -15,14 +15,16 @@ short_description: Allows administration of Keycloak clients using Keycloak API description: - - This module allows the administration of Keycloak clients using 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/8.0/rest-api/index.html). - Aliases are provided so camelCased versions can be used as well. - - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect client for instance and - the other way around. Be careful. If you do not specify a setting, usually a sensible default is chosen. + - This module allows the administration of Keycloak clients using 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/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used + as well. + - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect + client for instance and the other way around. Be careful. If you do not specify a setting, usually a sensible default + is chosen. attributes: check_mode: support: full @@ -49,15 +51,16 @@ options: client_id: description: - - Client id of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or O(id) is required. If you specify - both, O(id) takes precedence. This is C(clientId) in the Keycloak REST API. + - Client ID of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or O(id) is required. + If you specify both, O(id) takes precedence. This is C(clientId) in the Keycloak REST API. aliases: - clientId type: str id: description: - - Id of client to be worked on. This is usually an UUID. Either this or O(client_id) is required. If you specify both, this takes precedence. + - ID of client to be worked on. This is usually an UUID. Either this or O(client_id) is required. If you specify both, + this takes precedence. type: str name: @@ -86,7 +89,8 @@ options: base_url: description: - - Default URL to use when the auth server needs to redirect or link back to the client This is C(baseUrl) in the Keycloak REST API. + - Default URL to use when the auth server needs to redirect or link back to the client This is C(baseUrl) in the Keycloak + REST API. aliases: - baseUrl type: str @@ -98,11 +102,11 @@ options: client_authenticator_type: description: - - How do clients authenticate with the auth server? Either V(client-secret), V(client-jwt), or V(client-x509) can be chosen. When using - V(client-secret), the module parameter O(secret) can set it, for V(client-jwt), you can use the keys C(use.jwks.url), C(jwks.url), and - C(jwt.credential.certificate) in the O(attributes) module parameter to configure its behavior. For V(client-x509) you can use the keys - C(x509.allow.regex.pattern.comparison) and C(x509.subjectdn) in the O(attributes) module parameter to configure which certificate(s) to - accept. + - How do clients authenticate with the auth server? Either V(client-secret), V(client-jwt), or V(client-x509) can be + chosen. When using V(client-secret), the module parameter O(secret) can set it, for V(client-jwt), you can use the + keys C(use.jwks.url), C(jwks.url), and C(jwt.credential.certificate) in the O(attributes) module parameter to configure + its behavior. For V(client-x509) you can use the keys C(x509.allow.regex.pattern.comparison) and C(x509.subjectdn) + in the O(attributes) module parameter to configure which certificate(s) to accept. - This is C(clientAuthenticatorType) in the Keycloak REST API. choices: ['client-secret', 'client-jwt', 'client-x509'] aliases: @@ -111,22 +115,23 @@ options: secret: description: - - When using O(client_authenticator_type=client-secret) (the default), you can specify a secret here (otherwise one will be generated if - it does not exit). If changing this secret, the module will not register a change currently (but the changed secret will be saved). + - When using O(client_authenticator_type=client-secret) (the default), you can specify a secret here (otherwise one + will be generated if it does not exit). If changing this secret, the module will not register a change currently (but + the changed secret will be saved). type: str registration_access_token: description: - - The registration access token provides access for clients to the client registration service. This is C(registrationAccessToken) in the - Keycloak REST API. + - The registration access token provides access for clients to the client registration service. This is C(registrationAccessToken) + in the Keycloak REST API. aliases: - registrationAccessToken type: str default_roles: description: - - List of default roles for this client. If the client roles referenced do not exist yet, they will be created. This is C(defaultRoles) in - the Keycloak REST API. + - List of default roles for this client. If the client roles referenced do not exist yet, they will be created. This + is C(defaultRoles) in the Keycloak REST API. aliases: - defaultRoles type: list @@ -150,7 +155,8 @@ options: not_before: description: - - Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is C(notBefore) in the Keycloak REST API. + - Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is C(notBefore) in the + Keycloak REST API. type: int aliases: - notBefore @@ -171,36 +177,40 @@ options: standard_flow_enabled: description: - - Enable standard flow for this client or not (OpenID connect). This is C(standardFlowEnabled) in the Keycloak REST API. + - Enable standard flow for this client or not (OpenID connect). This is C(standardFlowEnabled) in the Keycloak REST + API. aliases: - standardFlowEnabled type: bool implicit_flow_enabled: description: - - Enable implicit flow for this client or not (OpenID connect). This is C(implicitFlowEnabled) in the Keycloak REST API. + - Enable implicit flow for this client or not (OpenID connect). This is C(implicitFlowEnabled) in the Keycloak REST + API. aliases: - implicitFlowEnabled type: bool direct_access_grants_enabled: description: - - Are direct access grants enabled for this client or not (OpenID connect). This is C(directAccessGrantsEnabled) in the Keycloak REST API. + - Are direct access grants enabled for this client or not (OpenID connect). This is C(directAccessGrantsEnabled) in + the Keycloak REST API. aliases: - directAccessGrantsEnabled type: bool service_accounts_enabled: description: - - Are service accounts enabled for this client or not (OpenID connect). This is C(serviceAccountsEnabled) in the Keycloak REST API. + - Are service accounts enabled for this client or not (OpenID connect). This is C(serviceAccountsEnabled) in the Keycloak + REST API. aliases: - serviceAccountsEnabled type: bool authorization_services_enabled: description: - - Are authorization services enabled for this client or not (OpenID connect). This is C(authorizationServicesEnabled) in the Keycloak REST - API. + - Are authorization services enabled for this client or not (OpenID connect). This is C(authorizationServicesEnabled) + in the Keycloak REST API. aliases: - authorizationServicesEnabled type: bool @@ -243,37 +253,40 @@ options: registered_nodes: description: - - Dict of registered cluster nodes (with C(nodename) as the key and last registration time as the value). This is C(registeredNodes) in the - Keycloak REST API. + - Dict of registered cluster nodes (with C(nodename) as the key and last registration time as the value). This is C(registeredNodes) + in the Keycloak REST API. type: dict aliases: - registeredNodes client_template: description: - - Client template to use for this client. If it does not exist this field will silently be dropped. This is C(clientTemplate) in the Keycloak - REST API. + - Client template to use for this client. If it does not exist this field will silently be dropped. This is C(clientTemplate) + in the Keycloak REST API. type: str aliases: - clientTemplate use_template_config: description: - - Whether or not to use configuration from the O(client_template). This is C(useTemplateConfig) in the Keycloak REST API. + - Whether or not to use configuration from the O(client_template). This is C(useTemplateConfig) in the Keycloak REST + API. aliases: - useTemplateConfig type: bool use_template_scope: description: - - Whether or not to use scope configuration from the O(client_template). This is C(useTemplateScope) in the Keycloak REST API. + - Whether or not to use scope configuration from the O(client_template). This is C(useTemplateScope) in the Keycloak + REST API. aliases: - useTemplateScope type: bool use_template_mappers: description: - - Whether or not to use mapper configuration from the O(client_template). This is C(useTemplateMappers) in the Keycloak REST API. + - Whether or not to use mapper configuration from the O(client_template). This is C(useTemplateMappers) in the Keycloak + REST API. aliases: - useTemplateMappers type: bool @@ -295,9 +308,9 @@ options: authorization_settings: description: - - A data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs at - U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation). - This is C(authorizationSettings) in the Keycloak REST API. + - A data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs + at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation). This is C(authorizationSettings) + in the Keycloak REST API. type: dict aliases: - authorizationSettings @@ -310,13 +323,15 @@ options: browser: description: - Flow ID of the browser authentication flow. - - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are mutually exclusive. + - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are + mutually exclusive. type: str browser_name: description: - Flow name of the browser authentication flow. - - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are mutually exclusive. + - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are + mutually exclusive. aliases: - browserName type: str @@ -325,8 +340,8 @@ options: direct_grant: description: - Flow ID of the direct grant authentication flow. - - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name) are mutually - exclusive. + - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name) + are mutually exclusive. aliases: - directGrant type: str @@ -334,8 +349,8 @@ options: direct_grant_name: description: - Flow name of the direct grant authentication flow. - - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name) are mutually - exclusive. + - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name) + are mutually exclusive. aliases: - directGrantName type: str @@ -398,8 +413,8 @@ options: protocolMapper: description: - - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may - be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' + - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide + since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' - V(docker-v2-allow-all-mapper). - V(oidc-address-mapper). - V(oidc-full-name-mapper). @@ -422,29 +437,30 @@ options: - V(saml-user-attribute-mapper). - V(saml-user-property-mapper). - V(saml-user-session-note-mapper). - - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers - and looking under 'protocol-mapper'. + - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to + Server Info -> Providers and looking under 'protocol-mapper'. type: str config: description: - - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of - O(protocol_mappers[].protocolMapper) - and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest - to obtain valid config values by dumping an already-existing protocol mapper configuration through check-mode in the RV(existing) - field. + - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value + of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its + parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: description: - - A dict of further attributes for this client. This can contain various configuration settings; an example is given in the examples section. - While an exhaustive list of permissible options is not available; possible options as of Keycloak 3.4 are listed below. The Keycloak API - does not validate whether a given option is appropriate for the protocol used; if specified anyway, Keycloak will simply not use it. + - A dict of further attributes for this client. This can contain various configuration settings; an example is given + in the examples section. While an exhaustive list of permissible options is not available; possible options as of + Keycloak 3.4 are listed below. The Keycloak API does not validate whether a given option is appropriate for the protocol + used; if specified anyway, Keycloak will simply not use it. type: dict suboptions: saml.authnstatement: description: - - For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included in the login response. + - For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included + in the login response. saml.client.signature: description: - For SAML clients, boolean specifying whether a client signature is required and validated. @@ -462,8 +478,8 @@ options: - Boolean specifying whether SAML documents should be signed by the realm. saml.server.signature.keyinfo.ext: description: - - For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion of the signing key - id in the SAML Extensions element. + - For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion + of the signing key ID in the SAML Extensions element. saml.signature.algorithm: description: - Signature algorithm used to sign SAML documents. One of V(RSA_SHA256), V(RSA_SHA1), V(RSA_SHA512), or V(DSA_SHA1). @@ -481,28 +497,30 @@ options: - SAML Redirect Binding URL for the client's assertion consumer service (login responses). saml_force_name_id_format: description: - - For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured one instead. + - For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured + one instead. saml_name_id_format: description: - For SAML clients, the NameID format to use (one of V(username), V(email), V(transient), or V(persistent)). saml_signature_canonicalization_method: description: - - SAML signature canonicalization method. This is one of four values, namely V(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE, - V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS, V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) + - SAML signature canonicalization method. This is one of four values, namely V(http://www.w3.org/2001/10/xml-exc-c14n#) + for EXCLUSIVE, V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS, + V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS. saml_single_logout_service_url_post: description: - - SAML POST binding url for the client's single logout service. + - SAML POST binding URL for the client's single logout service. saml_single_logout_service_url_redirect: description: - - SAML redirect binding url for the client's single logout service. + - SAML redirect binding URL for the client's single logout service. user.info.response.signature.alg: description: - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of V(RS256) or V(unsigned). request.object.signature.alg: description: - - For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One of V(any), V(none), - V(RS256). + - For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One + of V(any), V(none), V(RS256). use.jwks.url: description: - For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client public keys. diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py index 23dad803d7..dff8c633b6 100644 --- a/plugins/modules/keycloak_client_rolemapping.py +++ b/plugins/modules/keycloak_client_rolemapping.py @@ -16,16 +16,17 @@ short_description: Allows administration of Keycloak client_rolemapping with the version_added: 3.5.0 description: - - This module allows you to add, remove or modify Keycloak client_rolemapping 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/8.0/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. - - When updating a client_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 allows you to add, remove or modify Keycloak client_rolemapping 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/8.0/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. + - When updating a client_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. attributes: check_mode: support: full @@ -38,7 +39,8 @@ options: state: description: - State of the client_rolemapping. - - On V(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. + - On V(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you + provide. - On V(absent), the client_rolemapping will be removed if it exists. default: 'present' type: str @@ -71,21 +73,22 @@ options: - 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. + - 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. + - 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 will reduce the number of API calls required. + - ID of the group to be mapped. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. client_id: type: str description: @@ -94,8 +97,9 @@ options: cid: type: str description: - - Id of the client to be mapped. - - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of API calls required. + - ID of the client to be mapped. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. roles: description: - Roles to be mapped to the group. @@ -111,8 +115,8 @@ options: 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 will reduce the number of API calls - required. + - This parameter is not required for updating or deleting a role_representation but providing it will reduce the + number of API calls required. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak diff --git a/plugins/modules/keycloak_client_rolescope.py b/plugins/modules/keycloak_client_rolescope.py index ff91a0fe78..7c87c0664c 100644 --- a/plugins/modules/keycloak_client_rolescope.py +++ b/plugins/modules/keycloak_client_rolescope.py @@ -11,17 +11,20 @@ __metaclass__ = type DOCUMENTATION = r""" module: keycloak_client_rolescope -short_description: Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other specific client applications +short_description: Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other + specific client applications version_added: 8.6.0 description: - - This module allows you to add or remove Keycloak roles from clients scope using 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. + - This module allows you to add or remove Keycloak roles from clients scope using 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. - Client O(client_id) must have O(community.general.keycloak_client#module:full_scope_allowed) set to V(false). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py index ed82e0c0f7..b36c390ae1 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -16,15 +16,17 @@ short_description: Allows administration of Keycloak client_scopes using Keycloa version_added: 3.4.0 description: - - This module allows you to add, remove or modify Keycloak client_scopes using 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/8.0/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. - - When updating a client_scope, where possible provide the client_scope ID to the module. This removes a lookup to the API to translate the - name into the client_scope ID. + - This module allows you to add, remove or modify Keycloak client_scopes using 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/8.0/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. + - When updating a client_scope, where possible provide the client_scope ID to the module. This removes a lookup to the API + to translate the name into the client_scope ID. attributes: check_mode: support: full @@ -60,7 +62,8 @@ options: type: str description: - The unique identifier for this client_scope. - - This parameter is not required for updating or deleting a client_scope but providing it will reduce the number of API calls required. + - This parameter is not required for updating or deleting a client_scope but providing it will reduce the number of + API calls required. description: type: str description: @@ -91,8 +94,8 @@ options: protocolMapper: description: - - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may - be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' + - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide + since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' - V(docker-v2-allow-all-mapper). - V(oidc-address-mapper). - V(oidc-full-name-mapper). @@ -115,8 +118,8 @@ options: - V(saml-user-attribute-mapper). - V(saml-user-property-mapper). - V(saml-user-session-note-mapper). - - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers - and looking under 'protocol-mapper'. + - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to + Server Info -> Providers and looking under 'protocol-mapper'. type: str name: @@ -131,11 +134,10 @@ options: config: description: - - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of - O(protocol_mappers[].protocolMapper) - and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest - to obtain valid config values by dumping an already-existing protocol mapper configuration through check-mode in the RV(existing) - return value. + - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value + of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its + parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing + protocol mapper configuration through check-mode in the RV(existing) return value. type: dict attributes: diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index 48d57bcc46..3923d5fb43 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -17,9 +17,10 @@ short_description: Set the type of aclientscope in realm or client using Keycloa version_added: 6.6.0 description: - - This module allows you to set the type (optional, default) of clientscopes using 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. + - This module allows you to set the type (optional, default) of clientscopes using 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. attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py index d0f6297037..da07d03248 100644 --- a/plugins/modules/keycloak_clientsecret_info.py +++ b/plugins/modules/keycloak_clientsecret_info.py @@ -17,12 +17,14 @@ short_description: Retrieve client secret using Keycloak API version_added: 6.1.0 description: - - This module allows you to get a Keycloak client secret using 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. - - When retrieving a new client secret, where possible provide the client's O(id) (not O(client_id)) to the module. This removes a lookup to - the API to translate the O(client_id) into the client ID. - - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to the task.' + - This module allows you to get a Keycloak client secret using 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. + - When retrieving a new client secret, where possible provide the client's O(id) (not O(client_id)) to the module. This + removes a lookup to the API to translate the O(client_id) into the client ID. + - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to + the task.' attributes: action_group: version_added: 10.2.0 @@ -37,7 +39,8 @@ options: id: description: - The unique identifier for this client. - - This parameter is not required for getting or generating a client secret but providing it will reduce the number of API calls required. + - This parameter is not required for getting or generating a client secret but providing it will reduce the number of + API calls required. type: str client_id: diff --git a/plugins/modules/keycloak_clientsecret_regenerate.py b/plugins/modules/keycloak_clientsecret_regenerate.py index 4bd48e90ad..bb449abc10 100644 --- a/plugins/modules/keycloak_clientsecret_regenerate.py +++ b/plugins/modules/keycloak_clientsecret_regenerate.py @@ -17,12 +17,14 @@ short_description: Regenerate Keycloak client secret using Keycloak API version_added: 6.1.0 description: - - This module allows you to regenerate a Keycloak client secret using 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. - - When regenerating a client secret, where possible provide the client's id (not client_id) to the module. This removes a lookup to the API - to translate the client_id into the client ID. - - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to the task.' + - This module allows you to regenerate a Keycloak client secret using 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. + - When regenerating a client secret, where possible provide the client's ID (not client_id) to the module. This removes + a lookup to the API to translate the client_id into the client ID. + - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to + the task.' attributes: check_mode: support: full @@ -41,12 +43,13 @@ options: id: description: - The unique identifier for this client. - - This parameter is not required for getting or generating a client secret but providing it will reduce the number of API calls required. + - This parameter is not required for getting or generating a client secret but providing it will reduce the number of + API calls required. type: str client_id: description: - - The client_id of the client. Passing this instead of id results in an extra API call. + - The client_id of the client. Passing this instead of ID results in an extra API call. aliases: - clientId type: str diff --git a/plugins/modules/keycloak_clienttemplate.py b/plugins/modules/keycloak_clienttemplate.py index bfd138c3f2..66e96f5a50 100644 --- a/plugins/modules/keycloak_clienttemplate.py +++ b/plugins/modules/keycloak_clienttemplate.py @@ -14,13 +14,15 @@ module: keycloak_clienttemplate short_description: Allows administration of Keycloak client templates using Keycloak API description: - - This module allows the administration of Keycloak client templates using 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/8.0/rest-api/index.html). - - The Keycloak API does not always enforce for only sensible settings to be used -- you can set SAML-specific settings on an OpenID Connect - client for instance and the other way around. Be careful. If you do not specify a setting, usually a sensible default is chosen. + - This module allows the administration of Keycloak client templates using 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/8.0/rest-api/index.html). + - The Keycloak API does not always enforce for only sensible settings to be used -- you can set SAML-specific settings on + an OpenID Connect client for instance and the other way around. Be careful. If you do not specify a setting, usually a + sensible default is chosen. attributes: check_mode: support: full @@ -41,7 +43,7 @@ options: id: description: - - Id of client template to be worked on. This is usually a UUID. + - ID of client template to be worked on. This is usually a UUID. type: str realm: @@ -69,12 +71,14 @@ options: full_scope_allowed: description: - - Is the "Full Scope Allowed" feature set for this client template or not. This is C(fullScopeAllowed) in the Keycloak REST API. + - Is the "Full Scope Allowed" feature set for this client template or not. This is C(fullScopeAllowed) in the Keycloak + REST API. type: bool protocol_mappers: description: - - A list of dicts defining protocol mappers for this client template. This is C(protocolMappers) in the Keycloak REST API. + - A list of dicts defining protocol mappers for this client template. This is C(protocolMappers) in the Keycloak REST + API. type: list elements: dict suboptions: @@ -106,8 +110,8 @@ options: protocolMapper: description: - - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may - be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' + - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide + since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:' - V(docker-v2-allow-all-mapper). - V(oidc-address-mapper). - V(oidc-full-name-mapper). @@ -130,31 +134,29 @@ options: - V(saml-user-attribute-mapper). - V(saml-user-property-mapper). - V(saml-user-session-note-mapper). - - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers - and looking under 'protocol-mapper'. + - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to + Server Info -> Providers and looking under 'protocol-mapper'. type: str config: description: - - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of - O(protocol_mappers[].protocolMapper) - and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest - to obtain valid config values by dumping an already-existing protocol mapper configuration through check-mode in the RV(existing) - field. + - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value + of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its + parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: description: - - A dict of further attributes for this client template. This can contain various configuration settings, though in the default installation - of Keycloak as of 3.4, none are documented or known, so this is usually empty. + - A dict of further attributes for this client template. This can contain various configuration settings, though in + the default installation of Keycloak as of 3.4, none are documented or known, so this is usually empty. type: dict notes: - The Keycloak REST API defines further fields (namely C(bearerOnly), C(consentRequired), C(standardFlowEnabled), C(implicitFlowEnabled), - C(directAccessGrantsEnabled), - C(serviceAccountsEnabled), C(publicClient), and C(frontchannelLogout)) which, while available with keycloak_client, do not have any effect - on Keycloak client-templates and are discarded if supplied with an API request changing client-templates. As such, they are not available - through this module. + C(directAccessGrantsEnabled), C(serviceAccountsEnabled), C(publicClient), and C(frontchannelLogout)) which, while available + with keycloak_client, do not have any effect on Keycloak client-templates and are discarded if supplied with an API request + changing client-templates. As such, they are not available through this module. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak @@ -242,13 +244,15 @@ existing: description: Representation of existing client template (sample is truncated). returned: always type: dict - sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"} + sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", + "protocol": "saml"} end_state: description: Representation of client template after module execution (sample is truncated). returned: on success type: dict - sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"} + sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", + "protocol": "saml"} """ from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \ diff --git a/plugins/modules/keycloak_component.py b/plugins/modules/keycloak_component.py index 2b402ddb62..5c7e3cd56b 100644 --- a/plugins/modules/keycloak_component.py +++ b/plugins/modules/keycloak_component.py @@ -16,12 +16,13 @@ short_description: Allows administration of Keycloak components using Keycloak A version_added: 10.0.0 description: - - This module allows the administration of Keycloak components using the Keycloak REST API. It requires access to the REST API using OpenID Connect; - the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, C(admin-cli) and an - C(admin) user would work, as would a separate realm 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/latest/rest-api/index.html). - Aliases are provided so camelCased versions can be used as well. + - This module allows the administration of Keycloak components using the Keycloak REST API. It requires access to the REST + API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default + Keycloak installation, C(admin-cli) and an C(admin) user would work, as would a separate realm 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/latest/rest-api/index.html). Aliases are provided so camelCased versions can be + used as well. attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_component_info.py b/plugins/modules/keycloak_component_info.py index a1f2c1f0ef..79a6d58720 100644 --- a/plugins/modules/keycloak_component_info.py +++ b/plugins/modules/keycloak_component_info.py @@ -34,9 +34,8 @@ options: provider_type: description: - Provider type of components. - - 'Examples: V(org.keycloak.storage.UserStorageProvider), - V(org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy), V(org.keycloak.keys.KeyProvider), - V(org.keycloak.userprofile.UserProfileProvider), V(org.keycloak.storage.ldap.mappers.LDAPStorageMapper).' + - 'Examples: V(org.keycloak.storage.UserStorageProvider), V(org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy), + V(org.keycloak.keys.KeyProvider), V(org.keycloak.userprofile.UserProfileProvider), V(org.keycloak.storage.ldap.mappers.LDAPStorageMapper).' type: str parent_id: description: @@ -92,7 +91,6 @@ EXAMPLES = r""" realm: myrealm parent_id: "075ef2fa-19fc-4a6d-bf4c-249f57365fd2" provider_type: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper" - """ RETURN = r""" diff --git a/plugins/modules/keycloak_group.py b/plugins/modules/keycloak_group.py index 796f5fc56f..b6b267e906 100644 --- a/plugins/modules/keycloak_group.py +++ b/plugins/modules/keycloak_group.py @@ -14,15 +14,17 @@ module: keycloak_group short_description: Allows administration of Keycloak groups using Keycloak API description: - - This module allows you to add, remove or modify Keycloak groups using 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/20.0.2/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. - - When updating a group, where possible provide the group ID to the module. This removes a lookup to the API to translate the name into the - group ID. + - This module allows you to add, remove or modify Keycloak groups using 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/20.0.2/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. + - When updating a group, where possible provide the group ID to the module. This removes a lookup to the API to translate + the name into the group ID. attributes: check_mode: support: full @@ -36,8 +38,8 @@ options: description: - State of the group. - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide. - - On V(absent), the group will be removed if it exists. Be aware that absenting a group with subgroups will automatically delete all its - subgroups too. + - On V(absent), the group will be removed if it exists. Be aware that absenting a group with subgroups will automatically + delete all its subgroups too. default: 'present' type: str choices: @@ -59,7 +61,8 @@ options: type: str description: - The unique identifier for this group. - - This parameter is not required for updating or deleting a group but providing it will reduce the number of API calls required. + - This parameter is not required for updating or deleting a group but providing it will reduce the number of API calls + required. attributes: type: dict description: @@ -70,9 +73,10 @@ options: type: list description: - List of parent groups for the group to handle sorted top to bottom. - - Set this to create a group as a subgroup of another group or groups (parents) or when accessing an existing subgroup by name. - - Not necessary to set when accessing an existing subgroup by its C(ID) because in that case the group can be directly queried without necessarily - knowing its parent(s). + - Set this to create a group as a subgroup of another group or groups (parents) or when accessing an existing subgroup + by name. + - Not necessary to set when accessing an existing subgroup by its C(ID) because in that case the group can be directly + queried without necessarily knowing its parent(s). elements: dict suboptions: id: @@ -81,19 +85,19 @@ options: - 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. + - 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. + - 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. notes: - - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the Keycloak API are read-only - for groups. This limitation will be removed in a later version of this module. + - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the + Keycloak API are read-only for groups. This limitation will be removed in a later version of this module. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak @@ -278,7 +282,8 @@ end_state: returned: always sample: [] subGroups: - description: A list of groups that are children of this group. These groups will have the same parameters as documented here. + description: A list of groups that are children of this group. These groups will have the same parameters as documented + here. type: list returned: always clientRoles: diff --git a/plugins/modules/keycloak_identity_provider.py b/plugins/modules/keycloak_identity_provider.py index ee631bf19c..e2c61a4a7a 100644 --- a/plugins/modules/keycloak_identity_provider.py +++ b/plugins/modules/keycloak_identity_provider.py @@ -16,12 +16,12 @@ short_description: Allows administration of Keycloak identity providers using Ke version_added: 3.6.0 description: - - This module allows you to add, remove or modify Keycloak identity providers using 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/15.0/rest-api/index.html). + - This module allows you to add, remove or modify Keycloak identity providers using 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/15.0/rest-api/index.html). attributes: check_mode: support: full @@ -34,7 +34,8 @@ options: state: description: - State of the identity provider. - - On V(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide. + - On V(present), the identity provider will be created if it does not yet exist, or updated with the parameters you + provide. - On V(absent), the identity provider will be removed if it exists. default: 'present' type: str @@ -89,8 +90,8 @@ options: link_only: description: - - If true, users cannot log in through this provider. They can only link to this provider. This is useful if you do not want to allow login - from the provider, but want to integrate with a provider. + - If true, users cannot log in through this provider. They can only link to this provider. This is useful if you do + not want to allow login from the provider, but want to integrate with a provider. aliases: - linkOnly type: bool @@ -125,14 +126,15 @@ options: config: description: - - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id). Examples are - given below for V(oidc) and V(saml). It is easiest to obtain valid config values by dumping an already-existing identity provider configuration - through check-mode in the RV(existing) field. + - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id). + Examples are given below for V(oidc) and V(saml). It is easiest to obtain valid config values by dumping an already-existing + identity provider configuration through check-mode in the RV(existing) field. type: dict suboptions: hide_on_login_page: description: - - If hidden, login with this provider is possible only if requested explicitly, for example using the C(kc_idp_hint) parameter. + - If hidden, login with this provider is possible only if requested explicitly, for example using the C(kc_idp_hint) + parameter. aliases: - hideOnLoginPage type: bool diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py index d2ae4f33c8..7c505d8d37 100644 --- a/plugins/modules/keycloak_realm.py +++ b/plugins/modules/keycloak_realm.py @@ -17,14 +17,16 @@ short_description: Allows administration of Keycloak realm using Keycloak API version_added: 3.0.0 description: - - This module allows the administration of Keycloak realm using the Keycloak REST API. It requires access to the REST API using OpenID Connect; - the user connecting and the realm 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 realm 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/8.0/rest-api/index.html). - Aliases are provided so camelCased versions can be used as well. - - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect client for instance and - also the other way around. B(Be careful). If you do not specify a setting, usually a sensible default is chosen. + - This module allows the administration of Keycloak realm using the Keycloak REST API. It requires access to the REST API + using OpenID Connect; the user connecting and the realm 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 realm 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/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used + as well. + - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect + client for instance and also the other way around. B(Be careful). If you do not specify a setting, usually a sensible + default is chosen. attributes: check_mode: support: full diff --git a/plugins/modules/keycloak_realm_info.py b/plugins/modules/keycloak_realm_info.py index e3e4f08248..838b19513d 100644 --- a/plugins/modules/keycloak_realm_info.py +++ b/plugins/modules/keycloak_realm_info.py @@ -17,10 +17,11 @@ version_added: 4.3.0 description: - This module allows you to get Keycloak realm public information using the Keycloak REST API. - - 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/8.0/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. + - 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/8.0/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. extends_documentation_fragment: - community.general.attributes - community.general.attributes.info_module diff --git a/plugins/modules/keycloak_realm_key.py b/plugins/modules/keycloak_realm_key.py index 0f7c5ae114..425206bf98 100644 --- a/plugins/modules/keycloak_realm_key.py +++ b/plugins/modules/keycloak_realm_key.py @@ -17,17 +17,19 @@ short_description: Allows administration of Keycloak realm keys using Keycloak A version_added: 7.5.0 description: - - This module allows the administration of Keycloak realm keys using the Keycloak REST API. It requires access to the REST API using OpenID Connect; - the user connecting and the realm 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 realm 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/8.0/rest-api/index.html). - Aliases are provided so camelCased versions can be used as well. - - This module is unable to detect changes to the actual cryptographic key after importing it. However, if some other property is changed alongside - the cryptographic key, then the key will also get changed as a side-effect, as the JSON payload needs to include the private key. This can - be considered either a bug or a feature, as the alternative would be to always update the realm key whether it has changed or not. - - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current state of the certificate - to the desired state (which may be empty) is not possible. + - This module allows the administration of Keycloak realm keys using the Keycloak REST API. It requires access to the REST + API using OpenID Connect; the user connecting and the realm 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 realm 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/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used + as well. + - This module is unable to detect changes to the actual cryptographic key after importing it. However, if some other property + is changed alongside the cryptographic key, then the key will also get changed as a side-effect, as the JSON payload needs + to include the private key. This can be considered either a bug or a feature, as the alternative would be to always update + the realm key whether it has changed or not. + - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current + state of the certificate to the desired state (which may be empty) is not possible. attributes: check_mode: support: full @@ -52,9 +54,9 @@ options: required: true force: description: - - Enforce the state of the private key and certificate. This is not automatically the case as this module is unable to determine the current - state of the private key and thus cannot trigger an update based on an actual divergence. That said, a private key update may happen even - if force is false as a side-effect of other changes. + - Enforce the state of the private key and certificate. This is not automatically the case as this module is unable + to determine the current state of the private key and thus cannot trigger an update based on an actual divergence. + That said, a private key update may happen even if force is false as a side-effect of other changes. default: false type: bool parent_id: @@ -76,12 +78,14 @@ options: suboptions: active: description: - - Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the O(state) parameter. + - Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the + O(state) parameter. default: true type: bool enabled: description: - - Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the O(state) parameter. + - Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the + O(state) parameter. default: true type: bool priority: @@ -92,30 +96,33 @@ options: algorithm: description: - Key algorithm. - - The values V(RS384), V(RS512), V(PS256), V(PS384), V(PS512), V(RSA1_5), V(RSA-OAEP), V(RSA-OAEP-256) have been added in community.general - 8.2.0. + - The values V(RS384), V(RS512), V(PS256), V(PS384), V(PS512), V(RSA1_5), V(RSA-OAEP), V(RSA-OAEP-256) have been + added in community.general 8.2.0. default: RS256 choices: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'RSA1_5', 'RSA-OAEP', 'RSA-OAEP-256'] type: str private_key: description: - The private key as an ASCII string. Contents of the key must match O(config.algorithm) and O(provider_id). - - Please note that the module cannot detect whether the private key specified differs from the current state's private key. Use O(force=true) - to force the module to update the private key if you expect it to be updated. + - Please note that the module cannot detect whether the private key specified differs from the current state's private + key. Use O(force=true) to force the module to update the private key if you expect it to be updated. required: true type: str certificate: description: - - A certificate signed with the private key as an ASCII string. Contents of the key must match O(config.algorithm) and O(provider_id). - - If you want Keycloak to automatically generate a certificate using your private key then set this to an empty string. + - A certificate signed with the private key as an ASCII string. Contents of the key must match O(config.algorithm) + and O(provider_id). + - If you want Keycloak to automatically generate a certificate using your private key then set this to an empty + string. required: true type: str notes: - - Current value of the private key cannot be fetched from Keycloak. Therefore comparing its desired state to the current state is not possible. - - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current state of the certificate - to the desired state (which may be empty) is not possible. - - Due to the private key and certificate options the module is B(not fully idempotent). You can use O(force=true) to force the module to always - update if you know that the private key might have changed. + - Current value of the private key cannot be fetched from Keycloak. Therefore comparing its desired state to the current + state is not possible. + - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current + state of the certificate to the desired state (which may be empty) is not possible. + - Due to the private key and certificate options the module is B(not fully idempotent). You can use O(force=true) to force + the module to always update if you know that the private key might have changed. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak diff --git a/plugins/modules/keycloak_realm_keys_metadata_info.py b/plugins/modules/keycloak_realm_keys_metadata_info.py index d116e3435b..f76cabfd36 100644 --- a/plugins/modules/keycloak_realm_keys_metadata_info.py +++ b/plugins/modules/keycloak_realm_keys_metadata_info.py @@ -18,8 +18,8 @@ version_added: 9.3.0 description: - This module allows you to get Keycloak realm keys metadata using the Keycloak REST API. - - 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/latest/rest-api/index.html). + - 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/latest/rest-api/index.html). attributes: action_group: version_added: 10.2.0 diff --git a/plugins/modules/keycloak_realm_rolemapping.py b/plugins/modules/keycloak_realm_rolemapping.py index bed65057a4..4217e7e581 100644 --- a/plugins/modules/keycloak_realm_rolemapping.py +++ b/plugins/modules/keycloak_realm_rolemapping.py @@ -16,16 +16,17 @@ short_description: Allows administration of Keycloak realm role mappings into gr 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 will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be 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 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 will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be 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. attributes: check_mode: support: full @@ -38,7 +39,8 @@ options: state: description: - State of the realm_rolemapping. - - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. + - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you + provide. - On C(absent), the realm_rolemapping will be removed if it exists. default: 'present' type: str @@ -70,21 +72,22 @@ options: - 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. + - 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. + - 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 will reduce the number of API calls required. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. roles: description: - Roles to be mapped to the group. @@ -100,8 +103,8 @@ options: 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 will reduce the number of API calls - required. + - This parameter is not required for updating or deleting a role_representation but providing it will reduce the + number of API calls required. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index 3e7644bf6c..267682d31c 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -16,13 +16,15 @@ short_description: Allows administration of Keycloak roles using Keycloak API version_added: 3.4.0 description: - - This module allows you to add, remove or modify Keycloak roles using 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/8.0/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. + - This module allows you to add, remove or modify Keycloak roles using 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/8.0/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. attributes: check_mode: support: full @@ -62,7 +64,7 @@ options: client_id: type: str description: - - If the role is a client role, the client id under which it resides. + - If the role is a client role, the client ID under which it resides. - If this parameter is absent, the role is considered a realm role. attributes: type: dict @@ -199,15 +201,15 @@ existing: description: Representation of existing role. returned: always type: dict - sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", "description": "My - client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"} + sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", + "description": "My client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"} end_state: description: Representation of role after module execution (sample is truncated). returned: on success type: dict - sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", "description": "My - updated client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"} + sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", + "description": "My updated client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"} """ from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \ diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py index be8b75fc85..a631145600 100644 --- a/plugins/modules/keycloak_user_federation.py +++ b/plugins/modules/keycloak_user_federation.py @@ -16,11 +16,12 @@ short_description: Allows administration of Keycloak user federations using Keyc version_added: 3.7.0 description: - - This module allows you to add, remove or modify Keycloak user federations using 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/20.0.2/rest-api/index.html). + - This module allows you to add, remove or modify Keycloak user federations using 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/20.0.2/rest-api/index.html). attributes: check_mode: support: full @@ -59,8 +60,8 @@ options: provider_id: description: - - Provider for this user federation. Built-in providers are V(ldap), V(kerberos), and V(sssd). Custom user storage providers can also be - used. + - Provider for this user federation. Built-in providers are V(ldap), V(kerberos), and V(sssd). Custom user storage providers + can also be used. aliases: - providerId type: str @@ -90,12 +91,15 @@ options: bind_credential_update_mode: description: - - The value of the config parameter O(config.bindCredential) is redacted in the Keycloak responses. Comparing the redacted value with the - desired value always evaluates to not equal. This means the before and desired states are never equal if the parameter is set. - - Set to V(always) to include O(config.bindCredential) in the comparison of before and desired state. Because of the redacted value returned - by Keycloak the module will always detect a change and make an update if a O(config.bindCredential) value is set. + - The value of the config parameter O(config.bindCredential) is redacted in the Keycloak responses. Comparing the redacted + value with the desired value always evaluates to not equal. This means the before and desired states are never equal + if the parameter is set. + - Set to V(always) to include O(config.bindCredential) in the comparison of before and desired state. Because of the + redacted value returned by Keycloak the module will always detect a change and make an update if a O(config.bindCredential) + value is set. - Set to V(only_indirect) to exclude O(config.bindCredential) when comparing the before state with the desired state. - The value of O(config.bindCredential) will only be updated if there are other changes to the user federation that require an update. + The value of O(config.bindCredential) will only be updated if there are other changes to the user federation that + require an update. type: str default: always choices: @@ -105,9 +109,9 @@ options: config: description: - - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id). Examples are - given below for V(ldap), V(kerberos) and V(sssd). It is easiest to obtain valid config values by dumping an already-existing user federation - configuration through check-mode in the RV(existing) field. + - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id). + Examples are given below for V(ldap), V(kerberos) and V(sssd). It is easiest to obtain valid config values by dumping + an already-existing user federation configuration through check-mode in the RV(existing) field. - The value V(sssd) has been supported since community.general 4.2.0. type: dict suboptions: @@ -131,8 +135,8 @@ options: editMode: description: - - V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced back to LDAP on demand. V(UNSYNCED) means user data - will be imported, but not synced back to LDAP. + - V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced back to LDAP on demand. V(UNSYNCED) + means user data will be imported, but not synced back to LDAP. type: str choices: - READ_ONLY @@ -141,7 +145,8 @@ options: syncRegistrations: description: - - Should newly created users be created within LDAP store? Priority effects which provider is chosen to sync the new user. + - Should newly created users be created within LDAP store? Priority effects which provider is chosen to sync the + new user. default: false type: bool @@ -153,29 +158,31 @@ options: usernameLDAPAttribute: description: - - Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server vendors it can be V(uid). For Active directory - it can be V(sAMAccountName) or V(cn). The attribute should be filled for all LDAP user records you want to import from LDAP to Keycloak. + - Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server vendors it can be V(uid). For + Active directory it can be V(sAMAccountName) or V(cn). The attribute should be filled for all LDAP user records + you want to import from LDAP to Keycloak. type: str rdnLDAPAttribute: description: - - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it is the same as Username LDAP attribute, - however it is not required. For example for Active directory, it is common to use V(cn) as RDN attribute when username attribute might - be V(sAMAccountName). + - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it is the same as Username + LDAP attribute, however it is not required. For example for Active directory, it is common to use V(cn) as RDN + attribute when username attribute might be V(sAMAccountName). type: str uuidLDAPAttribute: description: - - Name of LDAP attribute, which is used as unique object identifier (UUID) for objects in LDAP. For many LDAP server vendors, it is - V(entryUUID); however some are different. For example for Active directory it should be V(objectGUID). If your LDAP server does not - support the notion of UUID, you can use any other attribute that is supposed to be unique among LDAP users in tree. + - Name of LDAP attribute, which is used as unique object identifier (UUID) for objects in LDAP. For many LDAP server + vendors, it is V(entryUUID); however some are different. For example for Active directory it should be V(objectGUID). + If your LDAP server does not support the notion of UUID, you can use any other attribute that is supposed to be + unique among LDAP users in tree. type: str userObjectClasses: description: - - All values of LDAP objectClass attribute for users in LDAP divided by comma. For example V(inetOrgPerson, organizationalPerson). Newly - created Keycloak users will be written to LDAP with all those object classes and existing LDAP user records are found just if they - contain all those object classes. + - All values of LDAP objectClass attribute for users in LDAP divided by comma. For example V(inetOrgPerson, organizationalPerson). + Newly created Keycloak users will be written to LDAP with all those object classes and existing LDAP user records + are found just if they contain all those object classes. type: str connectionUrl: @@ -195,8 +202,8 @@ options: searchScope: description: - - For one level, the search applies only for users in the DNs specified by User DNs. For subtree, the search applies to the whole subtree. - See LDAP documentation for more details. + - For one level, the search applies only for users in the DNs specified by User DNs. For subtree, the search applies + to the whole subtree. See LDAP documentation for more details. default: '1' type: str choices: @@ -205,7 +212,8 @@ options: authType: description: - - Type of the Authentication method used during LDAP Bind operation. It is used in most of the requests sent to the LDAP server. + - Type of the Authentication method used during LDAP Bind operation. It is used in most of the requests sent to + the LDAP server. default: 'none' type: str choices: @@ -230,9 +238,9 @@ options: usePasswordModifyExtendedOp: description: - - Use the LDAPv3 Password Modify Extended Operation (RFC-3062). The password modify extended operation usually requires that LDAP user - already has password in the LDAP server. So when this is used with 'Sync Registrations', it can be good to add also 'Hardcoded LDAP - attribute mapper' with randomly generated initial password. + - Use the LDAPv3 Password Modify Extended Operation (RFC-3062). The password modify extended operation usually requires + that LDAP user already has password in the LDAP server. So when this is used with 'Sync Registrations', it can + be good to add also 'Hardcoded LDAP attribute mapper' with randomly generated initial password. default: false type: bool @@ -250,11 +258,11 @@ options: useTruststoreSpi: description: - - Specifies whether LDAP connection will use the truststore SPI with the truststore configured in standalone.xml/domain.xml. V(always) - means that it will always use it. V(never) means that it will not use it. V(ldapsOnly) means that it will use if your connection URL - use ldaps. - - Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by C(javax.net.ssl.trustStore) - property will be used. + - Specifies whether LDAP connection will use the truststore SPI with the truststore configured in standalone.xml/domain.xml. + V(always) means that it will always use it. V(never) means that it will not use it. V(ldapsOnly) means that it + will use if your connection URL use ldaps. + - Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by + C(javax.net.ssl.trustStore) property will be used. default: ldapsOnly type: str choices: @@ -295,8 +303,8 @@ options: connectionPoolingDebug: description: - - A string that indicates the level of debug output to produce. Example valid values are V(fine) (trace connection creation and removal) - and V(all) (all debugging information). + - A string that indicates the level of debug output to produce. Example valid values are V(fine) (trace connection + creation and removal) and V(all) (all debugging information). type: str connectionPoolingInitSize: @@ -321,13 +329,14 @@ options: connectionPoolingTimeout: description: - - The number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. + - The number of milliseconds that an idle connection may remain in the pool without being closed and removed from + the pool. type: int allowKerberosAuthentication: description: - - Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users will be provisioned from - this LDAP server. + - Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users will + be provisioned from this LDAP server. default: false type: bool @@ -338,16 +347,17 @@ options: krbPrincipalAttribute: description: - - Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after successful Kerberos/SPNEGO - authentication in Keycloak. When this is empty, the LDAP user will be looked based on LDAP username corresponding to the first part - of his Kerberos principal. For instance, for principal C(john@KEYCLOAK.ORG), it will assume that LDAP username is V(john). + - Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after + successful Kerberos/SPNEGO authentication in Keycloak. When this is empty, the LDAP user will be looked based + on LDAP username corresponding to the first part of his Kerberos principal. For instance, for principal C(john@KEYCLOAK.ORG), + it will assume that LDAP username is V(john). type: str version_added: 8.1.0 serverPrincipal: description: - - Full name of server principal for HTTP service including server and domain name. For example V(HTTP/host.foo.org@FOO.ORG). Use V(*) - to accept any service principal in the KeyTab file. + - Full name of server principal for HTTP service including server and domain name. For example V(HTTP/host.foo.org@FOO.ORG). + Use V(*) to accept any service principal in the KeyTab file. type: str keyTab: @@ -362,8 +372,8 @@ options: useKerberosForPasswordAuthentication: description: - - Use Kerberos login module for authenticate username/password against Kerberos server instead of authenticating against LDAP server - with Directory Service API. + - Use Kerberos login module for authenticate username/password against Kerberos server instead of authenticating + against LDAP server with Directory Service API. default: false type: bool @@ -429,8 +439,9 @@ options: referral: description: - - Specifies if LDAP referrals should be followed or ignored. Please note that enabling referrals can slow down authentication as it - allows the LDAP server to decide which other LDAP servers to use. This could potentially include untrusted servers. + - Specifies if LDAP referrals should be followed or ignored. Please note that enabling referrals can slow down authentication + as it allows the LDAP server to decide which other LDAP servers to use. This could potentially include untrusted + servers. type: str choices: - ignore diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py index 319aa5350b..f8690d70c9 100644 --- a/plugins/modules/keycloak_user_rolemapping.py +++ b/plugins/modules/keycloak_user_rolemapping.py @@ -15,15 +15,17 @@ short_description: Allows administration of Keycloak user_rolemapping with the K version_added: 5.7.0 description: - - This module allows you to add, remove or modify Keycloak user_rolemapping 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/8.0/rest-api/index.html). - - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. - You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. - - When updating a user_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 allows you to add, remove or modify Keycloak user_rolemapping 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/8.0/rest-api/index.html). + - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that + way by this module. You may pass single values for attributes when calling the module, and this will be translated into + a list suitable for the API. + - When updating a user_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. attributes: check_mode: support: full @@ -59,22 +61,26 @@ options: type: str description: - ID of the user to be mapped. - - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of API calls required. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. service_account_user_client_id: type: str description: - Client ID of the service-account-user to be mapped. - - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of API calls required. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. client_id: type: str description: - Name of the client to be mapped (different than O(cid)). - - This parameter is required if O(cid) is not provided (can be replaced by O(cid) to reduce the number of API calls that must be made). + - This parameter is required if O(cid) is not provided (can be replaced by O(cid) to reduce the number of API calls + that must be made). cid: type: str description: - ID of the client to be mapped. - - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of API calls required. + - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of + API calls required. roles: description: - Roles to be mapped to the user. @@ -90,8 +96,8 @@ options: 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 will reduce the number of API calls - required. + - This parameter is not required for updating or deleting a role_representation but providing it will reduce the + number of API calls required. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak diff --git a/plugins/modules/keycloak_userprofile.py b/plugins/modules/keycloak_userprofile.py index 49b52c4521..f54cd7183a 100644 --- a/plugins/modules/keycloak_userprofile.py +++ b/plugins/modules/keycloak_userprofile.py @@ -14,11 +14,11 @@ module: keycloak_userprofile short_description: Allows managing Keycloak User Profiles description: - - 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 - U(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. + - 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 U(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. version_added: "9.4.0" attributes: @@ -33,7 +33,8 @@ options: state: description: - State of the User Profile provider. - - On V(present), the User Profile provider will be created if it does not yet exist, or updated with the parameters you provide. + - On V(present), the User Profile provider will be created if it does not yet exist, or updated with the parameters + you provide. - On V(absent), the User Profile provider will be removed if it exists. default: 'present' type: str @@ -264,8 +265,8 @@ options: - ADMIN_VIEW notes: - - Currently, only a single V(declarative-user-profile) entry is supported for O(provider_id) (design of the Keyckoak API). However, there can - be multiple O(config.kc_user_profile_config[].attributes[]) entries. + - Currently, only a single V(declarative-user-profile) entry is supported for O(provider_id) (design of the Keyckoak API). + However, there can be multiple O(config.kc_user_profile_config[].attributes[]) entries. extends_documentation_fragment: - community.general.keycloak - community.general.keycloak.actiongroup_keycloak diff --git a/plugins/modules/keyring.py b/plugins/modules/keyring.py index e96d01ac44..3a8cbcae02 100644 --- a/plugins/modules/keyring.py +++ b/plugins/modules/keyring.py @@ -19,8 +19,8 @@ author: - Alexander Hussey (@ahussey-redhat) short_description: Set or delete a passphrase using the Operating System's native keyring description: >- - This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to set or delete passphrases for a given service and username - from the OS' native keyring. + This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to set or delete passphrases for a given + service and username from the OS' native keyring. requirements: - keyring (Python library) - gnome-keyring (application - required for headless Gnome keyring access) diff --git a/plugins/modules/keyring_info.py b/plugins/modules/keyring_info.py index 9fcd4d5d92..836ecafdde 100644 --- a/plugins/modules/keyring_info.py +++ b/plugins/modules/keyring_info.py @@ -19,8 +19,8 @@ author: - Alexander Hussey (@ahussey-redhat) short_description: Get a passphrase using the Operating System's native keyring description: >- - This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to retrieve passphrases for a given service and username from - the OS' native keyring. + This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to retrieve passphrases for a given service + and username from the OS' native keyring. requirements: - keyring (Python library) - gnome-keyring (application - required for headless Linux keyring access) diff --git a/plugins/modules/kibana_plugin.py b/plugins/modules/kibana_plugin.py index 953d3518a6..09703b504c 100644 --- a/plugins/modules/kibana_plugin.py +++ b/plugins/modules/kibana_plugin.py @@ -102,7 +102,7 @@ name: returned: success type: str url: - description: The url from where the plugin is installed from. + description: The URL from where the plugin is installed from. returned: success type: str timeout: diff --git a/plugins/modules/krb_ticket.py b/plugins/modules/krb_ticket.py index d93966e501..e021050c22 100644 --- a/plugins/modules/krb_ticket.py +++ b/plugins/modules/krb_ticket.py @@ -50,21 +50,24 @@ options: - Use O(cache_name) as the ticket cache name and location. - If this option is not used, the default cache name and location are used. - The default credentials cache may vary between systems. - - If not set the the value of E(KRB5CCNAME) environment variable will be used instead, its value is used to name the default ticket cache. + - If not set the the value of E(KRB5CCNAME) environment variable will be used instead, its value is used to name the + default ticket cache. type: str lifetime: description: - Requests a ticket with the lifetime, if the O(lifetime) is not specified, the default ticket lifetime is used. - - Specifying a ticket lifetime longer than the maximum ticket lifetime (configured by each site) will not override the configured maximum - ticket lifetime. - - 'The value for O(lifetime) must be followed by one of the following suffixes: V(s) - seconds, V(m) - minutes, V(h) - hours, V(d) - days.' + - Specifying a ticket lifetime longer than the maximum ticket lifetime (configured by each site) will not override the + configured maximum ticket lifetime. + - 'The value for O(lifetime) must be followed by one of the following suffixes: V(s) - seconds, V(m) - minutes, V(h) + - hours, V(d) - days.' - You cannot mix units; a value of V(3h30m) will result in an error. - See U(https://web.mit.edu/kerberos/krb5-1.12/doc/basic/date_format.html) for reference. type: str start_time: description: - Requests a postdated ticket. - - Postdated tickets are issued with the invalid flag set, and need to be resubmitted to the KDC for validation before use. + - Postdated tickets are issued with the invalid flag set, and need to be resubmitted to the KDC for validation before + use. - O(start_time) specifies the duration of the delay before the ticket can become valid. - You can use absolute time formats, for example V(July 27, 2012 at 20:30) you would neet to set O(start_time=20120727203000). - You can also use time duration format similar to O(lifetime) or O(renewable). @@ -73,8 +76,8 @@ options: renewable: description: - Requests renewable tickets, with a total lifetime equal to O(renewable). - - 'The value for O(renewable) must be followed by one of the following delimiters: V(s) - seconds, V(m) - minutes, V(h) - hours, V(d) - - days.' + - 'The value for O(renewable) must be followed by one of the following delimiters: V(s) - seconds, V(m) - minutes, V(h) + - hours, V(d) - days.' - You cannot mix units; a value of V(3h30m) will result in an error. - See U(https://web.mit.edu/kerberos/krb5-1.12/doc/basic/date_format.html) for reference. type: str @@ -96,7 +99,8 @@ options: type: bool canonicalization: description: - - Requests canonicalization of the principal name, and allows the KDC to reply with a different client principal from the one requested. + - Requests canonicalization of the principal name, and allows the KDC to reply with a different client principal from + the one requested. type: bool enterprise: description: