OpenID Connect (OIDC)是一个身份验证协议，它是 OAuth 2.0 的扩展。虽然 OAuth 2.0 只是用于构建授权协议的框架，但主要不完整，但 OIDC 是一个功能齐全的身份验证和授权协议。OIDC 还使用 Json Web Token (JWT)标准集合。这些标准定义了身份令牌 JSON 格式，以及以紧凑和 Web 友好的方式对这些数据进行数字签名。

使用 OIDC 时，实际上有两种用例。第一个应用程序要求红帽单点登录服务器为其验证用户。成功登录后，应用将收到一个身份令牌和一个访问令牌。身份令牌 包含有关用户的信息，如用户名、电子邮件和其他配置集信息。访问令牌 由域数字签名，包含应用可使用的访问信息（如 user 角色映射），供应用程序用来决定用户被允许访问哪些资源。

第二种用例类型是希望获得远程服务访问权限的客户端。在这种情况下，客户端会要求红帽单点登录获取一个 访问令牌，供该用户用于对其他远程服务调用。Red Hat Single Sign-On 验证用户，然后要求用户同意授予请求它的客户端的访问权限。然后，客户端接收 访问令牌。此 访问令牌 由域数字签名。客户端可以使用此 访问令牌 在远程服务上发出 REST 调用。REST 服务提取 访问令牌，验证令牌的签名，然后根据令牌中的访问信息决定是否处理请求。

SAML 2.0 是与 OIDC 类似的规范，但有一个较老且更成熟的。它在 SOAP 中有根根和 WS-* 规格的 plethora，因此它往往会比 OIDC 更详细。SAML 2.0 主要是一种身份验证协议，可以在身份验证服务器和应用之间交换 XML 文档。XML 签名和加密用于验证请求和响应。

在红帽单点登录 SAML 中，提供两种用例：浏览器应用和 REST 调用。

使用 SAML 时，实际上有两种用例。第一个应用程序要求红帽单点登录服务器为其验证用户。成功登录后，应用将收到一个 XML 文档，其中包含一个名为 SAML 断言的内容，用于指定用户的各种属性。该 XML 文档由域数进行数字签名，包含应用可用于决定用户允许对应用程序访问哪些资源（如 user 角色映射）。

第二种用例类型是希望获得远程服务访问权限的客户端。在这种情况下，客户端要求红帽单点登录获得 SAML 断言，以便其用于代表用户调用其他远程服务。

在 OpenID Connect 和 SAML 间进行选择不只是使用较新的协议(OIDC)而不是旧的更成熟的协议(SAML)。

在大多数情况下，Red Hat Single Sign-On 建议使用 OIDC。

SAML 往往会比 OIDC 更详细。

除交换数据外，如果您比较的是，您会看到 OIDC 的设计旨在与 web 合作，而 SAML 被重新引入到 web 之上工作。例如，OIDC 更加适合 HTML5/JavaScript 应用程序，因为它比 SAML 更容易在客户端实现。由于令牌采用 JSON 格式，因此它们更容易被 JavaScript 使用。您还会发现一些在 Web 应用程序中实施安全性的附加功能。例如，请查看 iframe 技巧，说明规格用来轻松确定用户是否仍登录或未登录。

SAML 对其使用。当您看到 OIDC 规格的演变时，您会看到它们实现 SAML 多年的功能及更多功能。我们通常看到的是，用户选择 SAML 通过 OIDC，因为它比较成熟，同时还具有保护的现有应用程序。

Red Hat Single Sign-On 支持的每个 Java 适配器都可通过简单的 JSON 文件进行配置。这种情况可能如下所示：

{
  "realm" : "demo",
  "resource" : "customer-portal",
  "realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
  "auth-server-url" : "https://localhost:8443/auth",
  "ssl-required" : "external",
  "use-resource-role-mappings" : false,
  "enable-cors" : true,
  "cors-max-age" : 1000,
  "cors-allowed-methods" : "POST, PUT, DELETE, GET",
  "cors-exposed-headers" : "WWW-Authenticate, My-custom-exposed-Header",
  "bearer-only" : false,
  "enable-basic-auth" : false,
  "expose-token" : true,
  "verify-token-audience" : true,
  "credentials" : {
    "secret" : "234234-234234-234234"
  },

  "connection-pool-size" : 20,
  "socket-timeout-millis" : 5000,
  "connection-timeout-millis" : 6000,
  "connection-ttl-millis" : 500,
  "disable-trust-manager" : false,
  "allow-any-hostname" : false,
  "truststore" : "path/to/truststore.jks",
  "truststore-password" : "geheim",
  "client-keystore" : "path/to/client-keystore.jks",
  "client-keystore-password" : "geheim",
  "client-key-password" : "geheim",
  "token-minimum-time-to-live" : 10,
  "min-time-between-jwks-requests" : 10,
  "public-key-cache-ttl" : 86400,
  "redirect-rewrite-rules" : {
    "^/wsmaster/api/(.*)$" : "/api/$1"
  }
}

您可以将 ${…​} containure 用于系统属性替换。例如： ${jboss.server.config.dir} 替换为 /path/to/Red Hat Single Sign-On。也支持通过 env 前缀替换环境变量，如 ${env.MY_ENVIRONMENT_VARIABLE}。

初始配置文件可以从 admin 控制台获得。这可以通过打开 admin 控制台来完成，从菜单中选择 Clients 并单击对应的客户端。打开客户端页面后，点 Installation 选项卡并选择 Keycloak OIDC JSON。

以下是每个配置选项的描述：

您可以从 ZIP 文件或从 RPM 安装这个适配器。

为了保护 JBoss EAP 上部署的 WAR 应用安全，您必须安装并配置 Red Hat Single Sign-On 适配器子系统。然后，有两个选项来保护 WAR。

本节都介绍这两种方法。

适配器作为单独的归档提供，具体取决于您使用的服务器版本。

<extensions>
  <extension module="org.keycloak.keycloak-adapter-subsystem"/>
</extensions>

<profile>
  <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
     <secure-deployment name="WAR MODULE NAME.war">
        <realm>demo</realm>
        <auth-server-url>http://localhost:8081/auth</auth-server-url>
        <ssl-required>external</ssl-required>
        <resource>customer-portal</resource>
        <credential name="secret">password</credential>
     </secure-deployment>
  </subsystem>
</profile>

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    <realm name="demo">
        <auth-server-url>http://localhost:8080/auth</auth-server-url>
        <ssl-required>external</ssl-required>
    </realm>
    <secure-deployment name="customer-portal.war">
        <realm>demo</realm>
        <resource>customer-portal</resource>
        <credential name="secret">password</credential>
    </secure-deployment>
    <secure-deployment name="product-portal.war">
        <realm>demo</realm>
        <resource>product-portal</resource>
        <credential name="secret">password</credential>
    </secure-deployment>
    <secure-deployment name="database.war">
        <realm>demo</realm>
        <resource>database-service</resource>
        <bearer-only>true</bearer-only>
    </secure-deployment>
</subsystem>

您的安装已完成。

您必须订阅 JBoss EAP 6 存储库，然后才能从 RPM 安装 EAP 6 适配器。

您的安装已完成。

Red Hat Single Sign-On 支持保护在 JBoss Fuse 6 中运行的 Web 应用程序。

Fuse 支持以下项目的安全性：

<context-param>
    <param-name>keycloak.config.resolver</param-name>
    <param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>

<?xml version="1.0" encoding="UTF-8"?>

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:camel="http://camel.apache.org/schema/blueprint"
           xsi:schemaLocation="
       http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
       http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">

    <bean id="kcAdapterConfig" class="org.keycloak.representations.adapters.config.AdapterConfig">
        <property name="realm" value="demo"/>
        <property name="resource" value="admin-camel-endpoint"/>
        <property name="bearerOnly" value="true"/>
        <property name="authServerUrl" value="http://localhost:8080/auth" />
        <property name="sslRequired" value="EXTERNAL"/>
    </bean>

    <bean id="keycloakAuthenticator" class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator">
        <property name="adapterConfig" ref="kcAdapterConfig"/>
    </bean>

    <bean id="constraint" class="org.eclipse.jetty.util.security.Constraint">
        <property name="name" value="Customers"/>
        <property name="roles">
            <list>
                <value>admin</value>
            </list>
        </property>
        <property name="authenticate" value="true"/>
        <property name="dataConstraint" value="0"/>
    </bean>

    <bean id="constraintMapping" class="org.eclipse.jetty.security.ConstraintMapping">
        <property name="constraint" ref="constraint"/>
        <property name="pathSpec" value="/*"/>
    </bean>

    <bean id="securityHandler" class="org.eclipse.jetty.security.ConstraintSecurityHandler">
        <property name="authenticator" ref="keycloakAuthenticator" />
        <property name="constraintMappings">
            <list>
                <ref component-id="constraintMapping" />
            </list>
        </property>
        <property name="authMethod" value="BASIC"/>
        <property name="realmName" value="does-not-matter"/>
    </bean>

    <bean id="sessionHandler" class="org.keycloak.adapters.jetty.spi.WrappingSessionHandler">
        <property name="handler" ref="securityHandler" />
    </bean>

    <bean id="helloProcessor" class="org.keycloak.example.CamelHelloProcessor" />

    <camelContext id="blueprintContext"
                  trace="false"
                  xmlns="http://camel.apache.org/schema/blueprint">
        <route id="httpBridge">
            <from uri="jetty:http://0.0.0.0:8383/admin-camel-endpoint?handlers=sessionHandler&amp;matchOnUriPrefix=true" />
            <process ref="helloProcessor" />
            <log message="The message from camel endpoint contains ${body}"/>
        </route>
    </camelContext>

</blueprint>

javax.servlet;version="[3,4)",
javax.servlet.http;version="[3,4)",
org.apache.camel.*,
org.apache.camel;version="[2.13,3)",
org.eclipse.jetty.security;version="[9,10)",
org.eclipse.jetty.server.nio;version="[9,10)",
org.eclipse.jetty.util.security;version="[9,10)",
org.keycloak.*;version="18.0.12.redhat-00001",
org.osgi.service.blueprint,
org.osgi.service.blueprint.container,
org.osgi.service.event,

