如何使用 JAX-RS 和泽西岛实现基于 REST 令牌的身份验证

基于令牌的身份验证的工作原理

在基于令牌的身份验证中，客户端将硬凭据（如用户名和密码）交换为一段称为令牌的数据。对于每个请求，客户端将向服务器发送令牌以执行身份验证，然后进行授权，而不是发送硬凭据。

简而言之，基于令牌的身份验证方案遵循以下步骤：

1. 客户端将其凭据（用户名和密码）发送到服务器。
2. 服务器对凭据进行身份验证，如果凭据有效，则为用户生成令牌。
3. 服务器将以前生成的令牌与用户标识符和到期日期一起存储在某个存储中。
4. 服务器将生成的令牌发送到客户端。
5. 客户端在每个请求中将令牌发送到服务器。
6. 在每个请求中，服务器从传入请求中提取令牌。使用令牌，服务器查找用户详细信息以执行身份验证。
   • 如果令牌有效，则服务器接受请求。
   • 如果令牌无效，服务器将拒绝该请求。
7. 执行身份验证后，服务器将执行授权。
8. 服务器可以提供终结点来刷新令牌。

您可以使用 JAX-RS 2.0（Jersey、RESTEasy 和 Apache CXF）做什么

此解决方案仅使用 JAX-RS 2.0 API，避免了任何特定于供应商的解决方案。因此，它应该与JAX-RS 2.0实现一起使用，例如Jersey，RESTEasy和Apache CXF。

值得一提的是，如果您使用的是基于令牌的认证，那么您就不依赖于 servlet 容器提供的标准 Java EE Web 应用程序安全机制，这些机制可通过应用程序的描述符进行配置。这是一个自定义身份验证。web.xml

使用用户名和密码对用户进行身份验证并颁发令牌

创建一个 JAX-RS 资源方法，用于接收和验证凭证（用户名和密码）并为用户颁发令牌：

@Path("/authentication")
public class AuthenticationEndpoint {

    @POST
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public Response authenticateUser(@FormParam("username") String username, 
                                     @FormParam("password") String password) {

        try {

            // Authenticate the user using the credentials provided
            authenticate(username, password);

            // Issue a token for the user
            String token = issueToken(username);

            // Return the token on the response
            return Response.ok(token).build();

        } catch (Exception e) {
            return Response.status(Response.Status.FORBIDDEN).build();
        }      
    }

    private void authenticate(String username, String password) throws Exception {
        // Authenticate against a database, LDAP, file or whatever
        // Throw an Exception if the credentials are invalid
    }

    private String issueToken(String username) {
        // Issue a token (can be a random String persisted to a database or a JWT token)
        // The issued token must be associated to a user
        // Return the issued token
    }
}

如果在验证凭据时引发任何异常，则将返回状态为“禁止访问”的响应。403

如果成功验证凭据，则将返回状态为 （OK） 的响应，并将颁发的令牌发送到响应负载中的客户端。客户端必须在每个请求中将令牌发送到服务器。200

使用 时，客户端必须在请求负载中按以下格式发送凭据：application/x-www-form-urlencoded

username=admin&password=123456

而不是表单参数，可以将用户名和密码包装到一个类中：

public class Credentials implements Serializable {

    private String username;
    private String password;
    
    // Getters and setters omitted
}

然后将其用作 JSON：

@POST
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public Response authenticateUser(Credentials credentials) {

    String username = credentials.getUsername();
    String password = credentials.getPassword();
    
    // Authenticate the user, issue a token and return a response
}

使用此方法，客户端必须在请求的有效负载中按以下格式发送凭据：

{
  "username": "admin",
  "password": "123456"
}

从请求中提取令牌并对其进行验证

客户端应在请求的标准 HTTP 标头中发送令牌。例如：Authorization

Authorization: Bearer <token-goes-here>

标准 HTTP 标头的名称是不幸的，因为它携带身份验证信息，而不是授权。但是，它是用于将凭据发送到服务器的标准 HTTP 标头。

JAX-RS 提供了@NameBinding，这是一个元注释，用于创建其他注释以将过滤器和拦截器绑定到资源类和方法。按如下方式定义注释：@Secured

@NameBinding
@Retention(RUNTIME)
@Target({TYPE, METHOD})
public @interface Secured { }

