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 版本的蛇形命名法版本。提供了别名，因此也可以使用 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

属性

字典

此客户端的更多属性的字典。这可以包含各种配置设置；示例在示例部分中给出。虽然没有提供允许的选项的详尽列表；下面列出了 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

字符串

布尔值指定 SAML 文档是否应由领域签名。

saml.server.signature.keyinfo.ext

字符串

对于 SAML 客户端，布尔值指定是否应通过在 SAML 扩展元素中包含签名密钥 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

string / 必需

Keycloak 实例的 URL。

auth_password

别名: password

字符串

用于进行 API 访问身份验证的密码。

auth_realm

字符串

用于进行 API 访问身份验证的 Keycloak realm 名称。

auth_username

别名: username

字符串

用于进行 API 访问身份验证的用户名。

authentication_flow_binding_overrides

别名: authenticationFlowBindingOverrides

字典

在 community.general 3.4.0 中添加

覆盖 realm 身份验证流程绑定。

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，可以使用 use.jwks.url、jwks.url 和 jwt.credential.certificate 键在 attributes 模块参数中配置其行为。 对于 client-x509，可以使用 x509.allow.regex.pattern.comparison 和 x509.subjectdn 键在 attributes 模块参数中配置要接受的证书。

这是 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

list / elements=string

在 community.general 4.7.0 中添加

默认客户端作用域的列表。

default_roles

别名: defaultRoles

list / elements=string

此客户端的默认角色列表。 如果引用的客户端角色尚不存在，将创建它们。 这是 Keycloak REST API 中的 “defaultRoles”。

description

字符串

Keycloak 中客户端的描述。

direct_access_grants_enabled

别名: directAccessGrantsEnabled

布尔值

是否为此客户端启用了直接访问授权（OpenID Connect）。 这是 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

list / elements=string

在 community.general 4.7.0 中添加

可选客户端作用域列表。

protocol

字符串

客户端类型。

仅在创建时有效，如果省略 protocol，则默认值为 openid-connect。

docker-v2 值已在 community.general 8.6.0 中添加。

选项

  • "openid-connect"

  • "saml"

  • "docker-v2"

protocol_mappers

别名: protocolMappers

列表 / 元素=字典

一个字典列表，定义此客户端的协议映射器。这对应 Keycloak REST API 中的 ‘protocolMappers’。

config

字典

字典，用于指定协议映射器的配置选项；内容取决于 protocol_mappers[].protocolMapper 的值，除了映射器的源代码及其父类之外，没有其他文档记录。下面给出一个示例。最简单的方法是通过在 existing 字段中通过 check-mode 转储已存在的协议映射器配置来获取有效的配置值。

consentRequired

布尔值

指定用户是否需要为该映射器处于活动状态而向客户端提供同意。

选项

  • false

  • true

consentText

字符串

用户将看到并接受的同意的人类可读名称。

id

字符串

通常是一个 UUID，指定此协议映射器实例的内部 ID。

name

字符串

此协议映射器的名称。

protocol

字符串

指定此协议映射器处于活动状态的协议。

选项

  • "openid-connect"

  • "saml"

  • "docker-v2"

protocolMapper

字符串

此协议映射器类型的 Keycloak 内部名称。虽然不可能提供详尽的列表，因为用户可以通过 SPI 扩展 Keycloak，但默认情况下，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

字符串

要在其中创建客户端的 realm。

默认值: "master"

redirect_uris

别名: redirectUris

list / elements=string

此客户端可接受的重定向 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（默认值）时，您可以在此处指定一个 secret（否则，如果它不存在，则会生成一个）。如果更改此 secret，模块当前不会注册更改（但已更改的 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

list / elements=string

允许的 CORS 来源列表。这对应 Keycloak REST API 中的 ‘webOrigins’。

属性

属性

支持

描述

check_mode

支持: 完全

可以在 check_mode 下运行，并返回已更改状态预测，而无需修改目标。

diff_mode

支持: 完全

当处于差异模式时，将返回已更改（或可能需要在 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)