<bean id="securityHandlerRest" class="org.eclipse.jetty.security.ConstraintSecurityHandler">
    <property name="authenticator" ref="keycloakAuthenticator" />
    <property name="constraintMappings">
        <list>
            <ref component-id="constraintMapping" />
        </list>
    </property>
    <property name="authMethod" value="BASIC"/>
    <property name="realmName" value="does-not-matter"/>
</bean>

<bean id="sessionHandlerRest" class="org.keycloak.adapters.jetty.spi.WrappingSessionHandler">
    <property name="handler" ref="securityHandlerRest" />
</bean>


<camelContext id="blueprintContext"
              trace="false"
              xmlns="http://camel.apache.org/schema/blueprint">

    <restConfiguration component="jetty" contextPath="/restdsl"
                       port="8484">
        <!--the link with Keycloak security handlers happens here-->
        <endpointProperty key="handlers" value="sessionHandlerRest"></endpointProperty>
        <endpointProperty key="matchOnUriPrefix" value="true"></endpointProperty>
    </restConfiguration>

    <rest path="/hello" >
        <description>Hello rest service</description>
        <get uri="/{id}" outType="java.lang.String">
            <description>Just an helllo</description>
            <to uri="direct:justDirect" />
        </get>

    </rest>

    <route id="justDirect">
        <from uri="direct:justDirect"/>
        <process ref="helloProcessor" />
        <log message="RestDSL correctly invoked ${body}"/>
        <setBody>
            <constant>(__This second sentence is returned from a Camel RestDSL endpoint__)</constant>
        </setBody>
    </route>

</camelContext>

META-INF.cxf;version="[2.7,3.2)",
META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional,
org.apache.cxf.bus;version="[2.7,3.2)",
org.apache.cxf.bus.spring;version="[2.7,3.2)",
org.apache.cxf.bus.resource;version="[2.7,3.2)",
org.apache.cxf.transport.http;version="[2.7,3.2)",
org.apache.cxf.*;version="[2.7,3.2)",
org.springframework.beans.factory.config,
org.eclipse.jetty.security;version="[9,10)",
org.eclipse.jetty.util.security;version="[9,10)",
org.keycloak.*;version="18.0.12.redhat-00001"

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
           xsi:schemaLocation="
		http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
		http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd">

    <!-- JAXRS Application -->

    <bean id="customerBean" class="org.keycloak.example.rs.CxfCustomerService" />

    <jaxrs:server id="cxfJaxrsServer" address="/customerservice">
        <jaxrs:providers>
            <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
        </jaxrs:providers>
        <jaxrs:serviceBeans>
            <ref component-id="customerBean" />
        </jaxrs:serviceBeans>
    </jaxrs:server>


    <!-- Securing of whole /cxf context by unregister default cxf servlet from paxweb and re-register with applied security constraints -->

    <bean id="cxfConstraintMapping" class="org.eclipse.jetty.security.ConstraintMapping">
        <property name="constraint">
            <bean class="org.eclipse.jetty.util.security.Constraint">
                <property name="name" value="cst1"/>
                <property name="roles">
                    <list>
                        <value>user</value>
                    </list>
                </property>
                <property name="authenticate" value="true"/>
                <property name="dataConstraint" value="0"/>
            </bean>
        </property>
        <property name="pathSpec" value="/cxf/*"/>
    </bean>

    <bean id="cxfKeycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.PaxWebIntegrationService"
          init-method="start" destroy-method="stop">
        <property name="bundleContext" ref="blueprintBundleContext" />
        <property name="jettyWebXmlLocation" value="/WEB-INF/jetty-web.xml" />
        <property name="constraintMappings">
            <list>
                <ref component-id="cxfConstraintMapping" />
            </list>
        </property>
    </bean>

    <bean id="defaultCxfReregistration" class="org.keycloak.adapters.osgi.ServletReregistrationService" depends-on="cxfKeycloakPaxWebIntegration"
          init-method="start" destroy-method="stop">
        <property name="bundleContext" ref="blueprintBundleContext" />
        <property name="managedServiceReference">
            <reference interface="org.osgi.service.cm.ManagedService" filter="(service.pid=org.apache.cxf.osgi)" timeout="5000"  />
        </property>
    </bean>

</blueprint>

META-INF.cxf;version="[2.7,3.2)",
META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional,
org.apache.cxf.transport.http;version="[2.7,3.2)",
org.apache.cxf.*;version="[2.7,3.2)",
com.fasterxml.jackson.jaxrs.json;version="[2.5,3)",
org.eclipse.jetty.security;version="[9,10)",
org.eclipse.jetty.util.security;version="[9,10)",
org.keycloak.*;version="18.0.12.redhat-00001",
org.keycloak.adapters.jetty;version="18.0.12.redhat-00001",
*;resolution:=optional

service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root

{
  "realm" : "demo",
  "resource" : "hawtio-client",
  "auth-server-url" : "http://localhost:8080/auth",
  "ssl-required" : "external",
  "public-client" : true
}

Red Hat Single Sign-On 支持保护在 JBoss Fuse 7 中运行的 Web 应用程序。

JBoss Fuse 7 利用 Undertow 适配器，与 JBoss EAP 7 适配器相同，JBoss Fuse 7.4.0 与 Undertow HTTP 引擎捆绑在一起，而 Undertow 则用于运行各种 Web 应用。

Fuse 支持以下项目的安全性：

<context-param>
    <param-name>keycloak.config.resolver</param-name>
    <param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:camel="http://camel.apache.org/schema/blueprint"
           xsi:schemaLocation="
       http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
       http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint-2.17.1.xsd">

    <bean id="keycloakConfigResolver" class="org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver" >
        <property name="bundleContext" ref="blueprintBundleContext" />
    </bean>

    <bean id="helloProcessor" class="org.keycloak.example.CamelHelloProcessor" />

    <camelContext id="blueprintContext"
                  trace="false"
                  xmlns="http://camel.apache.org/schema/blueprint">

        <route id="httpBridge">
            <from uri="undertow-keycloak:http://0.0.0.0:8383/admin-camel-endpoint?matchOnUriPrefix=true&amp;configResolver=#keycloakConfigResolver&amp;allowedRoles=admin" />
            <process ref="helloProcessor" />
            <log message="The message from camel endpoint contains ${body}"/>
        </route>

    </camelContext>

</blueprint>

javax.servlet;version="[3,4)",
javax.servlet.http;version="[3,4)",
javax.net.ssl,
org.apache.camel.*,
org.apache.camel;version="[2.13,3)",
io.undertow.*,
org.keycloak.*;version="18.0.12.redhat-00001",
org.osgi.service.blueprint,
org.osgi.service.blueprint.container

<camelContext id="blueprintContext"
              trace="false"
              xmlns="http://camel.apache.org/schema/blueprint">

    <!--the link with Keycloak security handlers happens by using undertow-keycloak component -->
    <restConfiguration apiComponent="undertow-keycloak" contextPath="/restdsl" port="8484">
        <endpointProperty key="configResolver" value="#keycloakConfigResolver" />
        <endpointProperty key="allowedRoles" value="admin,superadmin" />
    </restConfiguration>

    <rest path="/hello" >
        <description>Hello rest service</description>
        <get uri="/{id}" outType="java.lang.String">
            <description>Just a hello</description>
            <to uri="direct:justDirect" />
        </get>

    </rest>

    <route id="justDirect">
        <from uri="direct:justDirect"/>
        <process ref="helloProcessor" />
        <log message="RestDSL correctly invoked ${body}"/>
        <setBody>
            <constant>(__This second sentence is returned from a Camel RestDSL endpoint__)</constant>
        </setBody>
    </route>

</camelContext>

META-INF.cxf;version="[2.7,3.3)",
META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional,
org.apache.cxf.bus;version="[2.7,3.3)",
org.apache.cxf.bus.spring;version="[2.7,3.3)",
org.apache.cxf.bus.resource;version="[2.7,3.3)",
org.apache.cxf.transport.http;version="[2.7,3.3)",
org.apache.cxf.*;version="[2.7,3.3)",
org.springframework.beans.factory.config,
org.keycloak.*;version="18.0.12.redhat-00001"

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
           xsi:schemaLocation="
		http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
		http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd">

    <!-- JAXRS Application -->
    <bean id="customerBean" class="org.keycloak.example.rs.CxfCustomerService" />

    <jaxrs:server id="cxfJaxrsServer" address="/customerservice">
        <jaxrs:providers>
            <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
        </jaxrs:providers>
        <jaxrs:serviceBeans>
            <ref component-id="customerBean" />
        </jaxrs:serviceBeans>
    </jaxrs:server>
</blueprint>

bundle.symbolicName = org.apache.cxf.cxf-rt-transports-http
context.id = default

context.param.keycloak.config.resolver = org.keycloak.adapters.osgi.HierarchicalPathBasedKeycloakConfigResolver

login.config.authMethod = KEYCLOAK

