[16.0.0.3 及更高版本]

为 OpenID Connect 配置 JSON Web Token 认证

您可以将 Liberty 服务器配置为接受 JSON Web Token (JWT) 令牌作为来自受信任认证代理、受信任服务客户机或 OAuth 授权服务器的认证令牌。

关于此任务

要将 Liberty 服务器配置为接受 JWT 令牌作为认证令牌,请启用 openidConnectClient-1.0 功能部件,设置 inboundPropagation="required",并配置信任库和 SSL。可以选择指定其他 JWT 配置(例如,用户注册表、认证过滤器和声明到主体集的映射)。将 JWT 用作认证令牌的配置与在 Liberty 中配置 OpenID Connect 客户机类似。

任何具有 JWT 令牌的受信任方都可以使用该令牌来访问 Liberty 中的相关联资源。Liberty 资源服务器验证 JWT 令牌并从 JWT 令牌创建认证主体集。要接受 JWT 令牌作为认证令牌,其中必须包含 isssubexp 声明,且必须使用 RS256 或 HS256 算法进行签名。不支持加密 JWT。以下示例显示解码的 JWT 有效内容:
{
	"iss":"https://idp.acme.com:8020/jwt",
	"sub":"marissa@acme.com",
	"exp":1385066178,
	"aud":"https://resource.acme.com/services",
	"iat":1385062578,
	“groupIds”: [
	    “group1”, “group2”
	 ]  
}