上面定义的名称绑定注释将用于修饰实现 ContainerRequestFilter 的筛选器类，允许您在资源方法处理请求之前截获请求。ContainerRequestContext 可用于访问 HTTP 请求标头，然后提取令牌：

@Secured
@Provider
@Priority(Priorities.AUTHENTICATION)
public class AuthenticationFilter implements ContainerRequestFilter {

    private static final String REALM = "example";
    private static final String AUTHENTICATION_SCHEME = "Bearer";

    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {

        // Get the Authorization header from the request
        String authorizationHeader =
                requestContext.getHeaderString(HttpHeaders.AUTHORIZATION);

        // Validate the Authorization header
        if (!isTokenBasedAuthentication(authorizationHeader)) {
            abortWithUnauthorized(requestContext);
            return;
        }

        // Extract the token from the Authorization header
        String token = authorizationHeader
                            .substring(AUTHENTICATION_SCHEME.length()).trim();

        try {

            // Validate the token
            validateToken(token);

        } catch (Exception e) {
            abortWithUnauthorized(requestContext);
        }
    }

    private boolean isTokenBasedAuthentication(String authorizationHeader) {

        // Check if the Authorization header is valid
        // It must not be null and must be prefixed with "Bearer" plus a whitespace
        // The authentication scheme comparison must be case-insensitive
        return authorizationHeader != null && authorizationHeader.toLowerCase()
                    .startsWith(AUTHENTICATION_SCHEME.toLowerCase() + " ");
    }

    private void abortWithUnauthorized(ContainerRequestContext requestContext) {

        // Abort the filter chain with a 401 status code response
        // The WWW-Authenticate header is sent along with the response
        requestContext.abortWith(
                Response.status(Response.Status.UNAUTHORIZED)
                        .header(HttpHeaders.WWW_AUTHENTICATE, 
                                AUTHENTICATION_SCHEME + " realm=\"" + REALM + "\"")
                        .build());
    }

    private void validateToken(String token) throws Exception {
        // Check if the token was issued by the server and if it's not expired
        // Throw an Exception if the token is invalid
    }
}

如果在令牌验证期间发生任何问题，将返回状态为“未授权”的响应。否则，请求将继续执行资源方法。401

保护您的 REST 端点

若要将身份验证筛选器绑定到资源方法或资源类，请使用上面创建的批注对它们进行批注。对于带批注的方法和/或类，将执行筛选器。这意味着，仅当使用有效令牌执行请求时，才会访问此类终结点。@Secured

如果某些方法或类不需要身份验证，则只需不注释它们：

@Path("/example")
public class ExampleResource {

    @GET
    @Path("{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Response myUnsecuredMethod(@PathParam("id") Long id) {
        // This method is not annotated with @Secured
        // The authentication filter won't be executed before invoking this method
        ...
    }

    @DELETE
    @Secured
    @Path("{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Response mySecuredMethod(@PathParam("id") Long id) {
        // This method is annotated with @Secured
        // The authentication filter will be executed before invoking this method
        // The HTTP request must be performed with a valid token
        ...
    }
}

在上面显示的示例中，将仅对该方法执行筛选器，因为它带有 .mySecuredMethod(Long)@Secured

标识当前用户

您很可能需要知道执行请求的用户再次访问您的 REST API。可以使用以下方法来实现它：

覆盖当前请求的安全上下文

在 ContainerRequestFilter.filter（ContainerRequestContext） 方法中，可以为当前请求设置新的 SecurityContext 实例。然后覆盖 SecurityContext.getUserPrincipal（），返回一个 Principal 实例：

final SecurityContext currentSecurityContext = requestContext.getSecurityContext();
requestContext.setSecurityContext(new SecurityContext() {

        @Override
        public Principal getUserPrincipal() {
            return () -> username;
        }

    @Override
    public boolean isUserInRole(String role) {
        return true;
    }

    @Override
    public boolean isSecure() {
        return currentSecurityContext.isSecure();
    }

    @Override
    public String getAuthenticationScheme() {
        return AUTHENTICATION_SCHEME;
    }
});

使用令牌查找用户标识符（用户名），这将是主体的名称。

在任何 JAX-RS 资源类中注入 SecurityContext：

@Context
SecurityContext securityContext;

在 JAX-RS 资源方法中也可以执行相同的操作：

@GET
@Secured
@Path("{id}")
@Produces(MediaType.APPLICATION_JSON)
public Response myMethod(@PathParam("id") Long id, 
                         @Context SecurityContext securityContext) {
    ...
}