security.cxf.url = /cxf/customerservice/*
security.cxf.roles = admin, user

javax.ws.rs;version="[2,3)",
META-INF.cxf;version="[2.7,3.3)",
META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional,
org.apache.cxf.transport.http;version="[2.7,3.3)",
org.apache.cxf.*;version="[2.7,3.3)",
com.fasterxml.jackson.jaxrs.json;version="${jackson.version}"

service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root

如果要在没有选择使用 servlet 过滤器适配器的平台上部署 Java Servlet 应用程序。这个适配器的工作方式与其它适配器不同。您不会在 web.xml 中定义安全限制。反之，您可以使用 Red Hat Single Sign-On servlet 过滤器适配器定义一个过滤器映射来保护您要保护的 url 模式。

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">

	<module-name>application</module-name>

    <filter>
        <filter-name>Keycloak Filter</filter-name>
        <filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>Keycloak Filter</filter-name>
        <url-pattern>/keycloak/*</url-pattern>
        <url-pattern>/protected/*</url-pattern>
    </filter-mapping>
</web-app>

在上面的代码段中有两个 url-patterns。/ protected/* 是我们需要保护的文件，而 /keycloak/* url-pattern 处理来自 Red Hat Single Sign-On 服务器的回调。

如果您需要排除配置的 url-patterns 下的一些路径，您可以使用 Filter init-param keycloak.config.skipPattern 配置正则表达式，该正则表达式描述了 keycloak 过滤器应立即委派给 filter-chain。默认情况下不配置 skipPattern。

在没有 context-path 的情况下，与 requestURI 匹配模式。假定上下文路径 /myapp 是一个对 /myapp/index.html 的请求，它会根据跳过特征匹配 /index.html。

<init-param>
    <param-name>keycloak.config.skipPattern</param-name>
    <param-value>^/(path1|path2|path3).*</param-value>
</init-param>

请注意，您应该在 Red Hat Single Sign-On Admin 控制台中配置您的客户端，其 Admin URL 指向过滤器的 url-pattern 所涵盖的安全部分。

Admin URL 将回调到 Admin URL，以便执行（如 backchannel logout）的操作。因此，本例中的 Admin URL 应为 http[s]://hostname/{context-root}/keycloak。

如果您需要自定义会话 ID 映射器，您可以在 Filter init-param keycloak.config.idMapper 中配置类的完全限定名称。会话 ID 映射器是一个映射用户 ID 和会话 ID 的映射程序。默认配置了 org.keycloak.adapters.spi.InMemorySessionIdMapper。

<init-param>
    <param-name>keycloak.config.idMapper</param-name>
    <param-value>org.keycloak.adapters.spi.InMemorySessionIdMapper</param-value>
</init-param>

Red Hat Single Sign-On 过滤器具有与其他适配器相同的配置参数，但您必须将它们定义为 filter init 参数，而不是上下文参数。

要使用此过滤器，请在 WAR poms 中包括这个 maven 工件：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-servlet-filter-adapter</artifactId>
    <version>18.0.12.redhat-00001</version>
</dependency>

如果您需要直接访问令牌，可以使用 KeycloakSecurityContext 接口。如果您要从令牌（如用户配置集信息）检索其他详细信息，或者您想要调用受 Red Hat Single Sign-On 保护的 RESTful 服务，这可能很有用。

在 servlet 环境中，它作为 HttpServletRequest 中的属性在安全调用中可用：

httpServletRequest
    .getAttribute(KeycloakSecurityContext.class.getName());

或者，它位于 HttpSession 中不安全的请求：

httpServletRequest.getSession()
    .getAttribute(KeycloakSecurityContext.class.getName());

Red Hat Single Sign-On 对基于 servlet 的客户端适配器有一些错误处理功能。在身份验证过程中遇到错误时，红帽 Single Sign-On 将调用 HttpServletResponse.sendError（）。您可以在 web.xml 文件中设置一个错误页面来处理错误。红帽单点登录可以抛出 400、401、403 和 500 错误。

<error-page>
    <error-code>403</error-code>
    <location>/ErrorHandler</location>
</error-page>

Red Hat Single Sign-On 还设置可检索的 HttpServletRequest 属性。属性名称是 org.keycloak.adapters.spi.AuthenticationError，它应该被转换为 org.keycloak.adapters.OIDCAuthenticationError。

例如：

import org.keycloak.adapters.OIDCAuthenticationError;
import org.keycloak.adapters.OIDCAuthenticationError.Reason;
...

OIDCAuthenticationError error = (OIDCAuthenticationError) httpServletRequest
    .getAttribute('org.keycloak.adapters.spi.AuthenticationError');

Reason reason = error.getReason();
System.out.println(reason.name());

您可以通过多种方式从 Web 应用程序注销。对于 Jakarta EE servlet 容器，您可以调用 HttpServletRequest.logout（）。对于其他浏览器应用，您可以将浏览器重定向到 http://auth-server/auth/realms/{realm-name}/protocol/openid-connect/logout，如果用户使用其浏览器具有 SSO 会话，则将用户注销。当用户确认注销后，会进行实际注销。您可以选择包含 id_token_hint、post_logout_redirect_uri、client_id 等参数，如 OpenID Connect RP-Initiated Logout 中所述。因此，如果您在包含 id_token_hint 参数时，用户不需要显式确认该注销。注销后，只要提供用户，用户会自动重定向到指定的 post_logout_redirect_uri。请注意，在包含 post_logout_redirect_uri 时，您需要包含 client_id 或 id_token_hint 参数。

如果您想避免在注销过程中注销外部身份提供程序，您可以提供 启动_idp 的参数，并成为身份提供程序的身份（别名）问题。当作为外部身份提供程序发起的单个注销端点的一部分调用时，此参数很有用。initiated ing_idp 是 Red Hat Single Sign-On logout 端点的支持参数，除了 RP-Initiated Logout 规范中描述的参数之外。

当使用 HttpServletRequest.logout（） 选项时，适配器对通过刷新令牌的红帽单点登录服务器执行后端 POST 调用。如果从未保护的页面（没有检查有效令牌的页面）执行方法，则刷新令牌将不可用，在这种情况下，适配器会跳过调用。因此，建议使用一个受保护的页面来执行 HttpServletRequest.logout（），以便在需要时执行当前的令牌，并与红帽单点登录服务器交互。

Red Hat Single Sign-On 初始授权端点请求支持不同的参数。大多数参数都在 OIDC 规格 中所述。某些参数由基于适配器配置自动添加。但是，每个调用时还可添加一些参数。当您打开受保护的应用程序 URI 时，特定的参数将转发到 Red Hat Single Sign-On 授权端点。

例如，如果请求离线令牌，您可以使用 scope 参数打开受保护的应用程序 URI：

http://myappserver/mysecuredapp?scope=offline_access

参数 scope=offline_access 将自动转发到 Red Hat Single Sign-On 授权端点。

支持的参数有：

大多数参数都包括在 OIDC 规格。唯一的例外是参数 kc_idp_hint，它特定于 Red Hat Single Sign-On，并包含要使用的身份提供程序的名称。如需更多信息，请参阅《 服务器管理指南》 中的 Identity Brokering 章节。

当机密 OIDC 客户端需要发送后台请求（例如，交换令牌的代码，或刷新令牌）时，它需要与红帽单点登录服务器进行身份验证。默认情况下，可以通过三种方式验证客户端：客户端 ID 和客户端 secret，使用签名 JWT 进行客户端身份验证，或者使用客户端 secret 使用签名 JWT 进行客户端身份验证。

"credentials": {
    "secret": "19666a4f-32dd-4049-b082-684c74115f28"
}

"credentials": {
  "jwt": {
    "client-keystore-file": "classpath:keystore-client.jks",
    "client-keystore-type": "JKS",
    "client-keystore-password": "storepass",
    "client-key-password": "keypass",
    "client-key-alias": "clientkey",
    "algorithm": "RS256",
    "token-expiration": 10
  }
}

在我们的环境中，多元意味着可以使用多个红帽单点登录域保护单一目标应用程序(WAR)。域可以位于同一红帽单点登录实例或不同的实例上。

实际上，这意味着应用程序需要有多个 keycloak.json 适配器配置文件。

您可以有多个 WAR 实例，它们不同的适配器配置文件部署到不同的上下文路径。但是，这可能很不便，您可能还希望根据上下文路径以外的其他内容选择域。

Red Hat Single Sign-On 使可以有一个自定义配置解析器，以便您可以选择每个请求的适配器配置。

要实现这一点，首先需要创建 org.keycloak.adapters.KeycloakConfigResolver 的实现。例如：

package example;

import org.keycloak.adapters.KeycloakConfigResolver;
import org.keycloak.adapters.KeycloakDeployment;
import org.keycloak.adapters.KeycloakDeploymentBuilder;

public class PathBasedKeycloakConfigResolver implements KeycloakConfigResolver {

    @Override
    public KeycloakDeployment resolve(OIDCHttpFacade.Request request) {
        if (path.startsWith("alternative")) {
            KeycloakDeployment deployment = cache.get(realm);
            if (null == deployment) {
                InputStream is = getClass().getResourceAsStream("/tenant1-keycloak.json");
                return KeycloakDeploymentBuilder.build(is);
            }
        } else {
            InputStream is = getClass().getResourceAsStream("/default-keycloak.json");
            return KeycloakDeploymentBuilder.build(is);
        }
    }

}

您还需要配置用于 web.xml 中的 keycloak.config.resolver 上下文-param 的 KeycloakConfigResolver 实现：

<web-app>
    ...
    <context-param>
        <param-name>keycloak.config.resolver</param-name>
        <param-value>example.PathBasedKeycloakConfigResolver</param-value>
    </context-param>
</web-app>

本章与支持部署到 JBoss EAP 的集群应用程序相关。

根据您的应用程序是可用的一些选项：

处理集群的过程就像常规的应用程序一样简单。主要的原因是浏览器和服务器端应用程序向红帽单点登录发送请求，因此不像在您的负载均衡器上启用粘性会话那样简单。

"token-store": "cookie"

"register-node-at-startup": true,
"register-node-period": 600,

"always-refresh-token": true

默认情况下，JavaScript 适配器会创建一个隐藏 iframe，用于检测是否发生了 Single-Sign Out。这不需要任何网络流量，而是通过查看特殊状态 cookie 来检索的状态。通过在传递到 init 方法的选项中设置 checkLoginIframe: false 来禁用这个功能。

您不应该依赖于直接查看这个 cookie。其格式可能会改变，它也与 Red Hat Single Sign-On 服务器的 URL 关联，而不是您的应用程序。

默认情况下，JavaScript 适配器使用授权代码流。

通过这个流程，Red Hat Single Sign-On 服务器会向应用返回授权代码，而不是身份验证令牌。在浏览器重新定向到应用程序后，JavaScript 适配器会交换访问令牌 的代码 和刷新令牌。

Red Hat Single Sign-On 还支持 Implicit 流，在使用红帽单点登录验证成功后立即发送访问令牌。这可能比标准流性能更好，因为没有额外的请求交换令牌代码，但它在访问令牌过期时会产生影响。

但是，在 URL 片段中发送访问令牌可以是安全漏洞。例如，令牌可以通过 Web 服务器日志和浏览器历史记录泄露。

要启用隐式流，您需要在 Red Hat Single Sign-On Admin Console 中为客户端启用 Implicit Flow Enabled 标志。您还需要传递带有值 隐式 到 init 方法的参数 流 ：

keycloak.init({
    flow: 'implicit'
})

需要注意的一点是，只会提供访问令牌，且没有刷新令牌。这意味着，当访问令牌过期后，应用程序必须再次重定向到 Red Hat Single Sign-On，以获取新的访问令牌。

Red Hat Single Sign-On 还支持 混合 流程。

这要求客户端同时在管理控制台中启用 Standard Flow 和 Implicit Flow Enabled 标记。然后，Red Hat Single Sign-On 服务器会将代码和令牌发送到您的应用。访问令牌可以立即使用，而代码可以被交换用于访问和刷新令牌。与隐式流类似，混合流适合性能，因为访问令牌可以立即可用。但是，令牌仍然在 URL 中发送，前面提到的安全漏洞可能仍然适用。

混合流程的一个优点是，刷新令牌可供应用程序使用。

对于混合流程，您需要将参数 流 与值 hybrid 传递给 init 方法：

keycloak.init({
    flow: 'hybrid'
})

Keycloak 支持通过 Apache Cordova 开发的混合移动应用程序。JavaScript 适配器具有两种模式：cordova 和 cordova-native。

默认为 cordova，如果还没有配置适配器类型且存在 window.cordova，则适配器会自动选择。登录时，它会打开一个 InApp Browser，允许用户与红帽单点登录互动，然后再通过重定向到 http://localhost 来返回到应用程序。因此，您必须在管理控制台的客户端配置部分中将这个 URL 列列为有效的 redirect-uri。

虽然此模式易于设置，但它也有一些缺点：

使用此示例应用程序帮助您入门 ：https://github.com/keycloak/keycloak/tree/master/examples/cordova

另一种模式 cordova-native 采用不同的方法。它使用系统的浏览器打开登录页面。在用户通过身份验证后，浏览器会使用特殊的 URL 重新指向应用程序。在那里，Red Hat Single Sign-On 适配器可以通过从 URL 读取代码或令牌来完成登录。

您可以通过将适配器类型 cordova-native 传递给 init 方法来激活原生模式：

keycloak.init({
    adapter: 'cordova-native'
})

这个适配器需要两个附加插件：

每个平台上链接到应用程序的技术细节各有不同，且需要特殊设置。如需更多详情，请参阅 deeplinks 插件文档中的 Android 和 iOS 部分。

用于打开应用程序的不同链接：自定义方案（如 myapp://login 或 android-app://com.example.myapp/https/example.com/login）和 Universal Links(iOS)）/ Deep Links(Android)。虽然前者易于设置并更可靠工作，但之后会提供额外的安全性，因为它们是唯一的，并且只有域的所有者可以注册它们。custom-URLs 在 iOS 中已弃用。我们建议您使用通用链接和回退站点，并在其中使用 custom-url 链接来获得最佳的可靠性。

另外，我们推荐以下步骤提高与 Keycloak 适配器的兼容性：

<preference name="AndroidLaunchMode" value="singleTask" />

一个示例应用程序演示了如何使用 native-mode: https://github.com/keycloak/keycloak/tree/master/examples/cordova-native

有时需要运行默认不支持的 JavaScript 客户端（如 Capacitor）。要在这些未知环境中使用 JavasScript 客户端，可以传递自定义适配器。例如，第三方库可能会提供这样的适配器，以便可以在没有问题的情况下运行 JavaScript 客户端：

import Keycloak from 'keycloak-js';
import KeycloakCapacitorAdapter from 'keycloak-capacitor-adapter';

const keycloak = new Keycloak();

keycloak.init({
    adapter: KeycloakCapacitorAdapter,
});

这个特定软件包不存在，但它会提供一个很好的示例来把这个适配器传递给客户端。

也可以让自己的适配器实现，因此您必须实现 KeycloakAdapter 接口中描述的方法。例如，以下 TypeScript 代码确保正确实施所有方法：

import Keycloak, { KeycloakAdapter } from 'keycloak-js';

// Implement the 'KeycloakAdapter' interface so that all required methods are guaranteed to be present.
const MyCustomAdapter: KeycloakAdapter = {
    login(options) {
        // Write your own implementation here.
    }

    // The other methods go here...
};

const keycloak = new Keycloak();

keycloak.init({
    adapter: MyCustomAdapter,
});

通过省略类型信息来确保正确实施接口将完全保留给您，那么在一定程度上，您也可以在不进行 TypeScript 的情况下执行此操作。

JavaScript 适配器依赖于 Base64（window.btoa 和 window.atob）、HTML5 History API 以及可选的 Promise API。如果您需要支持没有这些可用的浏览器（例如，IE9），则需要添加填充器。

polyfill 库示例：

应用了各种浏览器的最新版本中的 Cookie 策略，以防止由第三方（如 Chrome 中的 SameSite）跟踪用户，或者完全阻止了第三方 Cookie。预计这些策略会随着时间的推移而变得更严格的限制，并由其他浏览器采用，最终导致浏览器不支持并阻止第三方上下文中的 Cookie。受此问题影响的适配器功能可能会在以后被弃用。

JavaScript 适配器依赖于 Session Status iframe、静默 check-sso 以及部分常规（非静默）check-sso。这些功能有限，或者完全禁用，具体取决于浏览器对 Cookie 的限制程度。适配器会尝试检测此设置并相应地做出反应。

假设您已经安装了 Node.js，并为您的应用程序创建一个文件夹：

mkdir myapp && cd myapp

使用 npm init 命令为您的应用程序创建 package.json。现在，在依赖列表中添加 Red Hat Single Sign-On 连接适配器：

    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-18.0.6-redhat-00001.tgz"
    }

在项目的根目录中，创建一个名为 server.js 的文件，并添加以下代码：

    const session = require('express-session');
    const Keycloak = require('keycloak-connect');

    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });

安装 express-session 依赖项：

    npm install express-session

要启动 server.js 脚本，请在 package.json 的"scripts"部分中添加以下命令：

    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "start" "node server.js"
    },

现在，我们可以使用以下命令运行我们的服务器：

    npm run start

默认情况下，这将查找名为 keycloak.json 的文件，以及应用程序的主要可执行文件，本例中为 root 文件夹，以初始化特定于密钥的设置，如公钥、域名和各种 URL。

在这种情况下，需要 Keycloak 部署来访问 Keycloak admin 控制台。

请访问链接如何使用 Podman 或 Docker部署 Keycloak 管理控制台

现在，我们已准备好通过访问 Red Hat Single Sign-On Admin Console → client（左侧侧边栏）- → 选择您的 client → Installation → Format Option → Keycloak OIDC JSON → Download 来获取 keycloak.json 文件

将下载的 文件粘贴到我们项目的根目录中。

这个方法的实例化会导致使用所有合理的默认值。另外，也可以提供配置对象，而不是 keycloak.json 文件：

    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080/auth',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };

    const keycloak = new Keycloak({ store: memoryStore }, kcConfig);

应用程序还可以使用以下方法将用户重定向到首选身份提供程序：

    const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);

    const session = require('express-session');
    const memoryStore = new session.MemoryStore();

    // Configure session
    app.use(
      session({
        secret: 'mySecret',
        resave: false,
        saveUninitialized: true,
        store: memoryStore,
      })
    );

    const keycloak = new Keycloak({ store: memoryStore });

    const keycloak = new Keycloak({ scope: 'offline_access' });

实例化后，将中间件安装到连接功能的应用程序中：

为此，首先需要安装 Express：

    npm install express

然后，我们的项目中需要 Express，如下所示：

    const express = require('express');
    const app = express();

并在以下代码中添加一个 Keycloak 中间件，并在 Express 中配置 Keycloak 中间件：

    app.use( keycloak.middleware() );

最后，我们把服务器设置为在端口 3000 上侦听 HTTP 请求，方法是将以下代码添加到 main.js 中：

    app.listen(3000, function () {
        console.log('App listening on port 3000');
    });

如果应用程序在 代理的代理后面运行，则必须根据代理指南中的表达 来配置终止 SSL 连接 Express。使用不正确的代理配置可能会导致生成的重定向 URI。

配置示例：

    const app = express();

    app.set( 'trust proxy', true );

    app.use( keycloak.middleware() );

要在访问资源之前检查用户进行身份验证，只需使用 keycloak.checkSso（）。只有在用户已经登录后，它将才进行身份验证。如果用户没有登录，浏览器将重新重定向到原先请求的 URL，并保持未经身份验证的：

    app.get( '/check-sso', keycloak.checkSso(), checkSsoHandler );

    app.get( '/complain', keycloak.protect(), complaintHandler );

    app.get( '/special', keycloak.protect('special'), specialHandler );

使用不同应用程序的应用程序角色 保护资源 ：

    app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );

使用 realm 角色保护资源：

    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );

    app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);

keycloak-enforcer 方法以两种模式运行，具体取决于 response_mode 配置选项的值。

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);

如果将 response_mode 设为 token，则代表您的应用程序的 bearer 令牌代表的主体从服务器获得权限。在本例中，由由服务器授予权限的 Keycloak 发布新访问令牌。如果服务器没有响应具有预期权限的令牌，则请求被拒绝。使用此模式时，您应该能够从请求中获取令牌，如下所示：

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
        const token = req.kauth.grant.access_token.content;
        const permissions = token.authorization ? token.authorization.permissions : undefined;

        // show user profile
    });

当应用程序使用会话时，首选使用这个模式，并希望从服务器缓存以前的决定，并自动处理刷新令牌。对于作为客户端和服务器的应用程序，此模式特别有用。

如果将 response_mode 设为 permissions （默认模式），服务器只返回授予权限的列表，而不会发出新的访问令牌。除了不提供新令牌外，此方法还通过 请求 公开服务器授予的权限，如下所示：

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
        const permissions = req.permissions;

        // show user profile
    });

无论使用是否使用了 response_mode，cloak .enforcer 方法将首先尝试检查发送到应用程序的 bearer 令牌中的权限。如果 bearer 令牌已执行预期的权限，则不需要与服务器交互来获取决策。当您的客户端能够在访问受保护的资源前从具有预期权限的服务器获取访问令牌时，可以使用 Keycloak Authorization Services（如增量授权）提供的一些功能，并避免在 keycloak.enforcer 被强制访问资源时对服务器获取访问令牌。

默认情况下，策略 enforcer 将使用定义为应用程序的 client_id （例如，通过 keycloak.json）引用支持 Keycloak 授权服务的 Keycloak 中的客户端。在这种情况下，如果客户端实际上是资源服务器，客户端不能是公共的。

如果您的应用程序同时充当公共客户端(frontend)和资源服务器，您可以使用以下配置使用您要强制执行的策略引用 Keycloak 中的不同客户端：

      keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})

建议您在 Keycloak 中使用不同的客户端来代表您的前端和后端。

如果使用 Keycloak 授权服务启用了保护应用程序，且您在 keycloak.json 中定义了客户端凭证，您可以将额外声明推送到服务器，并将其提供给您的策略以做出决策。为此，您可以定义一个 claims 配置选项，它需要一个会返回一个带有您要推送的声明的 JSON 的函数：

      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
          claims: function(request) {
            return {
              "http.uri": ["/protected/resource"],
              "user.agent": // get user agent  from request
            }
          }
        }), function (req, res) {
          // access granted

有关如何配置 Keycloak 以保护应用程序资源的详情，请查看授权服务 指南。

    function protectBySection(token, request) {
      return token.hasRole( request.params.section );
    }

    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );

高级登录配置：

默认情况下，所有未授权的请求都将被重定向到红帽单点登录登录页面，除非您的客户端只有 bearer-only。但是，机密或公共客户端可以托管可浏览和 API 端点。要防止对未经身份验证的 API 请求进行重定向并返回 HTTP 401，您可以覆盖 redirectToLogin 功能。

例如，这个覆盖会检查 URL 包含 /api/ 并禁用登录重定向：

    Keycloak.prototype.redirectToLogin = function(req) {
    const apiReqMatcher = /\/api\//i;
    return !apiReqMatcher.test(req.originalUrl || req.url);
    };

    app.use( keycloak.middleware( { logout: '/logoff' } ));

当调用查询参数 redirect_url 时，可以传递用户触发的 logout：

https://example.com/logoff?redirect_url=https%3A%2F%2Fexample.com%3A3000%2Flogged%2Fout

然后，这个参数被用作 OIDC logout 端点的重定向 url，并将用户重定向到 https://example.com/logged/out。

    app.use( keycloak.middleware( { admin: '/callbacks' } );

使用 Node.js 适配器用法的完整示例可在 Node.js 的 KeycloakQuickstart 中找到

要理解的最重要端点是 已知的 配置端点。它列出了与 Red Hat Single Sign-On 中的 OpenID Connect 实施相关的端点和其他配置选项。端点是：

/realms/{realm-name}/.well-known/openid-configuration

要获得完整的 URL，请添加 Red Hat Single Sign-On 的基本 URL，并将 {realm-name} 替换为您的域的名称。例如：

http://localhost:8080/auth/realms/master/.well-known/openid-configuration

某些 RP 库从此端点检索所有必需的端点，但对于其他端点，您可能需要单独列出端点。

/realms/{realm-name}/protocol/openid-connect/auth

/realms/{realm-name}/protocol/openid-connect/token

/realms/{realm-name}/protocol/openid-connect/userinfo

/realms/{realm-name}/protocol/openid-connect/logout

/realms/{realm-name}/protocol/openid-connect/certs

/realms/{realm-name}/protocol/openid-connect/token/introspect

/realms/{realm-name}/clients-registrations/openid-connect

/realms/{realm-name}/protocol/openid-connect/revoke

/realms/{realm-name}/protocol/openid-connect/auth/device

/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth

如果您需要手动验证红帽单点登录发布的访问令牌，您可以调用 内省端点。这种方法的缺点是您必须使网络调用 Red Hat Single Sign-On 服务器。如果您同时出现太多验证请求，这可能很慢，可能会给服务器过载。红帽单点登录访问令牌是数字签名和编码的 JSON Web 令牌(JWT)，使用 JSON Web 签名(JWS)。由于它们采用这种方式编码，因此允许您使用发布域的公钥在本地验证访问令牌。您可以在验证代码中硬编码域的公钥，或使用嵌入在 JWS 中的密钥 ID (KID) 的证书端点 来缓存公钥。根据您的代码，有很多第三方库可以使用 JWS 验证。

使用基于重定向的流时，将有效的重定向 uri 用于您的客户端非常重要。重定向 uri 应该尽量具体。这特别适用于客户端（公共客户端）应用程序。否则可能会导致：

在生产环境中，web 应用始终使用 https 作为所有重定向 URI。不要允许重定向到 http。

还有几个特殊的重定向 URI：

为确保您的客户端兼容 FAPI，您可以在域中配置客户端策略，如 服务器管理指南 所述，并将它们链接到 FAPI 支持的全局客户端配置集，这些配置文件在每个域中自动可用。您可以基于客户端符合的 FAPI 配置集，使用 fapi-1-baseline 或 fapi-1-advanced 配置集。

如果要使用 Pushed Authorization Request(PAR)，建议您的客户端同时针对 PAR 请求使用 fapi-1-baseline 配置集和 fapi-1-advanced。具体来说，fapi-1-baseline 配置集包含 pkce-enforcer executor，以确保客户端使用带有安全 S256 算法的 PKCE。FAPI 高级客户端不需要此项，除非它们使用 PAR 请求。

如果要以 FAPI 兼容方式使用 CIBA，请确保您的客户端同时使用 fapi-1-advanced 和 fapi-ciba 客户端配置文件。需要使用 fapi-1-advanced 配置集，或者包含所请求执行器的其他客户端配置集，因为 fapi-ciba 配置集包含仅 CIBA 特定的 executors。当强制 FAPI CIBA 规格的要求时，需要满足机密客户端或证书界访问令牌的执行。

红帽单点登录符合 Open Banking Brasil financial-grade API Security Profile 1.0 implementers Draft 2。与 FAPI 1 高级 规格相比，这个要求更为严格，因此可能需要以 更严格的方式配置客户端 策略来强制实施某些要求。特别是：

随着机密信息交换，所有交互都应该通过 TLS(HTTPS)加密。此外，FAPI 规格中对使用的密码套件和 TLS 协议版本有一些要求。要满足这些要求，您可以考虑配置允许的密码。此配置可以在 Elytron 子系统中的 KEYCLOAK_HOME/standalone/configuration/standalone-*.xml 文件中完成。例如，此元素可以在 tls → server-ssl-contexts下添加

<server-ssl-context name="kcSSLContext" want-client-auth="true" protocols="TLSv1.2" \
key-manager="kcKeyManager" trust-manager="kcTrustManager" \
cipher-suite-filter="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384" protocols="TLSv1.2" />

对 kcKeyManager 和 kcTrustManager 的引用引用引用对应的 Keystore 和 Truststore。有关更多详细信息以及 Red Hat Single Sign-On 文档，如 网络设置 部分或 X.509 身份验证 部分，请参阅 Wildfly Elytron 子系统文档。

Red Hat Single Sign-On 支持的每个 SAML 客户端适配器均可通过简单的 XML 文本文件配置。这种情况可能如下所示：

<keycloak-saml-adapter xmlns="urn:keycloak:saml:adapter"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="urn:keycloak:saml:adapter https://www.keycloak.org/schema/keycloak_saml_adapter_1_10.xsd">
    <SP entityID="http://localhost:8081/sales-post-sig/"
        sslPolicy="EXTERNAL"
        nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        logoutPage="/logout.jsp"
        forceAuthentication="false"
        isPassive="false"
        turnOffChangeSessionIdOnLogin="false"
        autodetectBearerOnly="false">
        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="http://localhost:8080/sales-post-sig/" password="test123"/>
                    <Certificate alias="http://localhost:8080/sales-post-sig/"/>
                </KeyStore>
            </Key>
        </Keys>
        <PrincipalNameMapping policy="FROM_NAME_ID"/>
        <RoleIdentifiers>
            <Attribute name="Role"/>
        </RoleIdentifiers>
        <RoleMappingsProvider id="properties-based-role-mapper">
            <Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
        </RoleMappingsProvider>
        <IDP entityID="idp"
             signaturesRequired="true">
        <SingleSignOnService requestBinding="POST"
                             bindingUrl="http://localhost:8081/auth/realms/demo/protocol/saml"
                    />

            <SingleLogoutService
                    requestBinding="POST"
                    responseBinding="POST"
                    postBindingUrl="http://localhost:8081/auth/realms/demo/protocol/saml"
                    redirectBindingUrl="http://localhost:8081/auth/realms/demo/protocol/saml"
                    />
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>
     </SP>
</keycloak-saml-adapter>

其中一些配置切换可能特定于适配器，一些配置交换机在所有适配器中都很常见。对于 Java 适配器，您可以使用 ${…​} parture 作为系统属性替换。例如： ${jboss.server.config.dir}

<SP entityID="sp"
    sslPolicy="ssl"
    nameIDPolicyFormat="format"
    forceAuthentication="true"
    isPassive="false"
    keepDOMAssertion="true"
    autodetectBearerOnly="false">
...
</SP>

        <Keys>
            <Key signing="true" >
               ...
            </Key>
        </Keys>

        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="myPrivate" password="test123"/>
                    <Certificate alias="myCertAlias"/>
                </KeyStore>
            </Key>
        </Keys>

<Keys>
   <Key signing="true">
      <PrivateKeyPem>
         2341251234AB31234==231BB998311222423522334
      </PrivateKeyPem>
      <CertificatePem>
         211111341251234AB31234==231BB998311222423522334
      </CertificatePem>
   </Key>
</Keys>

<SP ...>
  <PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>

<SP ...>
  <PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>

<RoleIdentifiers>
     <Attribute name="Role"/>
     <Attribute name="member"/>
     <Attribute name="memberOf"/>
</RoleIdentifiers>

...
<RoleIdentifiers>
    ...
</RoleIdentifiers>
<RoleMappingsProvider id="properties-based-role-mapper">
    <Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
</RoleMappingsProvider>
<IDP>
    ...
</IDP>

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>

roleA=roleX,roleY
roleB=

kc_user=roleZ

role\u0020A=roleX,roleY

<IDP entityID="idp"
     signaturesRequired="true"
     signatureAlgorithm="RSA_SHA1"
     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
...
</IDP>

<AllowedClockSkew unit="MILLISECONDS">3500</AllowedClockSkew>

<SingleSignOnService signRequest="true"
                     validateResponseSignature="true"
                     requestBinding="post"
                     bindingUrl="url"/>

<SingleLogoutService validateRequestSignature="true"
                     validateResponseSignature="true"
                     signRequest="true"
                     signResponse="true"
                     requestBinding="redirect"
                     responseBinding="post"
                     postBindingUrl="posturl"
                     redirectBindingUrl="redirecturl">

       <IDP entityID="idp">
            ...
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>

<HttpClient connectionPoolSize="10"
            disableTrustManager="false"
            allowAnyHostname="false"
            clientKeystore="classpath:keystore.jks"
            clientKeystorePassword="pwd"
            truststore="classpath:truststore.jks"
            truststorePassword="pwd"
            proxyUrl="http://proxy/"
            socketTimeout="5000"
            connectionTimeout="6000"
            connectionTtl="500" />

为了保护 JBoss EAP 上部署的 WAR 应用安全，您必须安装并配置 Red Hat Single Sign-On SAML Adapter subsystem。

然后，您可以在 WAR 中提供 keycloak 配置 /WEB-INF/keycloak-saml.xml 文件，并将 auth-method 更改为 web.xml 中的 KEYCLOAK-SAML。

您可以使用 ZIP 文件或 RPM 安装适配器。

每个适配器是在 Red Hat Single Sign-On 下载站点单独下载。

<server xmlns="urn:jboss:domain:1.4">

    <extensions>
        <extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
          ...
    </extensions>

    <profile>
        <subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1"/>
         ...
    </profile>

当您需要在受保护的 Web 层中创建的安全上下文被传播到您正调用的 EJB（其它 EE 组件）时，其中的 keycloak 安全域应当与 EJBs 和其他组件一起使用。否则此配置是可选的。

<server xmlns="urn:jboss:domain:1.4">
 <subsystem xmlns="urn:jboss:domain:security:1.2">
    <security-domains>
...
      <security-domain name="keycloak">
         <authentication>
           <login-module code="org.keycloak.adapters.jboss.KeycloakLoginModule"
                         flag="required"/>
          </authentication>
      </security-domain>
    </security-domains>

安全上下文自动传播到 EJB 层。

samesite-cookie(mode=None, cookie-pattern=JSESSIONID)

您的安装已完成。

您的安装已完成。

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">

	<module-name>customer-portal</module-name>

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Admins</web-resource-name>
            <url-pattern>/admin/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Customers</web-resource-name>
            <url-pattern>/customers/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>user</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>KEYCLOAK-SAML</auth-method>
        <realm-name>this is ignored currently</realm-name>
    </login-config>

    <security-role>
        <role-name>admin</role-name>
    </security-role>
    <security-role>
        <role-name>user</role-name>
    </security-role>
</web-app>

<extensions>
  <extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
</extensions>

<profile>
  <subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
    <secure-deployment name="WAR MODULE NAME.war">
      <SP entityID="APPLICATION URL">
        ...
      </SP>
    </secure-deployment>
  </subsystem>
</profile>

<subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
  <secure-deployment name="saml-post-encryption.war">
    <SP entityID="http://localhost:8080/sales-post-enc/"
        sslPolicy="EXTERNAL"
        nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        logoutPage="/logout.jsp"
        forceAuthentication="false">
      <Keys>
        <Key signing="true" encryption="true">
          <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
            <PrivateKey alias="http://localhost:8080/sales-post-enc/" password="test123"/>
            <Certificate alias="http://localhost:8080/sales-post-enc/"/>
          </KeyStore>
        </Key>
      </Keys>
      <PrincipalNameMapping policy="FROM_NAME_ID"/>
      <RoleIdentifiers>
        <Attribute name="Role"/>
      </RoleIdentifiers>
      <IDP entityID="idp">
        <SingleSignOnService signRequest="true"
            validateResponseSignature="true"
            requestBinding="POST"
            bindingUrl="http://localhost:8080/auth/realms/saml-demo/protocol/saml"/>

        <SingleLogoutService
            validateRequestSignature="true"
            validateResponseSignature="true"
            signRequest="true"
            signResponse="true"
            requestBinding="POST"
            responseBinding="POST"
            postBindingUrl="http://localhost:8080/auth/realms/saml-demo/protocol/saml"
            redirectBindingUrl="http://localhost:8080/auth/realms/saml-demo/protocol/saml"/>
        <Keys>
          <Key signing="true" >
            <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
              <Certificate alias="saml-demo"/>
            </KeyStore>
          </Key>
        </Keys>
      </IDP>
    </SP>
   </secure-deployment>
</subsystem>

如果要将 SAML 与不属于 servlet 平台的适配器的 Java servlet 应用程序搭配使用，您可以选择使用 Red Hat Single Sign-On 拥有的 servlet 过滤器。这个适配器的工作方式与其它适配器不同。您仍然需要指定一个 /WEB-INF/keycloak-saml.xml 文件，如 General Adapter Config 部分中定义，但您不会在 web.xml 中定义安全限制。反之，您可以使用 Red Hat Single Sign-On servlet 过滤器适配器定义一个过滤器映射来保护您要保护的 url 模式。

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">

	<module-name>customer-portal</module-name>

    <filter>
        <filter-name>Keycloak Filter</filter-name>
        <filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>Keycloak Filter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

Red Hat Single Sign-On 过滤器具有与与其他适配器相同的配置参数，但您必须将它们定义为 filter init 参数，而不是上下文参数。

如果您有不同的安全和不安全的 url 模式，可以定义多个过滤器映射。

当将 SP 与 IdP 注册时，您必须将 http[s]://hostname/{context-root}/saml 注册为 Assert Consumer Service URL 和 Single Logout Service URL。

要使用此过滤器，请在 WAR poms 中包括这个 maven 工件：

<dependency>
   <groupId>org.keycloak</groupId>
   <artifactId>keycloak-saml-servlet-filter-adapter</artifactId>
   <version>18.0.12.redhat-00001</version>
</dependency>

要使用 Multi Tenancy，keycloak.config.resolver 参数应作为过滤器参数传递。

    <filter>
        <filter-name>Keycloak Filter</filter-name>
        <filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
        <init-param>
            <param-name>keycloak.config.resolver</param-name>
            <param-value>example.SamlMultiTenantResolver</param-value>
        </init-param>
    </filter>

对于每个基于 servlet 的适配器，您注册了 assert 使用者服务 URL 的端点必须是 servlet 应用程序的基本 URL，附加有 /saml，即 https://example.com/contextPath/saml。

您可以通过多种方式从 web 应用程序注销。对于 Jakarta EE servlet 容器，您可以调用 HttpServletRequest.logout（）。对于任何其他浏览器应用程序，您可以将浏览器指向具有安全约束的 Web 应用的任何 url，并传递查询参数 GLO，例如 http://myapp?GLO=true。如果您通过浏览器具有 SSO 会话，这将注销。

<context-param>
    <param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
    <param-value>org.keycloak.adapters.saml.wildfly.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
</context-param>

<context-param>
    <param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
    <param-value>org.keycloak.adapters.saml.jbossweb.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
</context-param>

成功 SAML 登录后，您的应用程序代码可能希望获取通过 SAML 断言传递的属性值。HttpServletRequest.getUserPrincipal（） 返回 可进入 Red Hat Single Sign-On 特定类（名为 org.keycloak.adapters.saml.SamlPrincipal ）的主体对象。此对象允许您查看原始的断言，以及便利函数来查找属性值。

package org.keycloak.adapters.saml;

public class SamlPrincipal implements Serializable, Principal {
    /**
     * Get full saml assertion
     *
     * @return
     */
    public AssertionType getAssertion() {
       ...
    }

    /**
     * Get SAML subject sent in assertion
     *
     * @return
     */
    public String getSamlSubject() {
        ...
    }

    /**
     * Subject nameID format
     *
     * @return
     */
    public String getNameIDFormat() {
        ...
    }

    @Override
    public String getName() {
        ...
    }

    /**
     * Convenience function that gets Attribute value by attribute name
     *
     * @param name
     * @return
     */
    public List<String> getAttributes(String name) {
        ...

    }

    /**
     * Convenience function that gets Attribute value by attribute friendly name
     *
     * @param friendlyName
     * @return
     */
    public List<String> getFriendlyAttributes(String friendlyName) {
        ...
    }

    /**
     * Convenience function that gets first  value of an attribute by attribute name
     *
     * @param name
     * @return
     */
    public String getAttribute(String name) {
        ...
    }

    /**
     * Convenience function that gets first  value of an attribute by attribute name
     *
     *
     * @param friendlyName
     * @return
     */
    public String getFriendlyAttribute(String friendlyName) {
        ...
    }

    /**
     * Get set of all assertion attribute names
     *
     * @return
     */
    public Set<String> getAttributeNames() {
        ...
    }

    /**
     * Get set of all assertion friendly attribute names
     *
     * @return
     */
    public Set<String> getFriendlyNames() {
        ...
    }
}

