Spring-security-OAuth 2开发指南

た入场券 2021-09-20 07:32 327阅读 0赞

**官方原文：[http://projects.spring.io/spring-security-oauth/docs/oauth2.html][http_projects.spring.io_spring-security-oauth_docs_oauth2.html]**

**本文记录官方文档的重点内容，先记录下来以供学习，****里面涉及到一些概念性的东西还需研究具体含义。**

该指南共分为两部分：

OAuth 2.0 provider----------样例代码[integration tests][]

OAuth 2.0 client-------------样例代码[sample apps][]

## 一、OAuth 2.0 Provider ##

provider向用户提供接口用于确认是否具有受保护资源的访问权限

client用来独立访问或者代表用户访问受保护的资源

## OAuth 2.0 Provider 实现 ##

Spring OAuth2.0提供者分为：

*  授权服务 Authorization Service.
 *  资源服务 Resource Service.

**with Spring Security OAuth you have the option to split them across two applications, and also to have multiple Resource Services that share an Authorization Service. The requests for the tokens are handled by Spring MVC controller endpoints, and access to protected resources is handled by standard Spring Security request filters. The following endpoints are required in the Spring Security filter chain in order to implement OAuth 2.0 Authorization Server:**

它们有时会同时存在于一个应用程序中，但在Spring Security OAuth里你可以分开部署，甚至可以拥有多个资源服务共享一个授权服务。所有获取令牌的请求都将会在Spring MVC controller endpoints中进行处理，并且访问受保护

的资源服务的处理流程将会放在标准的Spring Security请求过滤器中(filters)。

下面是配置一个授权服务要实现的endpoints：

*  AuthorizationEndpoint：用来作为请求者获得授权的服务，默认的URL是/oauth/authorize.
 *  TokenEndpoint：用来作为请求者获得令牌（Token）的服务，默认的URL是/oauth/token.

下面是配置一个资源服务要实现的过滤器：

*  OAuth2AuthenticationProcessingFilter：用来作为认证令牌（Token）的一个处理流程过滤器。只有当过滤器通过之后，请求者才能获得受保护的资源。

## 1.Authorization Server Configuration授权服务配置 ##

要配置授权服务，首先要考虑grant type授权类型（authorization code, user credentials, refresh token），不同的授权类型为客户端（Client）提供了不同的获取令牌（Token）方式

The `@EnableAuthorizationServer` annotation is used to configure the OAuth 2.0 Authorization Server mechanism, together with any `@Beans` that implement `AuthorizationServerConfigurer` (there is a handy adapter implementation with empty methods). The following features are delegated to separate configurers that are created by Spring and passed into the `AuthorizationServerConfigurer`:

*  `ClientDetailsServiceConfigurer`: a configurer that defines the client details service. Client details can be initialized, or you can just refer to an existing store.
 *  `AuthorizationServerSecurityConfigurer`: defines the security constraints on the token endpoint.
 *  `AuthorizationServerEndpointsConfigurer`: defines the authorization and token endpoints and the token services.

可以使用@EnableAuthorizationServer注解来配置OAuth2.0的认证服务机制。同时使用实现了AuthorizationServerConfigurer的@Beans注解的类。几个配置是由Spring创建的独立的配置对象，它们会被Spring传入AuthorizationServerConfigurer中：

*  `ClientDetailsServiceConfigurer`: 用来配置客户端详情服务（ClientDetailsService），客户端详情信息在这里进行初始化，你能够把客户端详情信息通过指定的数据库来存储。
 *  `AuthorizationServerSecurityConfigurer`: 用来配置令牌端点(Token Endpoint)的安全约束.
 *  `AuthorizationServerEndpointsConfigurer`: 用来配置授权（authorization）以及令牌（token）的访问端点和令牌服务(token services)。

### Configuring Client Details配置客户端详情 ###

The `ClientDetailsServiceConfigurer` (a callback from your `AuthorizationServerConfigurer`) can be used to define an in-memory or JDBC implementation of the client details service. Important attributes of a client are

*  `clientId`: (required) the client id.
 *  `secret`: (required for trusted clients) the client secret, if any.
 *  `scope`: The scope to which the client is limited. If scope is undefined or empty (the default) the client is not limited by scope.
 *  `authorizedGrantTypes`: Grant types that are authorized for the client to use. Default value is empty.
 *  `authorities`: Authorities that are granted to the client (regular Spring Security authorities).

Client details can be updated in a running application by access the underlying store directly (e.g. database tables in the case of `JdbcClientDetailsService`) or through the `ClientDetailsManager` interface (which both implementations of `ClientDetailsService` also implement).

ClientDetailsServiceConfigurer 能够使用内存或者JDBC来实现客户端详情服务（ClientDetailsService），一个客户端的重要的属性有：

*  clientId：（必须的）用来标识客户的Id。
 *  secret：（需要值得信任的客户端）客户端安全码，如果有的话。
 *  scope：用来限制客户端的访问范围，如果为空（默认）的话，那么客户端拥有全部的访问范围。
 *  authorizedGrantTypes：此客户端可以使用的授权类型，默认为空。
 *  authorities：客户端被授权的权限

### Managing Tokens管理令牌 ###

[`AuthorizationServerTokenServices`][AuthorizationServerTokenServices] 接口定义了一些管理OAuth 2.0 tokens的操作

*  When an  is created, the authentication must be stored so that resources accepting the access token can reference it later.访问令牌（access token）被创建后一定要保存下来，这样当一个客户端使用这个令牌对资源服务进行请求的时候才能够引用这个令牌
 *  The access token is used to load the authentication that was used to authorize its creation.

当你创建自己的 `AuthorizationServerTokenServices` 实现时, 可以考虑一下使用[`DefaultTokenServices`][DefaultTokenServices] ，它有很多种策略可以改变access token的存储方式. 使用它创建令牌时，默认的是一个随机值，除了令牌的持久化是由`TokenStore` 实现的，其他的都是由`DefaultTokenServices `实现的。 token默认时存储在内存的，下面也有其他几种方式：

*   `InMemoryTokenStore` 默认的实现方式
 *  The `JdbcTokenStore` 存储在关系型数据库中. 使用它时需要将 "spring-jdbc" 依赖放进你的classpath中
 *  The [JSON Web Token (JWT) version][JSON Web Token _JWT_ version] of the store encodes all the data about the grant into the token itself (so no back end store at all which is a significant advantage). One disadvantage is that you can't easily revoke an access token, so they normally are granted with short expiry and the revocation is handled at the refresh token. Another disadvantage is that the tokens can get quite large if you are storing a lot of user credential information in them. The `JwtTokenStore` is not really a "store" in the sense that it doesn't persist any data, but it plays the same role of translating betweeen token values and authentication information in the `DefaultTokenServices`.

> NOTE: the schema for the JDBC service is not packaged with the library (because there are too many variations you might like to use in practice), but there is an example you can start from in the [test code in github][]. Be sure to `@EnableTransactionManagement` to prevent clashes between client apps competing for the same rows when tokens are created. Note also that the sample schema has explicit `PRIMARY KEY` declarations - these are also necessary in a concurrent environment.

### JWT Tokens ###

较少使用，暂时不写

### Grant Types授权类型 ###

授权是使用 AuthorizationEndpoint 这个端点来进行控制的，通过 AuthorizationServerEndpointsConfigurer 来进行配置，默认情况下，除了password授权类型以外，支持所有授权类型，下面这些配置会影响到授权类型：

*  `authenticationManager`: 认证管理器，当你选择了资源所有者密码（password）授权类型的时候，请设置这个属性注入一个 AuthenticationManager 对象。
 *  `userDetailsService`: 如果你注入了一个 `UserDetailsService` 类（即你有了自己的UserDetailsService接口的实现）或者使用`GlobalAuthenticationManagerConfigurer`t作了全局配置，那么刷新令牌的授权就会检查用户的详细信息user detail,以确保账户的有效性、
 *  `authorizationCodeServices`:这个属性是用来设置授权码服务的，主要用于 "authorization\_code" 授权码类型模式。
 *  `implicitGrantService`: 用来管理隐式授权模式.
 *  `tokenGranter`: the `TokenGranter` 会掌控全部的授权控制，而忽略掉上面的属性配置

### Configuring the Endpoint URLs配置授权端点的url ###

`AuthorizationServerEndpointsConfigurer` 有一个 `pathMapping()` 方法.它有两个参数:

*  The default (framework implementation) URL path for the endpoint 默认url
 *  The custom path required (starting with a "/") 自定义的url，需要以"/"开头

框架提供的url有：

`/oauth/authorize` (the authorization endpoint),

`/oauth/token` (the token endpoint),

`/oauth/confirm_access` (user posts approval for grants here),用户确认授权提交端点

`/oauth/error` (used to render errors in the authorization server), 授权服务错误信息端点

`/oauth/check_token` (used by Resource Servers to decode access tokens)资源服务访问令牌解析端点

`/oauth/token_key` (exposes public key for token verification if using JWT tokens).使用JWT令牌时，提供令牌认证的公有密钥的端点

N.B. the Authorization endpoint `/oauth/authorize` (或者它的映射端点)应该被Spring Security保护起来只供授权用户访问. 例如，使用标准的Spring Security `WebSecurityConfigurer`:

@Override
        protected void configure(HttpSecurity http) throws Exception {
            http
                .authorizeRequests().antMatchers("/login").permitAll().and()
            // default protection for all resources (including /oauth/authorize)
                .authorizeRequests()
                    .anyRequest().hasRole("USER")
            // ... more configuration, e.g. for form login
        }

> Note: 如果你的服务既是Authorization Server 又是 Resource Server ，那么是一个低优先级的过滤器链来控制API资源的. 这些接口被access tokens所保护， you need their paths *not* to be matched by the ones in the main user-facing filter chain, so be sure to include a request matcher that picks out only non-API resources in the `WebSecurityConfigurer` above.
> 
> （所以请挑选一个URL链接来确保你的资源接口中有一个不需要被保护的链接用来取得授权，就如上面示例中的 /login 链接，你需要在 WebSecurityConfigurer 配置对象中进行设置。）

The token endpoint is protected for you by default by Spring OAuth in the `@Configuration` support using HTTP Basic authentication of the client secret. This is not the case in XML (so it should be protected explicitly).

In XML the `<authorization-server/>` element has some attributes that can be used to change the default endpoint URLs in a similar way. The `/check_token` endpoint has to be explicitly enabled (with the `check-token-enabled` attribute).

## Customizing the UI ##

### 。。。    ###

### Enforcing SSL ###

使用普通的http请求来测试是可以的，但是在生产环境中Authorization Server 必须使用SSL. 你可以在一个安全的容器中运行app或者使用代理，你也可以使用Spring Security的requiresChannel()约束来保证端点的安全性. 对于 `/authorize` 端点来说，你可以自由决定使用哪种方法来让/authorize端口作为你正常应用安全的一部分，即要保证这个端口是安全的. 对于 `/token` 端点来说， 在 `AuthorizationServerEndpointsConfigurer` 中有一个标记，可以使用 `sslOnly()` 方法来设置. In both cases the secure channel setting is optional but will cause Spring Security to redirect to what it thinks is a secure channel if it detects a request on an insecure channel.

## Customizing the Error Handling ##

Error handling in an Authorization Server uses standard Spring MVC features, namely `@ExceptionHandler` methods in the endpoints themselves. Users can also provide a `WebResponseExceptionTranslator` to the endpoints themselves which is the best way to change the content of the responses as opposed to the way they are rendered. The rendering of exceptions delegates to `HttpMesssageConverters` (which can be added to the MVC configuration) in the case of token endpoint and to the OAuth error view (`/oauth/error`) in the case of teh authorization endpoint. The whitelabel error endpoint is provided for HTML responses, but users probably need to provide a custom implementation (e.g. just add a `@Controller`with `@RequestMapping("/oauth/error")`).端点实际上就是一个特殊的Controller，它用于返回一些对象数据。

## 2.Resource Server Configuration资源服务配置 ##

资源服务器为受OAuth2令牌保护的资源提供服务. 由Spring OAuth提供的一个Spring Security认证过滤器来实现. 在一个 `@Configuration` 类上加上 `@EnableResourceServer` 注解, 必要的时候是 `ResourceServerConfigurer`.来作进一步的配置。可配置内容如下:

*  `tokenServices`: `ResourceServerTokenServices`)实例，用来实现token服务
 *  `resourceId`: 资源id (optional, but recommended and will be validated by the auth server if present).
 *  其他的扩展属性(例如 `tokenExtractor` 令牌提取器，从进来的请求中提取令牌
 *  request matchers for protected resources (defaults to all)请求匹配器，用来设置需要进行保护的资源路径，默认的情况下是受保护资源服务的全部路径
 *  access rules for protected resources (defaults to plain "authenticated")受保护资源的访问规则，默认的规则是普通的身份验证
 *  other customizations for the protected resources permitted by the `HttpSecurity` configurer in Spring Security其他的自定义权限保护规则通过 HttpSecurity 来进行配置

加了 `@EnableResourceServer` 注解会自动 向Spring Security 的过滤器链添加一个类型为 `OAuth2AuthenticationProcessingFilter` 的过滤器

In XML there is a `<resource-server/>` element with an `id` attribute - this is the bean id for a servlet `Filter` that can then be added manually to the standard Spring Security chain.

Your `ResourceServerTokenServices` 是组成Authorization Server的另一半. If the Resource Server and Authorization Server are in the same application and you use `DefaultTokenServices` then you don't have to think too hard about this because it implements all the necessary interfaces so it is automatically consistent. If your Resource Server is a separate application then you have to make sure you match the capabilities of the Authorization Server and provide a `ResourceServerTokenServices` that knows how to decode the tokens correctly. As with the Authorization Server, you can often use the `DefaultTokenServices` and the choices are mostly expressed through the `TokenStore` (backend storage or local encoding). An alternative is the `RemoteTokenServices` which is a Spring OAuth features (not part of the spec) allowing Resource Servers to decode tokens through an HTTP resource on the Authorization Server (`/oauth/check_token`). `RemoteTokenServices` are convenient if there is not a huge volume of traffic in the Resource Servers (every request has to be verified with the Authorization Server), or if you can afford to cache the results. To use the `/oauth/check_token` endpoint you need to expose it by changing its access rule (default is "denyAll()") in the `AuthorizationServerSecurityConfigurer`, e.g.

@Override
    		public void configure(AuthorizationServerSecurityConfigurer oauthServer) throws Exception {
    			oauthServer.tokenKeyAccess("isAnonymous() || hasAuthority('ROLE_TRUSTED_CLIENT')").checkTokenAccess(
    					"hasAuthority('ROLE_TRUSTED_CLIENT')");
    		}

In this example we are configuring both the `/oauth/check_token` endpoint and the `/oauth/token_key` endpoint (so trusted resources can obtain the public key for JWT verification). These two endpoints are protected by HTTP Basic authentication using client credentials.

### Configuring An OAuth-Aware Expression Handler ###

You may want to take advantage of Spring Security's [expression-based access control][]. An expression handler will be registered by default in the `@EnableResourceServer` setup. The expressions include *\#oauth2.clientHasRole*, *\#oauth2.clientHasAnyRole*, and *\#oath2.denyClient* which can be used to provide access based on the role of the oauth client (see `OAuth2SecurityExpressionMethods` for a comprehensive list). In XML you can register a oauth-aware expression handler with the `expression-handler` element of the regular `<http/>` security configuration.

## 二、OAuth 2.0 Client ##

The OAuth 2.0 client 机制是 负责 访问受OAuth 2.0保护的其他服务的资源. 配置包含建立用户可以访问的相关受保护资源、存储用户的认证码和访问令牌

### Protected Resource Configuration受保护的资源配置 ###

Protected resources (or "remote resources") 由 [`OAuth2ProtectedResourceDetails`][OAuth2ProtectedResourceDetails].的实现类来实现。 一个受保护的资源由如下属性:

*  `id`: 资源id. 客户端用它来查找资源; 
 *  `clientId`: OAuth客户端ID. OAuth provider用它来识别你的客户端
 *  `clientSecret`: 与资源有关的密钥，默认为空.
 *  `accessTokenUri`: 提供访问令牌的OAuth提供者端点的uri
 *  `scope`: Comma-separted list of strings specifying the scope of the access to the resource. By default, no scope will be specified.
 *  `clientAuthenticationScheme`: The scheme used by your client to authenticate to the access token endpoint. Suggested values: "http\_basic" and "form". Default: "http\_basic". See section 2.1 of the OAuth 2 spec.

Different grant types have different concrete implementations of `OAuth2ProtectedResourceDetails` (e.g. `ClientCredentialsResource` for "client\_credentials" grant type). For grant types that require user authorization there is a further property:

*  `userAuthorizationUri`: The uri to which the user will be redirected if the user is ever needed to authorize access to the resource. Note that this is not always required, depending on which OAuth 2 profiles are supported.

In XML there is a `<resource/>` element that can be used to create a bean of type `OAuth2ProtectedResourceDetails`. It has attributes matching all the properties above.

### Client Configuration客户端配置 ###

很简单，使用 `@EnableOAuth2Client`就行。这个配置会做两件事:

*  创建一个过滤器bean (with ID `oauth2ClientContextFilter`) 存储当前请求和上下文. 如果在一个请求中需要认证，它管理了OAuth authentication uri的重定向的源地址和目的地址
 *  在请求范围内创建一个类型为 `AccessTokenRequest` 的bean. 授权类型是认证码授权或者隐式授权时，客户端能避免个体之间的冲突.

这个过滤器必须装入到应用程序中(e.g. using a Servlet initializer or `web.xml` configuration for a `DelegatingFilterProxy` with the same name).

The `AccessTokenRequest` can be used in an `OAuth2RestTemplate` like this:

@Autowired
    private OAuth2ClientContext oauth2Context;
    
    @Bean
    public OAuth2RestTemplate sparklrRestTemplate() {
    	return new OAuth2RestTemplate(sparklr(), oauth2Context);
    }

The OAuth2ClientContext is placed (for you) in session scope to keep the state for different users separate. Without that you would have to manage the equivalent data structure yourself on the server, mapping incoming requests to users, and associating each user with a separate instance of the `OAuth2ClientContext`.

In XML there is a `<client/>` element with an `id` attribute - this is the bean id for a servlet `Filter` that must be mapped as in the `@Configuration`case to a `DelegatingFilterProxy` (with the same name).

### Accessing Protected Resources访问受保护的资源 ###

一旦你提供好了所有的资源配置，你就可以访问那些资源了. 推荐的方法是使用spring3中的[ `RestTemplate` ][RestTemplate]. OAuth for Spring Security 提供了一个[RestTemplate][RestTemplate 1] 的扩展，只需要提供一个 [`OAuth2ProtectedResourceDetails`][OAuth2ProtectedResourceDetails].实例。 To use it with user-tokens (authorization code grants) you should consider using the `@EnableOAuth2Client` configuration (or the XML equivalent `<oauth:rest-template/>`) which creates some request and session scoped context objects so that requests for different users do not collide at runtime.

As a general rule, a web application should not use password grants, so avoid using `ResourceOwnerPasswordResourceDetails` if you can in favour of `AuthorizationCodeResourceDetails`. If you desparately need password grants to work from a Java client, then use the same mechanism to configure your `OAuth2RestTemplate` and add the credentials to the `AccessTokenRequest` (which is a `Map` and is ephemeral) not the `ResourceOwnerPasswordResourceDetails` (which is shared between all access tokens).

### Persisting Tokens in a Client持久化令牌 ###

A client does not *need* to persist tokens, but it can be nice for users to not be required to approve a new token grant every time the client app is restarted. The [`ClientTokenServices`][ClientTokenServices] interface defines the operations that are necessary to persist OAuth 2.0 tokens for specific users. There is a JDBC implementation provided, but you can if you prefer implement your own service for storing the access tokens and associated authentication instances in a persistent database. If you want to use this feature you need provide a specially configured `TokenProvider` to the `OAuth2RestTemplate`e.g.

@Bean@Scope(value = "session", proxyMode = ScopedProxyMode.INTERFACES)public OAuth2RestOperations restTemplate() {
    	OAuth2RestTemplate template = new OAuth2RestTemplate(resource(), new DefaultOAuth2ClientContext(accessTokenRequest));
    	AccessTokenProviderChain provider = new AccessTokenProviderChain(Arrays.asList(new AuthorizationCodeAccessTokenProvider()));
    	provider.setClientTokenServices(clientTokenServices());
    	return template;}

## Customizations for Clients of External OAuth2 Providers ##

Some external OAuth2 providers (e.g. [Facebook][]) do not quite implement the specification correctly, or else they are just stuck on an older version of the spec than Spring Security OAuth. To use those providers in your client application you might need to adapt various parts of the client-side infrastructure.

To use Facebook as an example, there is a Facebook feature in the `tonr2` application (you need to change the configuration to add your own, valid, client id and secret - they are easy to generate on the Facebook website).

Facebook token responses also contain a non-compliant JSON entry for the expiry time of the token (they use `expires` instead of `expires_in`), so if you want to use the expiry time in your application you will have to decode it manually using a custom `OAuth2SerializationService`.

转载于:https://blog.51cto.com/12180440/2341079

[http_projects.spring.io_spring-security-oauth_docs_oauth2.html]: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
[integration tests]: https://github.com/spring-projects/spring-security-oauth/tree/master/tests
[sample apps]: https://github.com/spring-projects/spring-security-oauth/tree/master/samples/oauth2
[test code in github]: https://github.com/spring-projects/spring-security-oauth/blob/master/spring-security-oauth2/src/test/resources/schema.sql
[AuthorizationServerTokenServices]: https://docs.spring.io/spring-security/oauth/apidocs/org/springframework/security/oauth2/provider/token/AuthorizationServerTokenServices.html
[DefaultTokenServices]: https://docs.spring.io/spring-security/oauth/apidocs/org/springframework/security/oauth2/provider/token/DefaultTokenServices.html
[JSON Web Token _JWT_ version]: https://projects.spring.io/spring-security-oauth/docs/%60JwtTokenStore%60
[expression-based access control]: https://docs.spring.io/spring-security/site/docs/3.2.5.RELEASE/reference/htmlsingle/#el-access
[OAuth2ProtectedResourceDetails]: https://projects.spring.io/spring-security-oauth2/src/main/java/org/springframework/security/oauth2/client/resource/OAuth2ProtectedResourceDetails.java
[RestTemplate]: https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html
[RestTemplate 1]: https://projects.spring.io/spring-security-oauth2/src/main/java/org/springframework/security/oauth2/client/OAuth2RestTemplate.java
[ClientTokenServices]: https://projects.spring.io/spring-security-oauth2/src/main/java/org/springframework/security/oauth2/client/token/ClientTokenServices.java
[Facebook]: https://developers.facebook.com/docs/authentication