[17.0.0.3 and later]

配置 MicroProfile JSON Web 令牌

可以将 Liberty 服务器配置为接受 MicroProfile JSON Web 令牌作为认证令牌。

开始之前

安装 Java™ Platform, Standard Edition (Java SE) 8 或更高版本以使用 mpJwt-1.0 功能部件。

关于此任务

MicroProfile 1.2 定义了一个可互操作的 JSON Web 令牌 (MP-JWT) 标准,该标准包含以下三个部分:
  • 令牌格式和声明
  • org.eclipse.microprofile.jwt.JsonWebToken 接口,这是 java.security.Principal 接口的扩展,使此组声明能通过 Get 样式访问程序使用
  • 将 JSON Web 令牌和声明映射到各种 Java EE 容器应用程序编程接口 (API)

请在 JWT RBAC for MicroProfile 中查找 MP-JWT 规范和 API。

任何拥有 MP-JWT 令牌的可信方都可以通过在授权标头中发送该令牌,从而使用该令牌来访问 Liberty 中的关联资源。令牌有线格式必须遵循 RFC 6750 规范“OAuth 2.0 授权框架:不记名令牌用法”,如以下示例所示:

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT token>
Liberty 资源服务器将验证 MP-JWT 令牌、创建已认证的 JSON Web 令牌,并通过 CDI 注入或 JAX-RS 安全上下文使 JSON Web 令牌和令牌声明可用。要作为 MP-JWT 令牌接受,JWT 令牌必须包含声明列表。以下示例显示一个 MP-JWT 令牌:
{
    "typ": "JWT",
    "alg": "RS256",
    "kid": "abc-1234567890"
}
{
       "iss": "https://server.example.com",
       "aud": "s6BhdRkqt3",
       "jti": "a-123",
       "exp": 1311281970,
       "iat": 1311280970,
       "sub": "24400320",
       "upn": "jdoe@server.example.com",
       "groups": ["red-group", "green-group", "admin-group", "admin"],
}