Red Hat Single Sign-On 对基于 servlet 的客户端适配器有一些错误处理功能。在身份验证中遇到错误时，客户端适配器将调用 HttpServletResponse.sendError（）。您可以在 web.xml 文件中设置一个 错误页面 来处理错误。客户端适配器可能会抛出 400、401、403 和 500 错误。

<error-page>
    <error-code>403</error-code>
    <location>/ErrorHandler</location>
</error-page>

客户端适配器还设置可检索的 HttpServletRequest 属性。属性名称是 org.keycloak.adapters.spi.AuthenticationError。Typecast this object to: org.keycloak.adapters.saml.SamlAuthenticationError.此类可以告诉您发生的情况。如果没有设置此属性，则适配器不负责错误代码。

public class SamlAuthenticationError implements AuthenticationError {
    public static enum Reason {
        EXTRACTION_FAILURE,
        INVALID_SIGNATURE,
        ERROR_STATUS
    }

    public Reason getReason() {
        return reason;
    }
    public StatusResponseType getStatus() {
        return status;
    }
}

对问题进行故障排除的最佳方式是在客户端适配器和 Red Hat Single Sign-On Server 中打开 SAML 的调试。使用您的日志记录框架，将 org.keycloak.saml 软件包的日志级别设置为 DEBUG。启用这个端口可让您看到 SAML 请求和响应文档发送到服务器以及从服务器发送。

