community.general.keycloak_client 模块 – 允许通过 Keycloak API 管理 Keycloak 客户端

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您使用的是 ansible 包，您可能已经安装了这个集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定：community.general.keycloak_client。

概要

• 此模块允许通过 Keycloak REST API 管理 Keycloak 客户端。它需要通过 OpenID Connect 访问 REST API；连接的用户和正在使用的客户端必须具有所需的访问权限。在默认的 Keycloak 安装中，admin-cli 和管理员用户可以工作，也可以使用具有根据您的需求定制的作用域的单独客户端定义以及具有预期角色的用户。

• 模块选项的名称是 Keycloak API 及其文档（位于 https://keycloak.java.net.cn/docs-api/8.0/rest-api/index.html）中找到的 camelCase 版本的 snake_cased 版本。提供别名以便也可以使用 camelCase 版本。

• Keycloak API 并非总是对输入进行健全性检查，例如，您可以为 OpenID Connect 客户端设置 SAML 特定的设置，反之亦然。请小心。如果您不指定设置，通常会选择一个合理的默认值。

参数

参数	注释
admin_url 别名：adminUrl 字符串	客户端管理界面的 URL。这是 Keycloak REST API 中的“adminUrl”。
always_display_in_console 别名：alwaysDisplayInConsole 布尔值 在 community.general 4.7.0 中添加	是否在帐户控制台中显示此客户端，即使该用户没有活动会话。 选择 false true
attributes 字典	此客户端的其他属性的字典。这可以包含各种配置设置；在示例部分中给出了一个示例。虽然没有提供允许选项的详尽列表；以下列出了 Keycloak 3.4 的可能选项。Keycloak API 不验证给定的选项是否适合所使用的协议；如果仍然指定，Keycloak 将不会使用它。
jwks.url 字符串	对于 OpenID Connect 客户端，存储 JWK 中客户端密钥的 URL。
jwt.credential.certificate 字符串	对于 OpenID Connect 客户端，用于验证客户端颁发的 JWT 并由其密钥签名的客户端证书，base64 编码。
request.object.signature.alg 字符串	对于 OpenID Connect 客户端，客户端在发送 OIDC 请求对象时需要使用的 JWA 算法。其中之一是 any、none、RS256。
saml.authnstatement 字符串	对于 SAML 客户端，布尔值，指定是否应在登录响应中包含包含方法和时间戳的语句。
saml.client.signature 字符串	对于 SAML 客户端，布尔值，指定是否需要和验证客户端签名。
saml.encrypt 字符串	布尔值，指定是否应使用客户端的公钥加密 SAML 断言。
saml.force.post.binding 字符串	对于 SAML 客户端，布尔值，指定是否始终对响应使用 POST 绑定。
saml.onetimeuse.condition 字符串	对于 SAML 客户端，布尔值，指定是否应在登录响应中包含 OneTimeUse 条件。
saml.server.signature 字符串	布尔值，指定是否应由 realm 对 SAML 文档进行签名。
saml.server.signature.keyinfo.ext 字符串	对于 SAML 客户端，布尔值，指定是否应通过在 SAML Extensions 元素中包含签名密钥 ID 来优化 REDIRECT 签名密钥查找。
saml.signature.algorithm 字符串	用于签署 SAML 文档的签名算法。其中之一是 RSA_SHA256、RSA_SHA1、RSA_SHA512 或 DSA_SHA1。
saml.signing.certificate 字符串	SAML 签名密钥证书，base64 编码。
saml.signing.private.key 字符串	SAML 签名密钥私钥，base64 编码。
saml_assertion_consumer_url_post 字符串	客户端断言消费者服务（登录响应）的 SAML POST 绑定 URL。
saml_assertion_consumer_url_redirect 字符串	客户端断言消费者服务（登录响应）的 SAML 重定向绑定 URL。
saml_force_name_id_format 字符串	对于 SAML 客户端，布尔值，指定是否忽略请求的 NameID 主题格式，而使用配置的格式。
saml_name_id_format 字符串	对于 SAML 客户端，要使用的 NameID 格式（username、email、transient 或 persistent 之一）
saml_signature_canonicalization_method 字符串	SAML 签名规范化方法。这是四个值之一，即 http://www.w3.org/2001/10/xml-exc-c14n# 表示 EXCLUSIVE，http://www.w3.org/2001/10/xml-exc-c14n#WithComments 表示 EXCLUSIVE_WITH_COMMENTS，http://www.w3.org/TR/2001/REC-xml-c14n-20010315 表示 INCLUSIVE，以及 http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments 表示 INCLUSIVE_WITH_COMMENTS。
saml_single_logout_service_url_post 字符串	客户端单点注销服务的 SAML POST 绑定 URL。
saml_single_logout_service_url_redirect 字符串	客户端单点注销服务的 SAML 重定向绑定 URL。
use.jwks.url 字符串	对于 OpenID Connect 客户端，布尔值，指定是否使用 JWKS URL 获取客户端公钥。
user.info.response.signature.alg 字符串	对于 OpenID Connect 客户端，用于签名的 UserInfo 端点响应的 JWA 算法。RS256 或 unsigned 之一。
x509.allow.regex.pattern.comparison 布尔值 在 community.general 9.5.0 中添加	对于 OpenID Connect 客户端，布尔值，指定是否允许 x509.subjectdn 作为正则表达式。 选择 false true
x509.subjectdn 字符串 在 community.general 9.5.0 中添加	对于 OpenID Connect 客户端，将用于验证客户端的主题。
auth_client_id 字符串	用于向 API 进行身份验证的 OpenID Connect client_id。 默认值： "admin-cli"
auth_client_secret 字符串	与 auth_client_id 一起使用的客户端密钥（如果需要）。
auth_keycloak_url 别名：url 字符串 / 必需	Keycloak 实例的 URL。
auth_password 别名：password 字符串	用于 API 访问的身份验证密码。
auth_realm 字符串	用于 API 访问的身份验证的 Keycloak 领域名称。
auth_username 别名：username 字符串	用于 API 访问的身份验证的用户名。
authentication_flow_binding_overrides 别名：authenticationFlowBindingOverrides 字典 在 community.general 3.4.0 中添加	覆盖领域身份验证流绑定。
browser 字符串	浏览器身份验证流的流 ID。 authentication_flow_binding_overrides.browser 和 authentication_flow_binding_overrides.browser_name 是互斥的。
browser_name 别名：browserName 字符串 在 community.general 9.1.0 中添加	浏览器身份验证流的流名称。 authentication_flow_binding_overrides.browser 和 authentication_flow_binding_overrides.browser_name 是互斥的。
direct_grant 别名：directGrant 字符串	直接授权身份验证流的流 ID。 authentication_flow_binding_overrides.direct_grant 和 authentication_flow_binding_overrides.direct_grant_name 是互斥的。
direct_grant_name 别名：directGrantName 字符串 在 community.general 9.1.0 中添加	直接授权身份验证流的流名称。 authentication_flow_binding_overrides.direct_grant 和 authentication_flow_binding_overrides.direct_grant_name 是互斥的。
authorization_services_enabled 别名：authorizationServicesEnabled 布尔值	是否为此客户端启用了授权服务（OpenID Connect）。这是 Keycloak REST API 中的“authorizationServicesEnabled”。 选择 false true
authorization_settings 别名：authorizationSettings 字典	定义此客户端授权设置的数据结构。有关参考，请参阅 Keycloak API 文档，网址为 https://keycloak.java.net.cn/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation。这是 Keycloak REST API 中的“authorizationSettings”。
base_url 别名：baseUrl 字符串	当身份验证服务器需要重定向或链接回客户端时，要使用的默认 URL。这是 Keycloak REST API 中的“baseUrl”。
bearer_only 别名：bearerOnly 布尔值	此客户端的访问类型为仅持票人。这是 Keycloak REST API 中的“bearerOnly”。 选择 false true
client_authenticator_type 别名：clientAuthenticatorType 字符串	客户端如何使用身份验证服务器进行身份验证？可以选择 client-secret、client-jwt 或 client-x509。当使用 client-secret 时，模块参数 secret 可以设置它；对于 client-jwt，可以在 attributes 模块参数中使用键 use.jwks.url、jwks.url 和 jwt.credential.certificate 来配置其行为。对于 client-x509，可以在 attributes 模块参数中使用键 x509.allow.regex.pattern.comparison 和 x509.subjectdn 来配置要接受的证书。 这是 Keycloak REST API 中的“clientAuthenticatorType”。 选择 "client-secret" "client-jwt" "client-x509"
client_id 别名：clientId 字符串	要操作的客户端的客户端 ID。这通常是您选择的字母数字名称。需要指定此项或 id。如果同时指定两者，则 id 优先。这是 Keycloak REST API 中的“clientId”。
client_template 别名：clientTemplate 字符串	要用于此客户端的客户端模板。如果它不存在，此字段将静默删除。这是 Keycloak REST API 中的“clientTemplate”。
connection_timeout 整数 在 community.general 4.5.0 中添加	控制 Keycloak API 的 HTTP 连接超时时间（以秒为单位）。 默认值： 10
consent_required 别名：consentRequired 布尔值	如果启用，用户必须同意客户端访问。这是 Keycloak REST API 中的“consentRequired”。 选择 false true
default_client_scopes 别名：defaultClientScopes 列表 / 元素=字符串 在 community.general 4.7.0 中添加	默认客户端范围的列表。
default_roles 别名：defaultRoles 列表 / 元素=字符串	此客户端的默认角色列表。如果引用的客户端角色尚不存在，则将创建它们。这是 Keycloak REST API 中的“defaultRoles”。
description 字符串	Keycloak 中客户端的描述。
direct_access_grants_enabled 别名: directAccessGrantsEnabled 布尔值	是否为此客户端启用直接访问授权（OpenID 连接）。这在 Keycloak REST API 中为 ‘directAccessGrantsEnabled’。 选择 false true
enabled 布尔值	此客户端是否已启用？ 选择 false true
frontchannel_logout 别名: frontchannelLogout 布尔值	是否为此客户端启用前通道注销。这在 Keycloak REST API 中为 ‘frontchannelLogout’。 选择 false true
full_scope_allowed 别名: fullScopeAllowed 布尔值	是否为此客户端设置了“允许完全范围”功能。这在 Keycloak REST API 中为 ‘fullScopeAllowed’。 选择 false true
http_agent 字符串 在 community.general 5.4.0 中添加	配置 HTTP User-Agent 标头。 默认值: "Ansible"
id 字符串	要操作的客户端的 ID。通常是 UUID。此参数或 client_id 是必需的。如果同时指定两者，则此参数优先。
implicit_flow_enabled 别名: implicitFlowEnabled 布尔值	是否为此客户端启用隐式流（OpenID 连接）。这在 Keycloak REST API 中为 ‘implicitFlowEnabled’。 选择 false true
name 字符串	客户端的名称（这与 client_id 不同）。
node_re_registration_timeout 别名: nodeReRegistrationTimeout 整数	此客户端的集群节点重新注册超时时间。这在 Keycloak REST API 中为 ‘nodeReRegistrationTimeout’。
not_before 别名: notBefore 整数	撤销在此日期之前为此客户端颁发的所有令牌（这是一个 UNIX 时间戳）。这在 Keycloak REST API 中为 ‘notBefore’。
optional_client_scopes 别名: optionalClientScopes 列表 / 元素=字符串 在 community.general 4.7.0 中添加	可选客户端范围的列表。
protocol 字符串	客户端的类型。 仅在创建时，如果省略 protocol，则默认值为 openid-connect。 docker-v2 值在 community.general 8.6.0 中添加。 选择 "openid-connect" "saml" "docker-v2"
protocol_mappers 别名: protocolMappers list / elements=dictionary	定义此客户端的协议映射器的字典列表。这在 Keycloak REST API 中为 ‘protocolMappers’。
config 字典	指定协议映射器的配置选项的字典；内容取决于 protocol_mappers[].protocolMapper 的值，并且除了映射器的来源及其父类之外，没有其他文档说明。下面给出一个示例。最简单的方法是通过 existing 字段中的检查模式转储已存在的协议映射器配置，以获取有效的配置值。
consentRequired 布尔值	指定用户是否需要为该映射器向客户端提供同意才能使其生效。 选择 false true
consentText 字符串	呈现给用户接受的同意的人类可读名称。
id 字符串	通常是指定此协议映射器实例内部 ID 的 UUID。
name 字符串	此协议映射器的名称。
protocol 字符串	指定此协议映射器生效的协议。 选择 "openid-connect" "saml" "docker-v2"
protocolMapper 字符串	此协议映射器类型的 Keycloak 内部名称。由于 Keycloak 用户可以通过 SPI 扩展此名称，因此不可能提供详尽的列表，但默认情况下，Keycloak 3.4 至少附带以下内容： docker-v2-allow-all-mapper oidc-address-mapper oidc-full-name-mapper oidc-group-membership-mapper oidc-hardcoded-claim-mapper oidc-hardcoded-role-mapper oidc-role-name-mapper oidc-script-based-protocol-mapper oidc-sha256-pairwise-sub-mapper oidc-usermodel-attribute-mapper oidc-usermodel-client-role-mapper oidc-usermodel-property-mapper oidc-usermodel-realm-role-mapper oidc-usersessionmodel-note-mapper saml-group-membership-mapper saml-hardcode-attribute-mapper saml-hardcode-role-mapper saml-role-list-mapper saml-role-name-mapper saml-user-attribute-mapper saml-user-property-mapper saml-user-session-note-mapper 可以通过转到管理控制台的“服务器信息” -> “提供程序”，并在“协议映射器”下查找，来获取安装上可用的映射器的详尽列表。
public_client 别名: publicClient 布尔值	此客户端的访问类型是否为公共类型。这在 Keycloak REST API 中为 ‘publicClient’。 选择 false true
realm 字符串	要在其中创建客户端的域。 默认值: "master"
redirect_uris 别名: redirectUris 列表 / 元素=字符串	此客户端的可接受的重定向 URI。这在 Keycloak REST API 中为 ‘redirectUris’。
registered_nodes 别名: registeredNodes 字典	已注册的集群节点的字典（以 nodename 作为键，上次注册时间作为值）。这在 Keycloak REST API 中为 ‘registeredNodes’。
registration_access_token 别名: registrationAccessToken 字符串	注册访问令牌提供客户端对客户端注册服务的访问权限。这在 Keycloak REST API 中为 ‘registrationAccessToken’。
root_url 别名: rootUrl 字符串	附加到此客户端的相对 URL 的根 URL。这在 Keycloak REST API 中为 ‘rootUrl’。
secret 字符串	当使用 client_authenticator_type=client-secret （默认值）时，可以在此处指定密钥（否则，如果不存在，则会生成一个密钥）。如果更改此密钥，该模块当前不会注册更改（但会保存已更改的密钥）。
service_accounts_enabled 别名: serviceAccountsEnabled 布尔值	是否为此客户端启用服务帐户（OpenID 连接）。这在 Keycloak REST API 中为 ‘serviceAccountsEnabled’。 选择 false true
standard_flow_enabled 别名: standardFlowEnabled 布尔值	是否为此客户端启用标准流（OpenID 连接）。这在 Keycloak REST API 中为 ‘standardFlowEnabled’。 选择 false true
state 字符串	客户端的状态 在 present 时，将创建客户端（如果已存在，则更新客户端）。 在 absent 时，如果客户端存在，则将其删除 选择 "present" ← （默认） "absent"
surrogate_auth_required 别名: surrogateAuthRequired 布尔值	是否需要代理身份验证。这在 Keycloak REST API 中为 ‘surrogateAuthRequired’。 选择 false true
token 字符串 在 community.general 3.0.0 中添加	Keycloak API 的身份验证令牌。
use_template_config 别名: useTemplateConfig 布尔值	是否使用 client_template 中的配置。这在 Keycloak REST API 中为 ‘useTemplateConfig’。 选择 false true
use_template_mappers 别名: useTemplateMappers 布尔值	是否使用 client_template 中的映射器配置。这在 Keycloak REST API 中为 ‘useTemplateMappers’。 选择 false true
use_template_scope 别名: useTemplateScope 布尔值	是否使用 client_template 中的范围配置。这在 Keycloak REST API 中为 ‘useTemplateScope’。 选择 false true
validate_certs 布尔值	验证 TLS 证书（不要在生产环境中禁用此项）。 选择 false true ← （默认）
web_origins 别名: webOrigins 列表 / 元素=字符串	允许的 CORS 源列表。这在 Keycloak REST API 中是 ‘webOrigins’。

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行，并返回更改状态预测，而无需修改目标。
diff_mode	支持: 完全	当处于 diff 模式时，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息。

