Unflatmap community.general (#5461)

* Move files. * Update imports and references. * Move wrongly placed files. * Reverse redirects, deprecate long → short name redirects. * Simplify contribution guidelines for new modules. * Rewrite BOTMETA. * Add changelog fragment. * Fix ignore.txt files.
2025-06-05 07:49:10 -07:00 · 2022-11-02 21:42:29 +01:00 · 2022-11-02 21:42:29 +01:00 · b531ecdc9b
commit b531ecdc9b
parent 2b0bebc8fc
1033 changed files with 4802 additions and 1989 deletions
--- a/plugins/modules/keycloak_identity_provider.py
+++ b/plugins/modules/keycloak_identity_provider.py
@ -0,0 +1,648 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) Ansible project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: keycloak_identity_provider
+
+short_description: Allows administration of Keycloak identity providers via Keycloak API
+
+version_added: 3.6.0
+
+description:
+    - This module allows you to add, remove or modify Keycloak identity providers via the Keycloak REST API.
+      It requires access to the REST API via 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).
+
+
+options:
+    state:
+        description:
+            - State of the identity provider.
+            - On C(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide.
+            - On C(absent), the identity provider will be removed if it exists.
+        default: 'present'
+        type: str
+        choices:
+            - present
+            - absent
+
+    realm:
+        description:
+            - The Keycloak realm under which this identity provider resides.
+        default: 'master'
+        type: str
+
+    alias:
+        description:
+            - The alias uniquely identifies an identity provider and it is also used to build the redirect URI.
+        required: true
+        type: str
+
+    display_name:
+        description:
+            - Friendly name for identity provider.
+        aliases:
+            - displayName
+        type: str
+
+    enabled:
+        description:
+            - Enable/disable this identity provider.
+        type: bool
+
+    store_token:
+        description:
+            - Enable/disable whether tokens must be stored after authenticating users.
+        aliases:
+            - storeToken
+        type: bool
+
+    add_read_token_role_on_create:
+        description:
+            - Enable/disable whether new users can read any stored tokens. This assigns the C(broker.read-token) role.
+        aliases:
+            - addReadTokenRoleOnCreate
+        type: bool
+
+    trust_email:
+        description:
+            - If enabled, email provided by this provider is not verified even if verification is enabled for the realm.
+        aliases:
+            - trustEmail
+        type: bool
+
+    link_only:
+        description:
+            - If true, users cannot log in through this provider. They can only link to this provider.
+              This is useful if you don't want to allow login from the provider, but want to integrate with a provider.
+        aliases:
+            - linkOnly
+        type: bool
+
+    first_broker_login_flow_alias:
+        description:
+            - Alias of authentication flow, which is triggered after first login with this identity provider.
+        aliases:
+            - firstBrokerLoginFlowAlias
+        type: str
+
+    post_broker_login_flow_alias:
+        description:
+            - Alias of authentication flow, which is triggered after each login with this identity provider.
+        aliases:
+            - postBrokerLoginFlowAlias
+        type: str
+
+    authenticate_by_default:
+        description:
+            - Specifies if this identity provider should be used by default for authentication even before displaying login screen.
+        aliases:
+            - authenticateByDefault
+        type: bool
+
+    provider_id:
+        description:
+            - Protocol used by this provider (supported values are C(oidc) or C(saml)).
+        aliases:
+            - providerId
+        type: str
+
+    config:
+        description:
+            - Dict specifying the configuration options for the provider; the contents differ depending on the value of I(providerId).
+              Examples are given below for C(oidc) and C(saml). It is easiest to obtain valid config values by dumping an already-existing
+              identity provider configuration through check-mode in the I(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.
+                aliases:
+                    - hideOnLoginPage
+                type: bool
+
+            gui_order:
+                description:
+                    - Number defining order of the provider in GUI (for example, on Login page).
+                aliases:
+                    - guiOrder
+                type: int
+
+            sync_mode:
+                description:
+                    - Default sync mode for all mappers. The sync mode determines when user data will be synced using the mappers.
+                aliases:
+                    - syncMode
+                type: str
+
+            issuer:
+                description:
+                    - The issuer identifier for the issuer of the response. If not provided, no validation will be performed.
+                type: str
+
+            authorizationUrl:
+                description:
+                    - The Authorization URL.
+                type: str
+
+            tokenUrl:
+                description:
+                    - The Token URL.
+                type: str
+
+            logoutUrl:
+                description:
+                    - End session endpoint to use to logout user from external IDP.
+                type: str
+
+            userInfoUrl:
+                description:
+                    - The User Info URL.
+                type: str
+
+            clientAuthMethod:
+                description:
+                    - The client authentication method.
+                type: str
+
+            clientId:
+                description:
+                    - The client or client identifier registered within the identity provider.
+                type: str
+
+            clientSecret:
+                description:
+                    - The client or client secret registered within the identity provider.
+                type: str
+
+            defaultScope:
+                description:
+                    - The scopes to be sent when asking for authorization.
+                type: str
+
+            validateSignature:
+                description:
+                    - Enable/disable signature validation of external IDP signatures.
+                type: bool
+
+            useJwksUrl:
+                description:
+                    - If the switch is on, identity provider public keys will be downloaded from given JWKS URL.
+                type: bool
+
+            jwksUrl:
+                description:
+                    - URL where identity provider keys in JWK format are stored. See JWK specification for more details.
+                type: str
+
+            entityId:
+                description:
+                    - The Entity ID that will be used to uniquely identify this SAML Service Provider.
+                type: str
+
+            singleSignOnServiceUrl:
+                description:
+                    - The URL that must be used to send authentication requests (SAML AuthnRequest).
+                type: str
+
+            singleLogoutServiceUrl:
+                description:
+                    - The URL that must be used to send logout requests.
+                type: str
+
+            backchannelSupported:
+                description:
+                    - Does the external IDP support backchannel logout?
+                type: str
+
+            nameIDPolicyFormat:
+                description:
+                    - Specifies the URI reference corresponding to a name identifier format.
+                type: str
+
+            principalType:
+                description:
+                    - Way to identify and track external users from the assertion.
+                type: str
+
+    mappers:
+        description:
+            - A list of dicts defining mappers associated with this Identity Provider.
+        type: list
+        elements: dict
+        suboptions:
+            id:
+                description:
+                    - Unique ID of this mapper.
+                type: str
+
+            name:
+                description:
+                    - Name of the mapper.
+                type: str
+
+            identityProviderAlias:
+                description:
+                    - Alias of the identity provider for this mapper.
+                type: str
+
+            identityProviderMapper:
+                description:
+                    - Type of mapper.
+                type: str
+
+            config:
+                description:
+                    - Dict specifying the configuration options for the mapper; the contents differ depending on the value of I(identityProviderMapper).
+                type: dict
+
+extends_documentation_fragment:
+- community.general.keycloak
+
+author:
+    - Laurent Paumier (@laurpaum)
+'''
+
+EXAMPLES = '''
+- name: Create OIDC identity provider, authentication with credentials
+  community.general.keycloak_identity_provider:
+    state: present
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: admin
+    auth_password: admin
+    realm: myrealm
+    alias: oidc-idp
+    display_name: OpenID Connect IdP
+    enabled: true
+    provider_id: oidc
+    config:
+      issuer: https://idp.example.com
+      authorizationUrl: https://idp.example.com/auth
+      tokenUrl: https://idp.example.com/token
+      userInfoUrl: https://idp.example.com/userinfo
+      clientAuthMethod: client_secret_post
+      clientId: my-client
+      clientSecret: secret
+      syncMode: FORCE
+    mappers:
+      - name: first_name
+        identityProviderMapper: oidc-user-attribute-idp-mapper
+        config:
+          claim: first_name
+          user.attribute: first_name
+          syncMode: INHERIT
+      - name: last_name
+        identityProviderMapper: oidc-user-attribute-idp-mapper
+        config:
+          claim: last_name
+          user.attribute: last_name
+          syncMode: INHERIT
+
+- name: Create SAML identity provider, authentication with credentials
+  community.general.keycloak_identity_provider:
+    state: present
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: admin
+    auth_password: admin
+    realm: myrealm
+    alias: saml-idp
+    display_name: SAML IdP
+    enabled: true
+    provider_id: saml
+    config:
+      entityId: https://auth.example.com/auth/realms/myrealm
+      singleSignOnServiceUrl: https://idp.example.com/login
+      wantAuthnRequestsSigned: true
+      wantAssertionsSigned: true
+    mappers:
+      - name: roles
+        identityProviderMapper: saml-user-attribute-idp-mapper
+        config:
+          user.attribute: roles
+          attribute.friendly.name: User Roles
+          attribute.name: roles
+          syncMode: INHERIT
+'''
+
+RETURN = '''
+msg:
+    description: Message as to what action was taken.
+    returned: always
+    type: str
+    sample: "Identity provider my-idp has been created"
+
+proposed:
+    description: Representation of proposed identity provider.
+    returned: always
+    type: dict
+    sample: {
+        "config": {
+            "authorizationUrl": "https://idp.example.com/auth",
+            "clientAuthMethod": "client_secret_post",
+            "clientId": "my-client",
+            "clientSecret": "secret",
+            "issuer": "https://idp.example.com",
+            "tokenUrl": "https://idp.example.com/token",
+            "userInfoUrl": "https://idp.example.com/userinfo"
+        },
+        "displayName": "OpenID Connect IdP",
+        "providerId": "oidc"
+    }
+
+existing:
+    description: Representation of existing identity provider.
+    returned: always
+    type: dict
+    sample: {
+        "addReadTokenRoleOnCreate": false,
+        "alias": "my-idp",
+        "authenticateByDefault": false,
+        "config": {
+            "authorizationUrl": "https://old.example.com/auth",
+            "clientAuthMethod": "client_secret_post",
+            "clientId": "my-client",
+            "clientSecret": "**********",
+            "issuer": "https://old.example.com",
+            "syncMode": "FORCE",
+            "tokenUrl": "https://old.example.com/token",
+            "userInfoUrl": "https://old.example.com/userinfo"
+        },
+        "displayName": "OpenID Connect IdP",
+        "enabled": true,
+        "firstBrokerLoginFlowAlias": "first broker login",
+        "internalId": "4d28d7e3-1b80-45bb-8a30-5822bf55aa1c",
+        "linkOnly": false,
+        "providerId": "oidc",
+        "storeToken": false,
+        "trustEmail": false,
+    }
+
+end_state:
+    description: Representation of identity provider after module execution.
+    returned: on success
+    type: dict
+    sample: {
+        "addReadTokenRoleOnCreate": false,
+        "alias": "my-idp",
+        "authenticateByDefault": false,
+        "config": {
+            "authorizationUrl": "https://idp.example.com/auth",
+            "clientAuthMethod": "client_secret_post",
+            "clientId": "my-client",
+            "clientSecret": "**********",
+            "issuer": "https://idp.example.com",
+            "tokenUrl": "https://idp.example.com/token",
+            "userInfoUrl": "https://idp.example.com/userinfo"
+        },
+        "displayName": "OpenID Connect IdP",
+        "enabled": true,
+        "firstBrokerLoginFlowAlias": "first broker login",
+        "internalId": "4d28d7e3-1b80-45bb-8a30-5822bf55aa1c",
+        "linkOnly": false,
+        "providerId": "oidc",
+        "storeToken": false,
+        "trustEmail": false,
+    }
+'''
+
+from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
+    keycloak_argument_spec, get_token, KeycloakError
+from ansible.module_utils.basic import AnsibleModule
+from copy import deepcopy
+
+
+def sanitize(idp):
+    idpcopy = deepcopy(idp)
+    if 'config' in idpcopy:
+        if 'clientSecret' in idpcopy['config']:
+            idpcopy['clientSecret'] = '**********'
+    return idpcopy
+
+
+def get_identity_provider_with_mappers(kc, alias, realm):
+    idp = kc.get_identity_provider(alias, realm)
+    if idp is not None:
+        idp['mappers'] = sorted(kc.get_identity_provider_mappers(alias, realm), key=lambda x: x.get('name'))
+    if idp is None:
+        idp = {}
+    return idp
+
+
+def main():
+    """
+    Module execution
+
+    :return:
+    """
+    argument_spec = keycloak_argument_spec()
+
+    mapper_spec = dict(
+        id=dict(type='str'),
+        name=dict(type='str'),
+        identityProviderAlias=dict(type='str'),
+        identityProviderMapper=dict(type='str'),
+        config=dict(type='dict'),
+    )
+
+    meta_args = dict(
+        state=dict(type='str', default='present', choices=['present', 'absent']),
+        realm=dict(type='str', default='master'),
+        alias=dict(type='str', required=True),
+        add_read_token_role_on_create=dict(type='bool', aliases=['addReadTokenRoleOnCreate']),
+        authenticate_by_default=dict(type='bool', aliases=['authenticateByDefault']),
+        config=dict(type='dict'),
+        display_name=dict(type='str', aliases=['displayName']),
+        enabled=dict(type='bool'),
+        first_broker_login_flow_alias=dict(type='str', aliases=['firstBrokerLoginFlowAlias']),
+        link_only=dict(type='bool', aliases=['linkOnly']),
+        post_broker_login_flow_alias=dict(type='str', aliases=['postBrokerLoginFlowAlias']),
+        provider_id=dict(type='str', aliases=['providerId']),
+        store_token=dict(type='bool', aliases=['storeToken']),
+        trust_email=dict(type='bool', aliases=['trustEmail']),
+        mappers=dict(type='list', elements='dict', options=mapper_spec),
+    )
+
+    argument_spec.update(meta_args)
+
+    module = AnsibleModule(argument_spec=argument_spec,
+                           supports_check_mode=True,
+                           required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+
+    result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
+
+    # Obtain access token, initialize API
+    try:
+        connection_header = get_token(module.params)
+    except KeycloakError as e:
+        module.fail_json(msg=str(e))
+
+    kc = KeycloakAPI(module, connection_header)
+
+    realm = module.params.get('realm')
+    alias = module.params.get('alias')
+    state = module.params.get('state')
+
+    # Filter and map the parameters names that apply to the identity provider.
+    idp_params = [x for x in module.params
+                  if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm', 'mappers'] and
+                  module.params.get(x) is not None]
+
+    # See if it already exists in Keycloak
+    before_idp = get_identity_provider_with_mappers(kc, alias, realm)
+
+    # Build a proposed changeset from parameters given to this module
+    changeset = {}
+
+    for param in idp_params:
+        new_param_value = module.params.get(param)
+        old_value = before_idp[camel(param)] if camel(param) in before_idp else None
+        if new_param_value != old_value:
+            changeset[camel(param)] = new_param_value
+
+    # special handling of mappers list to allow change detection
+    if module.params.get('mappers') is not None:
+        for change in module.params['mappers']:
+            change = dict((k, v) for k, v in change.items() if change[k] is not None)
+            if change.get('id') is None and change.get('name') is None:
+                module.fail_json(msg='Either `name` or `id` has to be specified on each mapper.')
+            if before_idp == dict():
+                old_mapper = dict()
+            elif change.get('id') is not None:
+                old_mapper = kc.get_identity_provider_mapper(change['id'], alias, realm)
+                if old_mapper is None:
+                    old_mapper = dict()
+            else:
+                found = [x for x in kc.get_identity_provider_mappers(alias, realm) if x['name'] == change['name']]
+                if len(found) == 1:
+                    old_mapper = found[0]
+                else:
+                    old_mapper = dict()
+            new_mapper = old_mapper.copy()
+            new_mapper.update(change)
+            if new_mapper != old_mapper:
+                if changeset.get('mappers') is None:
+                    changeset['mappers'] = list()
+                changeset['mappers'].append(new_mapper)
+
+    # Prepare the desired values using the existing values (non-existence results in a dict that is save to use as a basis)
+    desired_idp = before_idp.copy()
+    desired_idp.update(changeset)
+
+    result['proposed'] = sanitize(changeset)
+    result['existing'] = sanitize(before_idp)
+
+    # Cater for when it doesn't exist (an empty dict)
+    if not before_idp:
+        if state == 'absent':
+            # Do nothing and exit
+            if module._diff:
+                result['diff'] = dict(before='', after='')
+            result['changed'] = False
+            result['end_state'] = {}
+            result['msg'] = 'Identity provider does not exist; doing nothing.'
+            module.exit_json(**result)
+
+        # Process a creation
+        result['changed'] = True
+
+        if module._diff:
+            result['diff'] = dict(before='', after=sanitize(desired_idp))
+
+        if module.check_mode:
+            module.exit_json(**result)
+
+        # create it
+        desired_idp = desired_idp.copy()
+        mappers = desired_idp.pop('mappers', [])
+        kc.create_identity_provider(desired_idp, realm)
+        for mapper in mappers:
+            if mapper.get('identityProviderAlias') is None:
+                mapper['identityProviderAlias'] = alias
+            kc.create_identity_provider_mapper(mapper, alias, realm)
+        after_idp = get_identity_provider_with_mappers(kc, alias, realm)
+
+        result['end_state'] = sanitize(after_idp)
+
+        result['msg'] = 'Identity provider {alias} has been created'.format(alias=alias)
+        module.exit_json(**result)
+
+    else:
+        if state == 'present':
+            # Process an update
+
+            # no changes
+            if desired_idp == before_idp:
+                result['changed'] = False
+                result['end_state'] = sanitize(desired_idp)
+                result['msg'] = "No changes required to identity provider {alias}.".format(alias=alias)
+                module.exit_json(**result)
+
+            # doing an update
+            result['changed'] = True
+
+            if module._diff:
+                result['diff'] = dict(before=sanitize(before_idp), after=sanitize(desired_idp))
+
+            if module.check_mode:
+                module.exit_json(**result)
+
+            # do the update
+            desired_idp = desired_idp.copy()
+            updated_mappers = desired_idp.pop('mappers', [])
+            kc.update_identity_provider(desired_idp, realm)
+            for mapper in updated_mappers:
+                if mapper.get('id') is not None:
+                    kc.update_identity_provider_mapper(mapper, alias, realm)
+                else:
+                    if mapper.get('identityProviderAlias') is None:
+                        mapper['identityProviderAlias'] = alias
+                    kc.create_identity_provider_mapper(mapper, alias, realm)
+            for mapper in [x for x in before_idp['mappers']
+                           if [y for y in updated_mappers if y["name"] == x['name']] == []]:
+                kc.delete_identity_provider_mapper(mapper['id'], alias, realm)
+
+            after_idp = get_identity_provider_with_mappers(kc, alias, realm)
+
+            result['end_state'] = sanitize(after_idp)
+
+            result['msg'] = "Identity provider {alias} has been updated".format(alias=alias)
+            module.exit_json(**result)
+
+        elif state == 'absent':
+            # Process a deletion
+            result['changed'] = True
+
+            if module._diff:
+                result['diff'] = dict(before=sanitize(before_idp), after='')
+
+            if module.check_mode:
+                module.exit_json(**result)
+
+            # delete it
+            kc.delete_identity_provider(alias, realm)
+
+            result['end_state'] = {}
+
+            result['msg'] = "Identity provider {alias} has been deleted".format(alias=alias)
+
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()