SAML 提供与 Multi Tenancy 相同的功能，这意味着单个目标应用程序(WAR)可以使用多个 Red Hat Single Sign-On 域进行保护。域可以位于同一红帽单点登录实例或不同的实例上。

要做到这一点，应用程序必须有多个 keycloak-saml.xml 适配器配置文件。

虽然您可以有多个 WAR 实例，但不同的适配器配置文件部署到不同的上下文路径，但这可能很不便，您可能还希望根据上下文路径以外的某些域选择域。

Red Hat Single Sign-On 使可以有一个自定义配置解析器，以便您可以选择每个请求使用哪些适配器配置。在 SAML 中，配置只在登录处理中非常感兴趣；一旦登录，会话会被身份验证，并且如果返回了 keycloak-saml.xml 并不重要。因此，为相同会话返回相同的配置是到达的正确方法。

为达成此目标，可创建 org.keycloak.adapters.saml.SamlConfigResolver 的实施。以下示例使用 Host 标头来定位正确的配置并加载它以及应用程序的 Java 类路径中的关联元素：

package example;

import java.io.InputStream;
import org.keycloak.adapters.saml.SamlConfigResolver;
import org.keycloak.adapters.saml.SamlDeployment;
import org.keycloak.adapters.saml.config.parsers.DeploymentBuilder;
import org.keycloak.adapters.saml.config.parsers.ResourceLoader;
import org.keycloak.adapters.spi.HttpFacade;
import org.keycloak.saml.common.exceptions.ParsingException;

