keycloak_client: expand documentation, add some checking (#35545)

* add protocol mapper dict argument spec, documentation for protocol mappers, and documentation for attributes

* reformat docs to stay in line length limit

* better formatting/highlighting for docs

* ooops

lib/ansible/modules/identity/keycloak/keycloak_client.py

@@ -41,7 +41,6 @@ options:
             - State of the client
             - On C(present), the client will be created (or updated if it exists already).
             - On C(absent), the client will be removed if it exists
-        required: false
         choices: ['present', 'absent']
         default: 'present'
 
@@ -50,46 +49,38 @@ options:
             - Client id of client to be worked on. This is usually an alphanumeric name chosen by
               you. Either this or I(id) is required. If you specify both, I(id) takes precedence.
               This is 'clientId' in the Keycloak REST API.
-        required: false
 
     id:
         description:
             - Id of client to be worked on. This is usually an UUID. Either this or I(client_id)
               is required. If you specify both, this takes precedence.
-        required: false
 
     name:
         description:
             - Name of the client (this is not the same as I(client_id))
-        required: false
 
     description:
         description:
             - Description of the client in Keycloak
-        required: false
 
     root_url:
         description:
             - Root URL appended to relative URLs for this client
               This is 'rootUrl' in the Keycloak REST API.
-        required: false
 
     admin_url:
         description:
             - URL to the admin interface of the client
               This is 'adminUrl' in the Keycloak REST API.
-        required: false
 
     base_url:
         description:
             - Default URL to use when the auth server needs to redirect or link back to the client
               This is 'baseUrl' in the Keycloak REST API.
-        required: false
 
     enabled:
         description:
             - Is this client enabled or not?
-        required: false
 
     client_authenticator_type:
         description:
@@ -99,7 +90,6 @@ options:
               C(jwks.url), and C(jwt.credential.certificate) in the I(attributes) module parameter
               to configure its behavior.
               This is 'clientAuthenticatorType' in the Keycloak REST API.
-        required: false
         choices: ['client-secret', 'client-jwt']
 
     secret:
@@ -108,169 +98,303 @@ options:
               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).
-        required: false
 
     registration_access_token:
         description:
             - The registration access token provides access for clients to the client registration
               service.
               This is 'registrationAccessToken' in the Keycloak REST API.
-        required: false
 
     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 'defaultRoles' in the Keycloak REST API.
-        required: false
 
     redirect_uris:
         description:
             - Acceptable redirect URIs for this client.
               This is 'redirectUris' in the Keycloak REST API.
-        required: false
 
     web_origins:
         description:
             - List of allowed CORS origins.
               This is 'webOrigins' in the Keycloak REST API.
-        required: false
 
     not_before:
         description:
             - Revoke any tokens issued before this date for this client (this is a UNIX timestamp).
               This is 'notBefore' in the Keycloak REST API.
-        required: false
 
     bearer_only:
         description:
             - The access type of this client is bearer-only.
               This is 'bearerOnly' in the Keycloak REST API.
-        required: false
 
     consent_required:
         description:
             - If enabled, users have to consent to client access.
               This is 'consentRequired' in the Keycloak REST API.
-        required: false
 
     standard_flow_enabled:
         description:
             - Enable standard flow for this client or not (OpenID connect).
               This is 'standardFlowEnabled' in the Keycloak REST API.
-        required: false
 
     implicit_flow_enabled:
         description:
             - Enable implicit flow for this client or not (OpenID connect).
               This is 'implictFlowEnabled' in the Keycloak REST API.
-        required: false
 
     direct_access_grants_enabled:
         description:
             - Are direct access grants enabled for this client or not (OpenID connect).
               This is 'directAccessGrantsEnabled' in the Keycloak REST API.
-        required: false
 
     service_accounts_enabled:
         description:
             - Are service accounts enabled for this client or not (OpenID connect).
               This is 'serviceAccountsEnabled' in the Keycloak REST API.