过程

  1. mpJwt-1.0 功能部件和任何其他必需功能部件添加至 server.xml 文件。 mpJwt-1.0 功能部件至少需要 AppSecurity-2.0jaxrs-2.0 功能部件,并且经常与上下文和依赖性注入 (CDI) 功能部件配合使用。
    <featureManager>
        <feature>mpJwt-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>jaxrs-2.0</feature>
        <feature>cdi-1.2</feature>
        ...
    </featureManager>
  2. 配置 mpJwt 元素。
    1. 添加 issuer 属性。请为此属性输入一个与 Java Web 令牌 (JWT) 中的 iss 声明相匹配的值。
    2. 如果 JWT 包含 aud 声明,请添加 audiences 属性。为此属性输入一个值,该值包含 JWT 中的 aud 声明的任一值。
    3. 添加 jwksUri 属性。请为此属性输入一个与 JSON Web 密钥 (JWK) 的 URL 相匹配的值。 以下代码显示一个具有 JWK 的典型 mpJwt 配置元素:
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"
           issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. 如果您在安全套接字层 (SSL) 配置中的信任库文件内添加了 JWT 签名验证密钥,请添加 keyName 属性。 keyName 属性用于指定信任库文件中的密钥别名。 以下代码显示样本 mpJwt 配置:
      <mpJwt 
           keyName="mpJwtValidationKey"
           issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. 配置信任库文件以包含 JWK 端点证书,以便 Liberty 服务器可建立到 JWK 端点的 SSL 连接。
    1. 通过 server.xml 文件中的 keystore 元素配置信任库
    2. 配置 SSL 以引用此信任库文件。
    3. 将 SSL 配置设置为服务器缺省 SSL 配置,或通过 mpJwt 元素的 sslRef 属性指定信任库标识。
    4. 如果 JWT 签发者不支持 JWK,并且 JWT 使用 X.509 证书进行签名,请将签发者的 X.509 证书导入到 SSL 配置中的信任库文件内。 有关更多信息,请参阅在 Liberty 中启用 SSL 通信
  4. 可选: 定义相关规则,以用于将 JWT 声明映射到未采用 MP-JWT 格式的 JWT 的认证主体集。 缺省情况下,程序使用 upn 声明作为用户的主体名称和唯一安全性名称,并且程序使用 groups 声明作为安全角色映射的组名。要更改缺省映射,请使用 userNameAttribute 属性选择用户主体的声明,并使用 groupAttribute 属性选择组名的声明。
  5. 可选: 使用 JAX-RS 应用程序并通过调用 javax.ws.rs.core.SecurityContext.getUserPrincipal() API 来访问 JsonWebToken getter 方法。 在以下示例中,用户主体被强制转换为 org.eclipse.microprofile.jwt.JsonWebToken API 的实例,并且应用程序可通过 JsonWebToken getter 方法访问所有声明:
    @GET
    @Path("/getGroups")
    public Set<String> getGroups(@Context SecurityContext sec) {
           Set<String> groups = null;
           Principal user = sec.getUserPrincipal();
           if (user instanceof JsonWebToken) {
                    JsonWebToken jwt = (JsonWebToken) user;
                    groups= = jwt.getGroups();
           }
           return groups;
    }
  6. 可选: 使用 JAX-RS 应用程序来通过 Raw TypeClaimValuejavax.inject.ProviderJSON-P 类型注入 org.eclipse.microprofile.jwt.JsonWebToken API,如以下示例所示:
    @RequestScoped
    public class JwtEndpoint {
           @Inject
           private JsonWebToken jwtPrincipal;
           @GET
           @Path("/getInjectedPrincipal")
           public String getInjectedJWT() {
              return  this.jwtPrincipal.getName();
           }
    }
  7. 可选: 如果程序执行程序化安全性,并且您接收到来自主体集的 org.eclipse.microprofile.jwt.JsonWebToken API,请使用 com.ibm.websphere.security.auth.WSSubject.getCallerPrincipal() API。 在当前安全上下文中,主体集包含两个 java.security.Principal 主体。其中一个主体是 JSON Web 令牌。
  8. 可选: [17.0.0.4 and later]使用注释和 JWT 的组声明来保护 JAX-RS 资源。请将 @RolesAllowed 注释中使用的安全角色名映射至 JWT 的 groups 声明中的组名。 如果角色名和组名相同,您可以在 application-bnd 元素中省略角色映射。但是,如果 JWT 是包含组信息的 MP-JWT,请在 application-bnd 元素中进行映射,以声明角色与组的关联。有关更多信息,请参阅使用注释保护 JAX-RS 资源访问标识和授权未提供角色映射绑定时的应用程序授权
  9. 可选: [17.0.0.4 and later]配置 Liberty,以根据已配置的 Liberty 用户注册表检查来自 JWT 的用户主体名称。

    缺省情况下,程序会直接根据已验证的 JWT 创建安全主体集,而不需要用户注册表。要更改此行为,请在 server.xml 文件中添加 mapToUserRegistry="true" 配置属性。程序会根据已配置的用户注册表来搜索主体名称,并根据用户注册表中的用户属性创建安全主体集。

  10. 可选: [17.0.0.4 and later]配置 Liberty,以将 mpJwt-1.0 功能部件仅应用于登录方法名称为 MP-JWT 的应用程序。
    缺省情况下,如果配置 mpJwt-1.0 功能部件,那么所有已授权的请求都必须在 HTTP 标头中包括有效的 JWT。要修改缺省行为,以便仅在某些应用程序中需要 JWT 认证令牌,请在 server.xml 文件中向 <mpJwt> 元素添加 ignoreApplicationAuthMethod="false" 配置属性。然后,使用以下两种方法中的一种来配置该应用程序:
    • 该应用程序具有 @LoginConfig 注释,其中声明 MP-JWT 登录方法作为认证方法。

      例如,@LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT")

    • 该应用程序的 web.xml 文件在 login-config 元素中具有 MP-JWT 认证方法的声明。

      例如,<login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config>

  11. 可选: [17.0.0.4 and later]配置 Liberty,以便在 Liberty 调用其他 JAX-RS 服务时,自动传播 MP-JWT 作为认证令牌。

    如果 Liberty 还充当 JAX-RS 2.0 客户机,请在 <webTarget> 配置元素中添加 authnToken="mpjwt" 语句。这样,Liberty JAX-RS 客户机就会在 JAX-RS 服务调用中自动添加 JWT 作为授权标头。例如,如果在 server.xml 文件中添加 <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> 元素,那么调用 http://localhost:56789/protectedResourceWithMPJWT/ 服务时,就会向授权标头添加 JWT 令牌。


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

文件名:twlp_sec_json.html