public class SamlMultiTenantResolver implements SamlConfigResolver {

    @Override
    public SamlDeployment resolve(HttpFacade.Request request) {
        String host = request.getHeader("Host");
        String realm = null;
        if (host.contains("tenant1")) {
            realm = "tenant1";
        } else if (host.contains("tenant2")) {
            realm = "tenant2";
        } else {
            throw new IllegalStateException("Not able to guess the keycloak-saml.xml to load");
        }

        InputStream is = getClass().getResourceAsStream("/" + realm + "-keycloak-saml.xml");
        if (is == null) {
            throw new IllegalStateException("Not able to find the file /" + realm + "-keycloak-saml.xml");
        }

        ResourceLoader loader = new ResourceLoader() {
            @Override
            public InputStream getResourceAsStream(String path) {
                return getClass().getResourceAsStream(path);
            }
        };

        try {
            return new DeploymentBuilder().build(is, loader);
        } catch (ParsingException e) {
            throw new IllegalStateException("Cannot load SAML deployment", e);
        }
    }
}

您还必须配置在 web.xml 中用于 keycloak.config.resolver context-param 的 SamlConfigResolver 实现：

<web-app>
    ...
    <context-param>
        <param-name>keycloak.config.resolver</param-name>
        <param-value>example.SamlMultiTenantResolver</param-value>
    </context-param>