-        required: false
 
     authorization_services_enabled:
         description:
             - Are authorization services enabled for this client or not (OpenID connect).
               This is 'authorizationServicesEnabled' in the Keycloak REST API.
-        required: false
 
     public_client:
         description:
             - Is the access type for this client public or not.
               This is 'publicClient' in the Keycloak REST API.
-        required: false
 
     frontchannel_logout:
         description:
             - Is frontchannel logout enabled for this client or not.
               This is 'frontchannelLogout' in the Keycloak REST API.
-        required: false
 
     protocol:
         description:
             - Type of client (either C(openid-connect) or C(saml).
-        required: false
         choices: ['openid-connect', 'saml']
 
     full_scope_allowed:
         description:
             - Is the "Full Scope Allowed" feature set for this client or not.
               This is 'fullScopeAllowed' in the Keycloak REST API.
-        required: false
 
     node_re_registration_timeout:
         description:
             - Cluster node re-registration timeout for this client.
               This is 'nodeReRegistrationTimeout' in the Keycloak REST API.
-        required: false
 
     registered_nodes:
         description:
             - dict of registered cluster nodes (with C(nodename) as the key and last registration
               time as the value).
               This is 'registeredNodes' in the Keycloak REST API.
-        required: false
 
     client_template:
         description:
             - Client template to use for this client. If it does not exist this field will silently
               be dropped.
               This is 'clientTemplate' in the Keycloak REST API.
-        required: false
 
     use_template_config:
         description:
             - Whether or not to use configuration from the I(client_template).
               This is 'useTemplateConfig' in the Keycloak REST API.
-        required: false
 
     use_template_scope:
         description:
             - Whether or not to use scope configuration from the I(client_template).
               This is 'useTemplateScope' in the Keycloak REST API.
-        required: false
 
     use_template_mappers:
         description:
             - Whether or not to use mapper configuration from the I(client_template).
               This is 'useTemplateMappers' in the Keycloak REST API.
-        required: false
 
     surrogate_auth_required:
         description:
             - Whether or not surrogate auth is required.
               This is 'surrogateAuthRequired' in the Keycloak REST API.
-        required: false
 
     authorization_settings:
         description:
             - a data structure defining the authorization settings for this client. For reference,
               please see the Keycloak API docs at U(http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_resourceserverrepresentation).
               This is 'authorizationSettings' in the Keycloak REST API.
-        required: false
 
     protocol_mappers:
         description:
-            - a list of dicts defining protocol mappers for this client. An example of one is given
+            - a list of dicts defining protocol mappers for this client.
-              in the examples section.
               This is 'protocolMappers' in the Keycloak REST API.
-        required: false
+        suboptions:
+            consentRequired:
+                description:
+                    - Specifies whether a user needs to provide consent to a client for this mapper to be active.
+
+            consentText:
+                description:
+                    - The human-readable name of the consent the user is presented to accept.
+
+            id:
+                description:
+                    - Usually a UUID specifying the internal ID of this protocol mapper instance.
+
+            name:
+                description:
+                    - The name of this protocol mapper.
+
+            protocol:
+                description:
+                    - This is either C(openid-connect) or C(saml), this specifies for which protocol this protocol mapper
+                      is active.
+                choices: ['openid-connect', 'saml']
+
+            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
+                    - C(docker-v2-allow-all-mapper)
+                    - C(oidc-address-mapper)
+                    - C(oidc-full-name-mapper)
+                    - C(oidc-group-membership-mapper)
+                    - C(oidc-hardcoded-claim-mapper)
+                    - C(oidc-hardcoded-role-mapper)
+                    - C(oidc-role-name-mapper)
+                    - C(oidc-script-based-protocol-mapper)
+                    - C(oidc-sha256-pairwise-sub-mapper)
+                    - C(oidc-usermodel-attribute-mapper)
+                    - C(oidc-usermodel-client-role-mapper)
+                    - C(oidc-usermodel-property-mapper)
+                    - C(oidc-usermodel-realm-role-mapper)
+                    - C(oidc-usersessionmodel-note-mapper)
+                    - C(saml-group-membership-mapper)
+                    - C(saml-hardcode-attribute-mapper)
+                    - C(saml-hardcode-role-mapper)
+                    - C(saml-role-list-mapper)
+                    - C(saml-role-name-mapper)
+                    - C(saml-user-attribute-mapper)
+                    - C(saml-user-property-mapper)
+                    - C(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'.
+
+            config:
+                description:
+                    - Dict specifying the configuration options for the protocol mapper; the
+                      contents differ depending on the value of I(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 I(existing) field.
 
     attributes:
         description:
             - A dict of further attributes for this client. This can contain various configuration
-              settings; an example is given in the examples section.
+              settings; an example is given in the examples section. While an exhaustive list of
-        required: false
+              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.
+        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.
+
+            saml.client.signature:
+                description:
+                    - For SAML clients, boolean specifying whether a client signature is required and validated.
+
+            saml.encrypt:
+                description:
+                    - Boolean specifying whether SAML assertions should be encrypted with the client's public key.
+
+            saml.force.post.binding:
+                description:
+                    - For SAML clients, boolean specifying whether always to use POST binding for responses.
+
+            saml.onetimeuse.condition:
+                description:
+                    - For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses.
+
+            saml.server.signature:
+                description:
+                    - 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.
+
+            saml.signature.algorithm:
+                description:
+                    - Signature algorithm used to sign SAML documents. One of C(RSA_SHA256), C(RSA_SHA1), C(RSA_SHA512), or C(DSA_SHA1).
+
+            saml.signing.certificate:
+                description:
+                    - SAML signing key certificate, base64-encoded.
+
+            saml.signing.private.key:
+                description:
+                    - SAML signing key private key, base64-encoded.
+
+            saml_assertion_consumer_url_post:
+                description:
+                    - SAML POST Binding URL for the client's assertion consumer service (login responses).
+
+            saml_assertion_consumer_url_redirect:
+                description:
+                    - 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.
+
+            saml_name_id_format:
+                description:
+                    - For SAML clients, the NameID format to use (one of C(username), C(email), C(transient), or C(persistent))
+
+            saml_signature_canonicalization_method:
+                description:
+                    - SAML signature canonicalization method. This is one of four values, namely
+                      C(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE,
+                      C(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS,
+                      C(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and
+                      C(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_single_logout_service_url_redirect:
+                description:
+                    - 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 C(RS256) or C(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 C(any), C(none), C(RS256).
+
+            use.jwks.url:
+                description:
+                    - For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client
+                      public keys.
+
+            jwks.url:
+                description:
+                    - For OpenID-Connect clients, URL where client keys in JWK are stored.
+
+            jwt.credential.certificate:
+                description:
+                    - For OpenID-Connect clients, client certificate for validating JWT issued by
+                      client and signed by its key, base64-encoded.
 
 extends_documentation_fragment:
     - keycloak
@@ -452,6 +576,17 @@ def main():
     :return:
     """
     argument_spec = keycloak_argument_spec()
+
+    protmapper_spec = dict(
+        consentRequired=dict(type='bool'),
+        consentText=dict(type='str'),
+        id=dict(type='str'),
+        name=dict(type='str'),
+        protocol=dict(type='str', choices=['openid-connect', 'saml']),
+        protocolMapper=dict(type='str'),
+        config=dict(type='dict'),
+    )
+
     meta_args = dict(
         state=dict(default='present', choices=['present', 'absent']),
         realm=dict(type='str', default='master'),
@@ -490,7 +625,7 @@ def main():
         use_template_config=dict(type='bool'),
         use_template_scope=dict(type='bool'),
         use_template_mappers=dict(type='bool'),
-        protocol_mappers=dict(type='list'),
+        protocol_mappers=dict(type='list', elements='dict', options=protmapper_spec),
         authorization_settings=dict(type='dict'),
     )
     argument_spec.update(meta_args)