然后获取委托人：

Principal principal = securityContext.getUserPrincipal();
String username = principal.getName();

使用 CDI（上下文和依赖关系注入）

如果由于某种原因，您不想覆盖 SecurityContext，则可以使用 CDI（上下文和依赖关系注入），它提供了有用的功能，如事件和生产者。

创建 CDI 限定符：

@Qualifier
@Retention(RUNTIME)
@Target({ METHOD, FIELD, PARAMETER })
public @interface AuthenticatedUser { }

在上面创建的中，注入一个注释有以下内容的事件：AuthenticationFilter@AuthenticatedUser

@Inject
@AuthenticatedUser
Event<String> userAuthenticatedEvent;

如果身份验证成功，请触发将用户名作为参数传递的事件（请记住，令牌是为用户颁发的，令牌将用于查找用户标识符）：

userAuthenticatedEvent.fire(username);

很可能有一个类表示应用程序中的用户。我们称之为类 。User

创建一个 CDI Bean 来处理身份验证事件，找到一个具有相应用户名的实例并将其分配给生产者字段：UserauthenticatedUser

@RequestScoped
public class AuthenticatedUserProducer {

    @Produces
    @RequestScoped
    @AuthenticatedUser
    private User authenticatedUser;
    
    public void handleAuthenticationEvent(@Observes @AuthenticatedUser String username) {
        this.authenticatedUser = findUser(username);
    }

    private User findUser(String username) {
        // Hit the the database or a service to find a user by its username and return it
        // Return the User instance
    }
}

该字段生成一个实例，该实例可以注入到容器管理的 Bean 中，例如 JAX-RS 服务、CDI Bean、servlet 和 EJB。使用以下代码段注入实例（实际上，它是 CDI 代理）：authenticatedUserUserUser

@Inject
@AuthenticatedUser
User authenticatedUser;

请注意，CDI @Produces注释与 JAX-RS @Produces注释不同：

• CDI： javax.enterprise.inject.Produces
• JAX-RS： javax.ws.rs.Produces

确保在 Bean 中使用 CDI @Produces注释。AuthenticatedUserProducer

这里的关键是用@RequestScoped注释的bean，允许您在过滤器和bean之间共享数据。如果您不想使用事件，那么可以修改过滤器以将经过身份验证的用户存储在请求范围的 Bean 中，然后从 JAX-RS 资源类中读取它。

与覆盖 SecurityContext 的方法相比，CDI 方法允许您从 JAX-RS 资源和提供程序以外的 Bean 中获取经过身份验证的用户。

支持基于角色的授权

有关如何支持基于角色的授权的详细信息，请参阅我的其他答案。

发行代币

令牌可以是：

• 不透明：除值本身（如随机字符串）外，不显示任何详细信息
• 自包含：包含有关令牌本身的详细信息（如 JWT）。

请参阅以下详细信息：

作为令牌的随机字符串

可以通过生成随机字符串并将其与用户标识符和到期日期一起保存到数据库中来颁发令牌。如何用Java生成随机字符串的一个很好的例子可以在这里看到。您还可以使用：

Random random = new SecureRandom();
String token = new BigInteger(130, random).toString(32);

JWT （JSON Web Token）

JWT（JSON Web 令牌）是一种标准方法，用于在双方之间安全地表示声明，由 RFC 7519 定义。

它是一个独立的令牌，它使您能够在声明中存储详细信息。这些声明存储在令牌负载中，该负载是编码为 Base64 的 JSON。以下是在RFC 7519中注册的一些声明及其含义（有关更多详细信息，请阅读完整的RFC）：

• iss：颁发令牌的主体。
• sub：作为JWT主题的主体。
• exp：令牌的到期日期。
• nbf：开始接受令牌进行处理的时间。
• iat：发行代币的时间。
• jti：令牌的唯一标识符。

请注意，不得在令牌中存储敏感数据（如密码）。

客户端可以读取有效负载，并且可以通过在服务器上验证令牌的签名来轻松检查令牌的完整性。签名可以防止令牌被篡改。

如果不需要跟踪 JWT 令牌，则无需保留它们。虽然，通过保留令牌，您将有可能使它们的访问权限无效并撤销它们的访问权限。若要跟踪 JWT 令牌，可以保留令牌标识符（jti 声明）以及其他一些详细信息（如为其颁发令牌的用户、到期日期等），而不是将整个令牌保留在服务器上。

