关于此任务
要将 Liberty 服务器配置为接受 JWT 令牌作为认证令牌,请启用 openidConnectClient-1.0 功能部件,设置 inboundPropagation="required",并配置信任库和 SSL。可以选择指定其他 JWT 配置(例如,用户注册表、认证过滤器和声明到主体集的映射)。将 JWT 用作认证令牌的配置与在 Liberty 中配置 OpenID Connect 客户机类似。
任何具有 JWT 令牌的受信任方都可以使用该令牌来访问
Liberty 中的相关联资源。
Liberty 资源服务器验证 JWT 令牌并从 JWT 令牌创建认证主体集。要接受 JWT 令牌作为认证令牌,其中必须包含
iss、
sub 和
exp 声明,且必须使用 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”
]
}
- 将 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>
- 配置 openidConnectClient 元素并设置 inboundPropagation="required"。有关其他 openidConnectClient 属性的信息,请参阅 OpenID Connect 客户机。
以下样本配置假定 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>
- 配置信任库以包含 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 进行签名,请针对 sharedKey 或 clientSecret 属性定义共享密钥。
有关信任库或密钥库的信息,请参阅在 Liberty 中启用 SSL 通信。
- 配置 openidConnectClient 元素的 issuerIdentifier 属性以匹配 JWT 签发者 iss 声明。
例如,如果 JWT 令牌包含 "iss":"https://idp.acme.com:8020/jwt",请设置 issuerIdentifier="https://idp.acme.com:8020/jwt"。
- 可选: 配置用户注册表。 缺省情况下,会使用经过验证的 JWT 声明直接创建调用者的已认证主体集,而无需将 JWT 映射到用户,因此不需要用户注册表。
但是,如果
openidConnectClient 元素的 mapIdentityToRegistryUser
属性设置为 true,那么必须从授权服务器返回相应身份的用户条目,认证和授权才能成功。有关配置用户注册表的更多信息,请参阅在 Liberty 中配置用户注册表。
- 可选: 如认证过滤器中所述配置认证过滤器。
如果配置认证过滤器,请针对 openidConnectClient 元素的 authFilterRef 属性引用认证过滤器。
如果未对 openidConnectClient 元素配置 authFilterRef 属性,那么系统将通过此 openidConnectClient 元素对任何未经认证的请求尝试进行认证。
- 可选: 通过配置多个 openidConnectClient 元素和多个认证过滤器,将 Liberty 资源服务器配置为与多个 JWT 签发者或认证代理服务器配合使用。
每个 openidConnectClient 元素定义与一个 JWT 签发者或认证代理的一种信任关系,并引用一个认证过滤器。
- 可选: 定义用于将 JWT 声明映射到认证主体集的规则。
Liberty 资源服务器使用 JWT 声明创建认证主体集,可以在以下
openidConnectClient 元素属性上定义如何将 JWT 声明映射到主体集:
- userIdentifier
- userUniqueIdentifier
- groupIdentifier
- realmName
- realmIdentifier
如果同时配置了
realmName 和
realmIdentifier,那么会优先使用
realmName,而会忽略
realmIdentifier。
如果未定义声明到主体集的映射,那么以下缺省映射规则适用:
- 主体集 (sub) 声明用作主体名称和用户的唯一安全名称。
- 签发者 (iss) 声明是缺省域,用作主体集域。如果 JWT 令牌中包含了 realmName 声明,那么 realmName 声明用作主体集域而不是 iss 声明。
- 可选: 配置单点登录 cookie。 Liberty 服务器预期每个请求会提供有效 JWT 令牌,且不会创建或使用单点登录 cookie 进行认证。要创建单点登录 cookie,请针对 openidConnectClient 元素设置 authnSessionDisabled="false"。
- 可选: 将 Liberty 服务器配置为接收 JWT 令牌。Web 客户机可使用以下其中一种方法,在资源请求中将 JWT 令牌发送到 Liberty 资源服务器。如果在 Authorization 字段或附带表单编码的主体参数中发送 JWT 令牌,那么不需要执行其他服务器配置。
要点: 客户机在每个请求中不得使用多种方法来传输令牌。如果配置了 headerName 属性,那么会忽略在 Authorization 头字段或附带表单编码的主体参数中发送令牌。如果未配置 headerName 属性,那么会首先搜索 Authorization 头,然后搜索 access_token 参数。
- 配置 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
- 可选: 通过实现 com.ibm.wsspi.security.oauth.UserCredentialResolver 服务编程接口 (SPI) 以编程方式将 JWT 令牌映射到主体集。
有关此接口的信息,请参阅 编程接口 中的 com.ibm.wsspi.security.oauth.UserCredentialResolver SPI 信息,或参阅随产品提供的 ${wlp.install.dir}/dev/spi/ibm/ 目录中 Java 文档中的 SPI 信息。