</web-app>

涉及两个主机：

以下所有步骤需要在带有 root 权限的 $sp_host 上执行。

yum install httpd mod_auth_mellon mod_ssl openssl

mkdir /etc/httpd/saml2

 <Location / >
    MellonEnable info
    MellonEndpointPath /mellon/
    MellonSPMetadataFile /etc/httpd/saml2/mellon_metadata.xml
    MellonSPPrivateKeyFile /etc/httpd/saml2/mellon.key
    MellonSPCertFile /etc/httpd/saml2/mellon.crt
    MellonIdPMetadataFile /etc/httpd/saml2/idp_metadata.xml
 </Location>
 <Location /private >
    AuthType Mellon
    MellonEnable auth
    Require valid-user
 </Location>

浏览器计划将 Cookie 的 SameSite 属性的默认值设置为 Lax。此设置表示，仅当请求源自于同一域中时，cookies 才会发送到应用程序。这个行为可能会影响 SAML POST 绑定，这可能会变为无法正常工作。要保留 mod_auth_mellon 模块的完整功能，我们建议将 mod_auth_mellon 创建的 cookie 的 SameSite 值设置为 None。不这样做可能会导致无法使用 Red Hat Single Sign-On 进行登录。

要将 SameSite 值设为 None，请将以下配置添加到 mellon.conf 文件中的 <Location / > tag。

MellonSecureCookie On
MellonCookieSameSite none

对此配置的支持在 0.16.0 版的 mod_auth_mellon 模块中可用。

bearer 令牌可以代表用户或服务帐户发布。调用端点需要以下权限（请参阅 "服务器管理指南" 以了解更多详细信息）：

如果您使用 bearer 令牌来创建客户端，建议仅使用具有 create-client 角色的服务帐户的令牌（详情请参阅 服务器管理指南 ）。

注册新客户端的建议方法是使用初始访问令牌。初始访问令牌只能用于创建客户端，并且具有可配置的到期时间，以及可以创建客户端数的可配置限制。

通过 admin 控制台可以创建初始访问令牌。要创建新的初始访问令牌，首先在 admin 控制台中选择域，然后单击左侧菜单中的 Realm Settings，然后在页面中显示的标签页里单击 Client Registration。最后，单击 Initial Access Tokens 子选项卡。

现在，您可以看到任何现有的初始访问令牌。如果您有访问权限，可以删除不再需要的令牌。您只能在创建令牌时检索令牌值。要创建新令牌，请点 Create。现在，您可以选择性地添加令牌有效的时长，以及可以使用令牌创建多少个客户端。在点 Save the token 值后会显示。

现在，复制/粘贴此令牌非常重要，因为您将无法在以后检索它。如果您忘记复制/粘贴，请删除令牌并创建令牌。

在调用客户端注册服务时，令牌值用作标准 bearer 令牌，方法是将其添加到请求的 Authorization 标头中。例如：

Authorization: bearer eyJhbGciOiJSUz...

当您通过客户端注册服务创建客户端时，响应将包含注册访问令牌。通过注册访问令牌，您可以在以后检索客户端配置，但也可更新或删除客户端。注册访问令牌会包含在请求中，其方式与 bearer 令牌或初始访问令牌相同。注册访问令牌只有效一次，使用响应时将包括新令牌。

如果在客户端注册服务之外创建客户端，它不会关联注册访问令牌。您可以通过 admin 控制台创建一个。如果您丢失了特定客户端的令牌，这也很有用。要在 admin 控制台中创建新令牌，并点击 Credentials。然后点击 生成注册访问令牌。

无论登录方法如何，登录的帐户需要适当的权限才能执行客户端注册操作。请记住，非主域中的任何帐户只能有一个权限管理同一域中客户端。如果需要管理不同的域，您可以在不同的域中配置多个用户，也可以在 master 域中创建单个用户，并在不同的域中管理客户端的角色。

您不能使用客户端注册 CLI 配置用户。使用 Admin Console Web 界面或 Admin Client CLI 配置用户。如需了解更多详细信息，请参阅 服务器管理指南。

当 kcreg 成功登录时，它会接收授权令牌并将其保存在私有配置文件中，以便令牌可用于后续调用。有关配置文件的更多信息，请参阅 第 6.4.2 节 “使用其他配置”。

有关使用客户端注册 CLI 的详情，请查看内置的帮助。

例如，在：

$ kcreg.sh help

c:\> kcreg help

有关启动经过身份验证的会话的更多信息，请参阅 kcreg config credentials --help。

默认情况下，客户端注册 CLI 会在用户主目录下自动维护默认位置 ./.keycloak/kcreg.config 的配置文件。您可以使用 --config 选项指向其他文件或位置，以并行维护多个经过身份验证的会话。从单一线程执行与单个配置文件关联的操作是最安全的方法。

您可能需要通过将 --no-config 选项与所有命令一起使用来避免将 secret 存储在配置文件中，即使它较方便，但需要更多令牌请求来执行。使用每个 kcreg 调用指定所有身份验证信息。

在他们想使用的 Red Hat Single Sign-On 服务器上未配置帐户的开发人员可使用客户端注册 CLI。只有域管理员向开发人员发出 Initial Access Token 时，才能实现。它由域管理员决定如何和何时发布这些令牌。域管理员可以限制 Initial Access Token 的最长期限，以及可使用它创建的客户端总数。

当开发人员具有 Initial Access Token 后，开发人员就可以使用它来创建新客户端，而无需向 kcreg 配置凭证 进行身份验证。Initial Access Token 可以存储在配置文件中，或者指定为 kcreg create 命令的一部分。

例如，在：

$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient

或者

$ kcreg.sh create -s clientId=myclient -t $TOKEN

c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient

或者

c:\> kcreg create -s clientId=myclient -t %TOKEN%

在使用 Initial Access Token 时，服务器响应包括新发布的注册访问令牌。该客户端的所有后续操作都需要通过与该令牌进行身份验证来执行，这仅对该客户端有效。