在保留令牌时，请始终考虑删除旧令牌，以防止数据库无限增长。

使用智威汤逊

有一些 Java 库可以颁发和验证 JWT 令牌，例如：

• jjwt
• java-jwt
• 何塞4j

要找到一些与JWT合作的其他重要资源，请查看 http://jwt.io。

使用 JWT 处理令牌吊销

如果要吊销令牌，则必须跟踪它们。无需在服务器端存储整个令牌，只需存储令牌标识符（必须是唯一的）和一些元数据（如果需要）。对于令牌标识符，您可以使用 UUID。

jti 声明应用于在令牌上存储令牌标识符。验证令牌时，通过根据服务器端的令牌标识符检查 jti 声明的值，确保令牌未被吊销。

出于安全目的，请在用户更改密码时吊销用户的所有令牌。

附加信息

• 您决定使用哪种类型的身份验证并不重要。始终在HTTPS连接的顶部执行此操作，以防止中间人攻击。
• 查看信息安全中的此问题，了解有关令牌的更多信息。
• 在本文中，您将找到有关基于令牌的身份验证的一些有用信息。

^{这个答案是关于授权的，它是我之前关于身份验证的答案的补充}

^{为什么是另一个答案？我试图通过添加有关如何支持JSR-250注释的详细信息来扩展我之前的答案。然而，最初的答案变得太长，超过了30，000个字符的最大长度。因此，我将整个授权详细信息移到了这个答案上，使另一个答案专注于执行身份验证和颁发令牌。}

通过注释支持基于角色的授权@Secured

除了其他答案中显示的身份验证流之外，REST 终结点中还可以支持基于角色的授权。

创建枚举并根据需要定义角色：

public enum Role {
    ROLE_1,
    ROLE_2,
    ROLE_3
}

更改之前创建的名称绑定注释以支持角色：@Secured

@NameBinding
@Retention(RUNTIME)
@Target({TYPE, METHOD})
public @interface Secured {
    Role[] value() default {};
}

然后注释资源类和方法以执行授权。方法注释将覆盖类注释：@Secured

@Path("/example")
@Secured({Role.ROLE_1})
public class ExampleResource {

    @GET
    @Path("{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Response myMethod(@PathParam("id") Long id) {
        // This method is not annotated with @Secured
        // But it's declared within a class annotated with @Secured({Role.ROLE_1})
        // So it only can be executed by the users who have the ROLE_1 role
        ...
    }

    @DELETE
    @Path("{id}")    
    @Produces(MediaType.APPLICATION_JSON)
    @Secured({Role.ROLE_1, Role.ROLE_2})
    public Response myOtherMethod(@PathParam("id") Long id) {
        // This method is annotated with @Secured({Role.ROLE_1, Role.ROLE_2})
        // The method annotation overrides the class annotation
        // So it only can be executed by the users who have the ROLE_1 or ROLE_2 roles
        ...
    }
}

创建具有授权优先级的筛选器，该筛选器在前面定义的身份验证优先级筛选器之后执行。

ResourceInfo 可用于获取将处理请求的资源方法和资源类，然后从中提取注释：@Secured

@Secured
@Provider
@Priority(Priorities.AUTHORIZATION)
public class AuthorizationFilter implements ContainerRequestFilter {

    @Context
    private ResourceInfo resourceInfo;

    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {

        // Get the resource class which matches with the requested URL
        // Extract the roles declared by it
        Class<?> resourceClass = resourceInfo.getResourceClass();
        List<Role> classRoles = extractRoles(resourceClass);

        // Get the resource method which matches with the requested URL
        // Extract the roles declared by it
        Method resourceMethod = resourceInfo.getResourceMethod();
        List<Role> methodRoles = extractRoles(resourceMethod);

        try {

            // Check if the user is allowed to execute the method
            // The method annotations override the class annotations
            if (methodRoles.isEmpty()) {
                checkPermissions(classRoles);
            } else {
                checkPermissions(methodRoles);
            }

        } catch (Exception e) {
            requestContext.abortWith(
                Response.status(Response.Status.FORBIDDEN).build());
        }
    }