示例

- name: Create or update Keycloak client (minimal example), authentication with credentials
  community.general.keycloak_client:
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    client_id: test
    state: present
  delegate_to: localhost


- name: Create or update Keycloak client (minimal example), authentication with token
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    token: TOKEN
    client_id: test
    state: present
  delegate_to: localhost


- name: Delete a Keycloak client
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    client_id: test
    state: absent
  delegate_to: localhost


- name: Create or update a Keycloak client (minimal example), with x509 authentication
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    realm: master
    state: present
    client_id: test
    client_authenticator_type: client-x509
    attributes:
      x509.subjectdn: "CN=client"
      x509.allow.regex.pattern.comparison: false


- name: Create or update a Keycloak client (with all the bells and whistles)
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    state: present
    realm: master
    client_id: test
    id: d8b127a3-31f6-44c8-a7e4-4ab9a3e78d95
    name: this_is_a_test
    description: Description of this wonderful client
    root_url: https://www.example.com/
    admin_url: https://www.example.com/admin_url
    base_url: basepath
    enabled: true
    client_authenticator_type: client-secret
    secret: REALLYWELLKEPTSECRET
    redirect_uris:
      - https://www.example.com/*
      - https://127.0.0.1:8888/
    web_origins:
      - https://www.example.com/*
    not_before: 1507825725
    bearer_only: false
    consent_required: false
    standard_flow_enabled: true
    implicit_flow_enabled: false
    direct_access_grants_enabled: false
    service_accounts_enabled: false
    authorization_services_enabled: false
    public_client: false
    frontchannel_logout: false
    protocol: openid-connect
    full_scope_allowed: false
    node_re_registration_timeout: -1
    client_template: test
    use_template_config: false
    use_template_scope: false
    use_template_mappers: false
    always_display_in_console: true
    registered_nodes:
      node01.example.com: 1507828202
    registration_access_token: eyJWT_TOKEN
    surrogate_auth_required: false
    default_roles:
      - test01
      - test02
    authentication_flow_binding_overrides:
        browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb
    protocol_mappers:
      - config:
          access.token.claim: true
          claim.name: "family_name"
          id.token.claim: true
          jsonType.label: String
          user.attribute: lastName
          userinfo.token.claim: true
        consentRequired: true
        consentText: "${familyName}"
        name: family name
        protocol: openid-connect
        protocolMapper: oidc-usermodel-property-mapper
      - config:
          attribute.name: Role
          attribute.nameformat: Basic
          single: false
        consentRequired: false
        name: role list
        protocol: saml
        protocolMapper: saml-role-list-mapper
    attributes:
      saml.authnstatement: true
      saml.client.signature: true
      saml.force.post.binding: true
      saml.server.signature: true
      saml.signature.algorithm: RSA_SHA256
      saml.signing.certificate: CERTIFICATEHERE
      saml.signing.private.key: PRIVATEKEYHERE
      saml_force_name_id_format: false
      saml_name_id_format: username
      saml_signature_canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#"
      user.info.response.signature.alg: RS256
      request.object.signature.alg: RS256
      use.jwks.url: true
      jwks.url: JWKS_URL_FOR_CLIENT_AUTH_JWT
      jwt.credential.certificate: JWT_CREDENTIAL_CERTIFICATE_FOR_CLIENT_AUTH
  delegate_to: localhost

返回值

常用的返回值记录在 这里，以下是此模块特有的字段

键	描述
end_state 字典	模块执行后客户端的表示形式（示例已截断）。 已返回: 成功时 示例: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
existing 字典	现有客户端的表示形式（示例已截断）。 已返回: 始终 示例: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
msg 字符串	关于执行的操作的消息。 已返回: 始终 示例: "客户端 testclient 已 被 更新"
proposed 字典	建议的客户端的表示形式。 已返回: 始终 示例: {"clientId": "test"}

作者

• Eike Frost (@eikef)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 通信