过程

  1. openidConnectClient-1.0 Liberty 功能部件及任何其他所需功能部件添加至 server.xml 文件。openidConnectClient-1.0 功能部件至少需要 ssl-1.0 功能部件。在 server.xml 文件的 featureManager 元素内添加以下元素声明:
    <feature>openidConnectClient-1.0</feature> 	
    <feature>ssl-1.0</feature>
  2. 配置 openidConnectClient 元素并设置 inboundPropagation="required"。有关其他 openidConnectClient 属性的信息,请参阅OpenID Connect 客户机 (openidConnectClient)

    以下样本配置假定 JWT 令牌颁发者支持 JSON Web Key (JWK) 并使用 RS256 算法进行签名。

    <openidConnectClient id="RS" inboundPropagation="required"		
      jwkEndpointUrl="https://acme.com/jwtserver/jwk" signatureAlgorithm="RS256"
      issuerIdentifier="https://idp.acme.com:8020/jwt" >		
    </openidConnectClient>
  3. 配置信任库以包含 JWT 端点证书,以便 Liberty 服务器可建立到 JWK 端点的 SSL 连接。信任库在 server.xml 文件的 keyStore 元素上配置。 配置 SSL 以引用此信任库后,可以将 SSL 配置设置为服务器缺省 SSL 配置,或针对 openidConnectClient 元素的 sslRef 属性指定信任库标识。

    如果 JWT 颁发者不支持 JWK 且 JWT 改为使用 X.509 证书签名,请将颁发者的 X.509 证书导入信任库。在 openidConnectClient 元素中,针对 trustStoreRef 属性指定信任库标识,并针对 trustAliasName 属性引用证书。

    如果通过将共享密钥与 HMAC-SHA256 算法配合使用对 JWT 进行签名,请针对 sharedKeyclientSecret 属性定义共享密钥。

    有关信任库或密钥库的信息,请参阅在 Liberty 中启用 SSL 通信

  4. 配置 openidConnectClient 元素的 issuerIdentifier 属性以匹配 JWT 颁发者 iss 声明。

    例如,如果 JWT 令牌包含 "iss":"https://idp.acme.com:8020/jwt",请设置 issuerIdentifier="https://idp.acme.com:8020/jwt"

  5. 可选: 配置用户注册表。 缺省情况下,会使用经过验证的 JWT 声明直接创建调用者的已认证主体集,而无需将 JWT 映射到用户,因此不需要用户注册表。

    但是,如果 openidConnectClient 元素的 mapIdentityToRegistryUser 属性设置为 true,那么必须从授权服务器返回相应身份的用户条目,认证和授权才能成功。有关配置用户注册表的更多信息,请参阅在 Liberty 中配置用户注册表

  6. 可选: 认证过滤器中所述配置认证过滤器。

    如果配置认证过滤器,请针对 openidConnectClient 元素的 authFilterRef 属性引用认证过滤器。

    如果未对 openidConnectClient 元素配置 authFilterRef 属性,那么系统将通过此 openidConnectClient 元素对任何未经认证的请求尝试进行认证。

  7. 可选: 通过配置多个 openidConnectClient 元素和多个认证过滤器,将 Liberty 资源服务器配置为与多个 JWT 颁发者或认证代理服务器配合使用。

    每个 openidConnectClient 元素定义与一个 JWT 颁发者或认证代理的一种信任关系,并引用一个认证过滤器。

  8. 可选: 定义用于将 JWT 声明映射到认证主体集的规则。
    Liberty 资源服务器使用 JWT 声明创建认证主体集,可以在以下 openidConnectClient 元素属性上定义如何将 JWT 声明映射到主体集:
    • userIdentifier
    • userUniqueIdentifier
    • groupIdentifier
    • realmName
    • realmIdentifier
    如果同时配置了 realmNamerealmIdentifier,那么会优先使用 realmName,而会忽略 realmIdentifier
    如果未定义声明到主体集的映射,那么以下缺省映射规则适用:
    • 主体集 (sub) 声明用作主体名称和用户的唯一安全名称。
    • 颁发者 (iss) 声明是缺省域,用作主体集域。如果 JWT 令牌中包含了 realmName 声明,那么 realmName 声明用作主体集域而不是 iss 声明。
  9. 可选: 配置单点登录 cookie。 Liberty 服务器预期每个请求会提供有效 JWT 令牌,且不会创建或使用单点登录 cookie 进行认证。要创建单点登录 cookie,请针对 openidConnectClient 元素设置 authnSessionDisabled="false"
  10. 可选: 将 Liberty 服务器配置为接收 JWT 令牌。Web 客户机可使用以下其中一种方法,在资源请求中将 JWT 令牌发送到 Liberty 资源服务器。如果在 Authorization 字段或附带表单编码的主体参数中发送 JWT 令牌,那么不需要执行其他服务器配置。
    要点: 客户机在每个请求中不得使用多种方法来传输令牌。如果配置了 headerName 属性,那么会忽略在 Authorization 头字段或附带表单编码的主体参数中发送令牌。如果未配置 headerName 属性,那么会首先搜索 Authorization 头,然后搜索 access_token 参数。
    • Authorization 请求头字段中发送令牌。
      GET /resource HTTP/1.1
      Host: server.example.com
      Authorization: Bearer mF_9.B5f-4.1JqM
    • 在请求 entity-body 中将令牌作为附带表单的主体参数发送。
      POST /resource HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
      access_token=mF_9.B5f-4.1JqM
    • 通过在 Liberty 中配置受信任头名称,在定制请求头字段中上发送令牌。

      要配置受信任头名称,请针对 openidConnectClient 元素设置 headerName="<myJwtHeaderName>"。例如,如果设置 headerName="jwt",那么可在 jwt 头字段上发送令牌,如以下示例中所示:
      GET /resource HTTP/1.1
      Host: server.example.com
      jwt: mF_9.B5f-4.1JqM
  11. 配置 JWT 受众。 要定义受信任受众的列表,请针对 openidConnectClient 元素配置 audiences 属性。
    有效 JWT 令牌必须满足以下其中一个条件:
    • 如果配置了 audiences 属性,那么受众 (aud) 声明值必须为其中一个配置的受众。要忽略受众检查,请将 audiences 设置为 ALL_AUDIENCES
    • 如果未配置 audiences 属性,但 JWT 令牌包含的 aud 声明是有效 URL,那么资源服务 URL 必须具有 aud 值作为前缀。
      例如,由于资源 URL 开头为 aud 声明值,因此以下受众有效:
      • 受众声明:"aud":"https://<server>:<port>/something"
      • 资源 URL:https://<server>:<port>/something/specific
      由于资源 URL 开头不是 aud 声明值,因此以下受众无效。
      • 受众声明:"aud":"https://<server>:<port>/something/specific"
      • 资源 URL:https://<server>:<port>/something
  12. 可选: 通过实现 com.ibm.wsspi.security.oauth.UserCredentialResolver 服务编程接口 (SPI) 以编程方式将 JWT 令牌映射到主体集。

    有关此接口的信息,请参阅 编程接口(API 和 SPI) 中的 com.ibm.wsspi.security.oauth.UserCredentialResolver SPI 信息,或参阅随产品提供的 ${wlp.install.dir}/dev/spi/ibm/ 目录中 Java 文档中的 SPI 信息。

结果

您已创建将 Liberty 服务器配置为接受 JWT 令牌作为认证令牌所需的最低配置。

用于指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: Tuesday, 6 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_sec_config_oidc_jwt
文件名:twlp_sec_config_oidc_jwt.html