    // Extract the roles from the annotated element
    private List<Role> extractRoles(AnnotatedElement annotatedElement) {
        if (annotatedElement == null) {
            return new ArrayList<Role>();
        } else {
            Secured secured = annotatedElement.getAnnotation(Secured.class);
            if (secured == null) {
                return new ArrayList<Role>();
            } else {
                Role[] allowedRoles = secured.value();
                return Arrays.asList(allowedRoles);
            }
        }
    }

    private void checkPermissions(List<Role> allowedRoles) throws Exception {
        // Check if the user contains one of the allowed roles
        // Throw an Exception if the user has not permission to execute the method
    }
}

如果用户没有执行操作的权限，则请求将中止并带有（禁止访问）。403

要了解执行请求的用户，请参阅我之前的答案。您可以从 SecurityContext（应该已经在 ContainerRequestContext 中设置）中获取它，也可以使用 CDI 注入它，具体取决于您采用的方法。

如果注释未声明任何角色，则可以假定所有经过身份验证的用户都可以访问该终结点，而不考虑用户具有的角色。@Secured

使用 JSR-250 注释支持基于角色的授权

或者，除了如上所示在注释中定义角色之外，还可以考虑 JSR-250 注释，例如 @RolesAllowed、@PermitAll 和 @DenyAll。@Secured

JAX-RS 不支持这种开箱即用的注释，但可以使用过滤器来实现。以下是一些注意事项，如果您想支持所有这些注意事项：

• 方法上的@DenyAll优先于@RolesAllowed，@PermitAll类。
• 对方法@RolesAllowed优先于对类@PermitAll。
• 对方法@PermitAll优先于对类@RolesAllowed。
• @DenyAll不能附加到类。
• 类上的@RolesAllowed优先于类上的@PermitAll。

因此，检查 JSR-250 注释的授权过滤器可能如下所示：

@Provider
@Priority(Priorities.AUTHORIZATION)
public class AuthorizationFilter implements ContainerRequestFilter {

    @Context
    private ResourceInfo resourceInfo;

    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {

        Method method = resourceInfo.getResourceMethod();

        // @DenyAll on the method takes precedence over @RolesAllowed and @PermitAll
        if (method.isAnnotationPresent(DenyAll.class)) {
            refuseRequest();
        }

        // @RolesAllowed on the method takes precedence over @PermitAll
        RolesAllowed rolesAllowed = method.getAnnotation(RolesAllowed.class);
        if (rolesAllowed != null) {
            performAuthorization(rolesAllowed.value(), requestContext);
            return;
        }

        // @PermitAll on the method takes precedence over @RolesAllowed on the class
        if (method.isAnnotationPresent(PermitAll.class)) {
            // Do nothing
            return;
        }

        // @DenyAll can't be attached to classes

        // @RolesAllowed on the class takes precedence over @PermitAll on the class
        rolesAllowed = 
            resourceInfo.getResourceClass().getAnnotation(RolesAllowed.class);
        if (rolesAllowed != null) {
            performAuthorization(rolesAllowed.value(), requestContext);
        }

        // @PermitAll on the class
        if (resourceInfo.getResourceClass().isAnnotationPresent(PermitAll.class)) {
            // Do nothing
            return;
        }

        // Authentication is required for non-annotated methods
        if (!isAuthenticated(requestContext)) {
            refuseRequest();
        }
    }

    /**
     * Perform authorization based on roles.
     *
     * @param rolesAllowed
     * @param requestContext
     */
    private void performAuthorization(String[] rolesAllowed, 
                                      ContainerRequestContext requestContext) {

        if (rolesAllowed.length > 0 && !isAuthenticated(requestContext)) {
            refuseRequest();
        }

        for (final String role : rolesAllowed) {
            if (requestContext.getSecurityContext().isUserInRole(role)) {
                return;
            }
        }

        refuseRequest();
    }

    /**
     * Check if the user is authenticated.
     *
     * @param requestContext
     * @return
     */
    private boolean isAuthenticated(final ContainerRequestContext requestContext) {
        // Return true if the user is authenticated or false otherwise
        // An implementation could be like:
        // return requestContext.getSecurityContext().getUserPrincipal() != null;
    }

    /**
     * Refuse the request.
     */
    private void refuseRequest() {
        throw new AccessDeniedException(
            "You don't have permissions to perform this action.");
    }
}

^{注意：上述实现基于 Jersey RolesAllowedDynamicFeature。如果您使用 Jersey，则无需编写自己的筛选器，只需使用现有实现即可。}