客户端注册 CLI 自动使用其专用配置文件来保存并使用其关联的客户端。只要所有客户端操作都使用相同的配置文件，开发人员不需要进行身份验证以这种方式创建、更新或删除创建的客户端。

有关初始访问和注册访问令牌的更多信息，请参阅客户端注册。

运行 kcreg config initial-token --help 和 kcreg config registration-token --help 命令以了解有关如何使用 Client Registration CLI 配置令牌的更多信息。

在使用凭据进行身份验证或配置初始访问令牌后，第一项任务通常是创建新客户端。通常，您可能希望使用准备的 JSON 文件作为模板，并设置或覆盖某些属性。

以下示例演示了如何读取 JSON 文件，覆盖任何客户端 id，设置任何其他属性，并在成功创建后将配置打印到标准输出。

$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o

C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o

运行 kcreg create --help 来获取有关 kcreg create 命令的更多信息。

您可以使用 kcreg attrs 来列出可用的属性。请记住，许多配置属性没有检查有效或一致性。您需要指定适当的值。请记住，您不应具有模板中的任何 id 字段，不应将它们指定为 kcreg create 命令的参数。

您可以使用 kcreg get 命令检索现有客户端。

例如，在：

$ kcreg.sh get myclient

C:\> kcreg get myclient

您还可以作为适配器配置文件检索客户端配置，该文件可以与 Web 应用程序打包。

例如，在：

$ kcreg.sh get myclient -e install > keycloak.json

C:\> kcreg get myclient -e install > keycloak.json

运行 kcreg get --help 命令以了解有关 kcreg get 命令的更多信息。

更新客户端配置有两种方法。

种方法是在获取当前配置后向服务器提交完整的新状态，将其保存到文件中，编辑该文件，并将它发回到服务器。

例如，在：

$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json

C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json

第二个方法获取当前客户端，设置或删除它的字段，然后在一个步骤中重新发布它。

例如，在：

$ kcreg.sh update myclient -s enabled=false -d redirectUris

C:\> kcreg update myclient -s enabled=false -d redirectUris

您还可以使用仅包含要应用的更改的文件，因此不必将过多的值指定为参数。在这种情况下，指定 --merge 告知客户端注册 CLI，而不是将 JSON 文件视为完整的新配置，而是应该将其视为要通过现有配置应用的一组属性。

例如，在：

$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json

C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json

运行 kcreg update --help 命令以了解有关 kcreg update 命令的更多信息。

使用以下示例删除客户端。

$ kcreg.sh delete myclient

C:\> kcreg delete myclient

运行 kcreg delete --help 命令以了解有关 kcreg delete 命令的更多信息。

当使用 --no-config 模式执行创建、读取、更新和删除(CRUD)操作时，客户端注册 CLI 无法为您处理注册访问令牌。在这种情况下，可能会丢失最近为客户端发出的注册访问令牌，这样就无法在该客户端上执行进一步的 CRUD 操作而无需与有 管理客户端 权限的帐户进行身份验证。

如果您有权限，您可以为客户端发布新的注册访问令牌，并将其打印到标准输出或保存到您选择的配置文件中。否则，您需要询问域管理员为您的客户端发布新的注册访问令牌并将其发送给您。然后，您可以通过 --token 选项将其传递给任何 CRUD 命令。您还可以使用 kcreg config registration-token 命令将新令牌保存在配置文件中，并使客户端注册 CLI 会自动为您处理它。

运行 kcreg update-token --help 命令以了解有关 kcreg update-token 命令的更多信息。

来自交换调用的成功响应将返回 HTTP 200 响应代码，它带有依赖于 requested-token-type 和 requested_issuer 请求的内容类型。OAuth 请求的令牌类型将返回 JSON 文档，如 OAuth Token Exchange 规范中所述。

{
   "access_token" : ".....",
   "refresh_token" : ".....",
   "expires_in" : "...."
 }

请求刷新令牌的客户端将在响应中返回访问和刷新令牌。仅请求访问令牌类型的客户端仅获得响应中的访问令牌。通过 requested_issuer paramater 请求外部签发者的客户端可能会包含过期信息。

错误响应通常低于 400 HTTP 响应代码类别，但其他错误状态代码可以根据错误的严重性进行返回。错误响应可能包括内容取决于 requested_issuer。基于 OAuth 的交换可能会返回 JSON 文档，如下所示：

{
   "error" : "...."
   "error_description" : "...."
}

可以根据交换类型返回额外的错误声明。例如，如果用户没有身份提供程序的链接，OAuth Identity Providers 可能包含额外的 account-link-url 声明。该链接可用于客户端发起链路请求。

本章的其余部分介绍了设置要求，并为不同的交换场景提供示例。为了简单起见，可以将当前域报告为 内部 令牌来报告令牌，以及由外部域或身份提供程序报告的令牌作为 外部 令牌。

希望为不同客户端交换令牌的客户端需要在管理控制台中授权。您需要在您要交换的目标客户端中定义 token-exchange fine grain 权限。

您的客户端现在有调用的权限。如果您没有正确执行此操作，如果您尝试进行交换，将得到一个 403 Forbidden 响应。

当客户端交换针对其他客户端的令牌的现有令牌时，请使用 audience 参数。此参数必须是您在 Admin 控制台中配置的目标客户端的客户端标识符。

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:refresh_token" \
    -d "audience=target-client" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

subject_token 参数必须是目标域的访问令牌。如果您的 requested_token_type 参数是一个刷新令牌类型，则响应将同时包含访问令牌、刷新令牌和过期。以下是您从这个调用中获取的 JSON 响应示例：

如果没有设置 使用者 参数，则参数的值默认为生成令牌交换请求的客户端。

与机密客户端不同，公共客户端不允许使用来自其他客户端的令牌来执行令牌交换。如果您传递了 subject_token，发布令牌的 （机密）客户端应与客户端发出请求匹配；如果向其他客户端发布，则发出请求的客户端应当位于使用者上。

如果您明确设置目标 audience （客户端与发出请求的客户端不同），您应确保为客户端集配置了 token-exchange 范围权限，设置 audience 权限以允许客户端成功完成交换。

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}

外部令牌交换请求内部将被拒绝使用 403, Forbidden 响应，直到您为调用客户端授予与外部身份提供程序交换令牌的权限。要向客户端授予权限，您需要进入身份提供程序的配置页面到 Permissions 选项卡。

您的客户端现在有调用的权限。如果您没有正确执行此操作，如果您尝试进行交换，将得到一个 403 Forbidden 响应。

当您的客户端将现有的内部令牌切换到外部时，您要提供 requested_issuer 参数。参数必须是配置的身份提供程序的别名。

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "requested_issuer=google" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

subject_token 参数必须是目标域的访问令牌。requested_token_type 参数必须是 urn:ietf:params:oauth:token-type:access_token 或 left blank。目前不支持其他请求的令牌类型。以下是您从这个调用中获取的 JSON 响应成功的示例。

{
   "access_token" : "....",
   "expires_in" : 3600
   "account-link-url" : "https://...."
}

如果外部身份提供程序没有以任何原因链接，您可以使用此 JSON 文档获取 HTTP 400 响应代码：

{
   "error" : "....",
   "error_description" : "..."
   "account-link-url" : "https://...."
}

错误 声明将为 token_expired 或 not_linked。提供了 account-link-url 声明，客户端可以执行 客户端初始化帐户链接。大多数（如果不是全部）供应商都需要通过浏览器 OAuth 协议链接。使用 account-link-url 时，只需在其中添加 redirect_uri 查询参数，并可转发浏览器来执行链接。

在进行外部令牌交换之前，您可以为调用客户端授予该交换的权限。这个权限的方式相同，与 授予外部权限的内部 权限相同。

如果还提供一个 audience 参数，其值指向调用者之外的不同客户端，还必须授予调用客户端的权限，以便与 audience 参数的特定目标客户端交换。本节前面将讨论如何 执行此操作。

subject_token_type 必须是 urn:ietf:params:oauth:token-type:access_token 或 urn:ietf:params:oauth:token-type:jwt。如果类型是 urn:ietf:params:oauth:token-type:access_token，您指定 subject_issuer 参数，它需要是配置的身份供应商的别名。如果类型为 urn:ietf:params:oauth:token-type:jwt，则提供程序将通过 JWT 中的 签发者 声明匹配，该提供商必须是提供程序的别名或提供程序配置中的注册签发者。

为进行验证，如果令牌是一个访问令牌，则会调用该提供程序的用户信息服务来验证令牌。成功调用意味着访问令牌有效。如果主体令牌是一个 JWT，如果提供程序启用了签名验证，则会试图进行尝试，否则它将默认在用户 info 服务上调用 以验证令牌。

默认情况下，Aded 内部令牌将使用调用客户端使用为调用客户端定义的协议映射程序来确定令牌中的内容。另外，您可以使用 audience 参数指定不同的目标客户端。

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    -d "subject_issuer=myOidcProvider" \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

如果您的 requested_token_type 参数是一个刷新令牌类型，则响应将同时包含访问令牌、刷新令牌和过期。以下是您从这个调用中获取的 JSON 响应示例：

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}

subject 令牌代表的用户必须具有模拟其他用户的权限。有关如何启用这个权限的服务器 管理指南。它可以通过角色完成，也可以通过更精细的管理员权限完成。

根据其他章节中所述进行请求，但另外另外指定 requested_subject 参数。此参数的值必须是用户名或用户 id。

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    -d "requested_subject=wburke" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token

如果提供 audience 参数，则调用客户端必须具有与客户端交换的权限。本章前文中介绍了如何设置此设置。

另外，调用客户端必须被授予模拟用户的权限。在管理控制台中.

现在，您的客户端具有模拟用户的权限。如果您没有正确执行此操作，如果您尝试进行这类交换，您将得到一个 403 Forbidden 响应。

要发出请求，只需指定 requested_subject 参数。这必须是有效用户的用户名或用户 id。如果您想要，还可以指定 audience 参数。

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "requested_subject=wburke" \
    http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token