OAuth2.0开发人员指南（Spring security oauth2）

218次阅读

共计 12745 个字符，预计需要花费 32 分钟才能阅读完成。

入门

这是支持 OAuth2.0 的用户指南。对于 OAuth1.0，一切都是不同的，所以看它的用户指南。

本用户指南分为两个部分，第一部分是 OAuth2.0 提供端（OAuth 2.0 Provider），第二部分是 OAuth2.0 的客户端（OAuth 2.0 Client）

OAuth2.0 提供端

OAuth2.0 的提供端的用途是负责将受保护的资源暴露出去。配置包括建立一个可以访问受保护的资源的客户端代表。提供端是通过管理和验证可用于访问受保护的资源的 OAuth 2 令牌来做的。在适当的地方，提供端也必须为用户提供一个用于确认客户端是否能够访问受保护的资源的接口（也就是一个页面或是一个窗口）。

在 OAuth 2 提供者其实是分成授权服务和资源服务两个角色的，而这两个角色有时是存在于同一个应用程序中的，通过 Spring Security OAuth 你可以有选择的将它们分裂到两个应用程序中，也可以有选择的给授权服务配置多个资源服务。获取令牌（Tokens）的请求是由 Spring MVC 的控制器端点来处理的，访问受保护的资源是通过标准的 Spring Security 请求过滤器来处理的。

下面列举的端点是 Spring Security 过滤器链实现 OAuth 2 授权服务器必须的端点：

AuthorizationEndpoint 是用于授权服务请求的。默认的 URL 是：/oauth/authrize。
TokenEndpoint 是用于获取访问令牌（Access Tokens）的请求。默认的 URL 是：/oauth/token。

下面过滤器是实现一个 OAuth2 资源服务器所必须的：

OAuth2AuthenticationProcessingFilter 这个过滤器是用于加载请求提供的一个授权了的访问令牌是否有效。

对于所有的 OAuth 2.0 的提供端，通过使用 Spring OAuth 专门的 @Configuration 适配器来简化配置。也可以通过 XML 命名空间来配置 OAuth，XML 的 schema 存在：http://www.springframework.org/schema/security/spring-security-oauth2.xsd。命令空间是 http://www.springframework.org/schema/security/oauth2

Spring Security 学习之数据库认证 http://www.linuxidc.com/Linux/2014-02/97407.htm

Spring Security 学习之 LDAP 认证 http://www.linuxidc.com/Linux/2014-02/97406.htm

Spring Security 学习之 OpenID 认证 http://www.linuxidc.com/Linux/2014-02/97405.htm

Spring Security 学习之 X.509 认证 http://www.linuxidc.com/Linux/2014-02/97404.htm

Spring Security 学习之 HTTP 基本认证和 HTTP 摘要认证 http://www.linuxidc.com/Linux/2014-02/97403.htm

Spring Security 学习之 HTTP 表单验证 http://www.linuxidc.com/Linux/2014-02/97402.htm

授权服务器配置

配置授权服务器时, 您必须考虑的 grant 类型，从终端用户那，客户端会使用获取到的访问令牌(如授权代码、用户凭证、刷新令牌)。服务器的配置是用于提供一些实现，像客户端细节服务和令牌服务还有启用或禁用某些方面的全球机制。但是请注意, 每个客户端可以专门配置权限能够使用某些授权机制和访问授权。即仅仅因为您的提供者配置为支持“客户证书”grant 类型, 并不意味着一个特定的客户端被授权使用 grant 类型。

@EnableAuthorizationServer 注释用于配置 OAuth 2.0 授权服务器机制，加上任意一个 @Beans 去实现 AuthorizationServerConfigurer (这是一个 hander 适配器实现的空方法)。以下功能委托给由 spring 创造的独立 configurers 而且传递到 AuthorizationServerConfigurer：

ClientDetailsServiceConfigurer: 这个 configurer 定义了客户端细节服务。客户详细信息可以被初始化, 或者你可以参考现有的商店。
AuthorizationServerSecurityConfigurer: 在令牌端点上定义了安全约束。
AuthorizationServerEndpointsConfigurer: 定义了授权和令牌端点和令牌服务

提供端配置中重要的一项是提供给 OAuth 客户端的授权码。OAuth 客户端通过将终端用户导向一个可以输入证书 / 口令的授权验证页面来获取授权码，然后，将授权码传递给提供端授权服务器，服务器验证后重定向页面。在 OAuth 2 说明文档中有详细的示例。

在 xml 配置文件中，可以使用 <authorization-server/> 节点配置 OAuth 2.0 授权服务器。

配置客户端详细步骤

ClientDetailsServiceConfigurer 类（AuthorizationServerConfigurer 类中的一个调用类）可以用来定义一个基于内存的或者 JDBC 的客户端信息服务。

客户端对象重要的属性有：

clientId：（必须）客户端 id。
secret：（对于可信任的客户端是必须的）客户端的私密信息。
scope：客户端的作用域。如果 scope 未定义或者为空（默认值），则客户端作用域不受限制。
authorizedGrantTypes：授权给客户端使用的权限类型。默认值为空。
authorities：授权给客户端的权限（Spring 普通的安全权限）。

在运行的应用中，可以通过直接访问隐藏的存储文件（如：JdbcClientDetailsService 中用到的数据库表）或者通过实现 ClientDetailsManager 接口（也可以实现 ClientDetailsService 接口，或者实现两个接口）来更新客户端信息。

管理令牌

AuthorizationServerTokenServices 接口里定义了 OAuth 2.0 令牌的操作方法。注意以下几点：

创建一个访问令牌时，必须保存权限信息，这样后续令牌才可以引用它。
访问令牌用于加载创建令牌时的授权信息。

创建 AuthorizationServerTokenServices 接口的实现类时，你可以考虑使用DefaultTokenServices 类，它使用随机值创建令牌，并处理除永久令牌以外的所有令牌，对于永久令牌，它委托 TokenStore 类进行处理。令牌默认采用基于内存实现的存储方式，但也有一些其它的存储方式。下面是其中一些方式的简介：

默认的 InMemoryTokenStore 处理类对于单服务器场景非常适用（优点有：低阻塞，宕机时无需热切换到备份服务器）。大部分项目可以在开始时或者在开发模式下使用这种方式，这样比较容易启动一个没有其它依赖的服务器。
JdbcTokenStore 类是实现存储令牌的 JDBC 版本，它将令牌信息保存到关系型数据库中。如果服务器间共享数据库或者同一个服务器有多个实例或者授权服务器、资源服务器有多个组件，那么可以使用JDBC 方式存储令牌。使用 JdbcTokenStore 类时，需要将 spring-jdbc 组件 jar 包添加到工程的编译路径中。
JSON 网页令牌（JWT）可以加密所有令牌授权访问的数据（因此不需要在后台存储数据，这就是 JWT 一个重要的优点）。缺点是你不能方便地撤销一个已授权的令牌（因此一般它们被授权的有效期较短，撤销授权的操作在刷新令牌中进行）。另一个缺点是存储的令牌数据会越来越大因为在令牌里面存储了大量的用户证书信息。JwtTokenStore 类不是一个真正的存储类，它未持久化（保存）任何数据，但是它在传输令牌信息和授权信息（在 DefaultTokenServices 类中实现）中扮演了同样的角色。JwtTokenStore（接口）类依赖 JwtAccessTokenConverter 类，授权服务器和资源服务器都需要接口的实现类（因此他们可以安全地使用相同的数据并进行解码）。令牌以默认方式进行签名，资源服务器为了能够验证这些签名，它需要有与授权服务器相同的对称密钥（服务器共享对称密钥），或者它需要有可以匹配签名私钥的公钥（公有私有密钥或混合密钥）。为了使用 JwtTokenStore 类，你需要在工程编译路径下添加 spring-security-jwt 组件 jar 包（你可以在 Spring OAuth 的github资源库中找到，但是两者的版本号是不一致的）。

Grant 类型

AuthorizationEndpoint 通过 AuthorizationServerEndpointsConfigurer 可以配置支持 Grant 类型。默认情况下支持所有的 grant 类型，除了密码(有关详细信息, 请参阅下面的信息如何开启和关闭)。以下属性影响 grant 类型：
• authenticationManager：密码授予被注入一个 authenticationManager 开启。
• authorizationCodeServices：为了身份验证代码授予定义了授权代码服务(org.springframework.security.oauth2.provider.code.AuthorizationCodeServices 实例).
• implicitGrantService：在隐式授予管理状态。
• tokenGranter:TokenGranter(完全掌控的授予和忽略上面的其他属性) 在 XML grant 类型包括 authorization-server 的子元素。

更多详情见请继续阅读下一页的精彩内容：http://www.linuxidc.com/Linux/2014-10/107716p2.htm

配置端点的 URL

AuthorizationServerEndpointsConfigurer 有一个 pathMapping()方法。该方法有两个参数：

defaultPath 默认的端点 URL
customPath 自定义的 URL

框架自己提供的 URL 路径是 /oauth/authorize（授权端），/oauth/token (令牌端)，/oauth/confirm_access (用户发送确认授权到这里)，还有 /oauth/error (用户呈现授权服务器授权出错的请求)。

注意：授权端 /oauth/authorize（或者是它的影射）应该是受 Spring Security 保护的，所以它只能被已授权的用户访问。令牌端默认是通过使用支持使用 HTTP 基本身份验证客户机的秘密的注解 @Configuration，被 Spring Oauth 保护的，但不是使用 XML 文件的（所以在这种情况下它被保护是很明确的）。

使用 XML 的 <authorization-server/> 元素可以使用一些属性来达到改变默认的端点 URL。

自定义错误处理

授权服务器上错误处理使用标准的 Spring MVC 功能, 即 @ExceptionHandler 端点本身的方法。用户还可以提供一个 WebResponseExceptionTranslator 端点本身, 最好的办法是改变响应的内容而不是他们呈现的方式。异常的呈现代表 HttpMesssageConverters (这个可以添加到 MVC 的配置中)令牌的端点和 OAuth 的错误视图 (/ OAuth /error) 的授权端点。提供一个 whitelabel 错误端点, 但是用户可能需要提供一个自定义的实现(例如, 就添加一个 @Controller，它的请求映射是 @RequestMapping(“/ oauth /error”))。

配置资源服务器

资源服务器（可能和授权服务器或者一个单独的应用程序在同一台主机上）提供被 OAuth2 令牌保护的资源。Spring OAuth 提供一个 Spring Security 授权过滤器，它实现保护资源的功能。在 @Configuration 类中，你可以使用 @EnableResourceServer 来开启 / 关闭过滤器，使用 ResourceServerConfigurer 来配置它。下面是可配置的属性：

tokenServices：定义令牌服务的实体（ResourceServerTokenServices 类的实例）。
resourceId：资源 ID（可选的，建议配置，如果不为空，授权服务器会对它进行验证）。

@EnableResourceServer 注解把一个 OAuth2AuthenticationProcessingFilter 类型过滤器添加到 Spring Security 过滤链中。

在 XML 中，有一个 <resource-server/> 元素，它有一个 id 属性 – 这是 servlet 过滤器的 bean id，它过滤哪些可以被添加到 Spring Security 链中。

配置 OAuth-Aware 表达式处理器

你可能想要使用 Spring Security 的使用表达式语言配置访问控制的优点。表达式处理器在 @EnableResourceServer 配置中以默认方式进行注册。表达式包括#oauth2.clientHasRole,#oauth2.clientHasAnyRole, 和 #oath2.denyClient，这些可以提供基于 oauth 客户端角色的访问控制（详细列表见 OAuth2SecurityExpressionMethods）。在 XML 中，你可以在 <http/> 安全配置节点内使用 expression-handler 元素注册一个 oauth-aware 表达式处理器。

OAuth 2.0 客户端

OAuth 2.0 客户端控制着 OAuth 2.0 保护的其它服务器的资源的访问权限。配置包括建立相关受保护资源与有权限访问资源的用户之间的连接。客户端也需要实现存储用户的授权代码和访问令牌的功能。

受保护资源的配置

受保护的资源（或称为远程资源）可以使用 OAuth2ProtectedResourceDetails 类型的实体 bean 定义。一个受保护的资源有以下属性：

id：资源 id。它仅在客户端搜索资源的时候使用；在 OAuth 协议中它从未被用到。它也被用作 bean 的 id。
clientId：OAuth 客户端 id。OAuth 提供端依赖这个 id 来识别客户端。
clientSecret：与资源有关的秘密。默认情况下，该值不为空。
accessTokenUri：提供访问口令的 OAuth 提供者终端的统一资源标识符（URI）。
scope：以逗号分隔的字符串列表，标识可访问资源的范围。默认情况下，该值为空。
clientAuthenticationScheme：客户端对访问的令牌终端授权时使用的机制。建议值：“http_basic” 和 “form”。默认值：“http_basic”。见 OAuth 2 帮助文档 2.1 节。

不同的授权类型有不同的实现 OAuth2ProtectedResourceDetails（对于 client_credentials 授权类型，使用 ClientCredentialsResource）的方式。对于需要进行用户身份验证的授权类型，还有一个属性：

userAuthorizationUri：用户访问资源需要身份验证时跳转页面的 URI。注意这个字段不是必填的，它依赖于被支持的OAuth 2 的配置文件类型。

在 XML 中，可以使用 <resource/> 元素创建一个 OAuth2ProtectedResourceDetails 类型的实体 bean。它有上面提到的所有的属性。

入门

这是支持 OAuth2.0 的用户指南。对于 OAuth1.0，一切都是不同的，所以看它的用户指南。

本用户指南分为两个部分，第一部分是 OAuth2.0 提供端（OAuth 2.0 Provider），第二部分是 OAuth2.0 的客户端（OAuth 2.0 Client）

OAuth2.0 提供端

OAuth2.0 的提供端的用途是负责将受保护的资源暴露出去。配置包括建立一个可以访问受保护的资源的客户端代表。提供端是通过管理和验证可用于访问受保护的资源的 OAuth 2 令牌来做的。在适当的地方，提供端也必须为用户提供一个用于确认客户端是否能够访问受保护的资源的接口（也就是一个页面或是一个窗口）。

在 OAuth 2 提供者其实是分成授权服务和资源服务两个角色的，而这两个角色有时是存在于同一个应用程序中的，通过 Spring Security OAuth 你可以有选择的将它们分裂到两个应用程序中，也可以有选择的给授权服务配置多个资源服务。获取令牌（Tokens）的请求是由 Spring MVC 的控制器端点来处理的，访问受保护的资源是通过标准的 Spring Security 请求过滤器来处理的。

下面列举的端点是 Spring Security 过滤器链实现 OAuth 2 授权服务器必须的端点：

AuthorizationEndpoint 是用于授权服务请求的。默认的 URL 是：/oauth/authrize。
TokenEndpoint 是用于获取访问令牌（Access Tokens）的请求。默认的 URL 是：/oauth/token。

下面过滤器是实现一个 OAuth2 资源服务器所必须的：

OAuth2AuthenticationProcessingFilter 这个过滤器是用于加载请求提供的一个授权了的访问令牌是否有效。

对于所有的 OAuth 2.0 的提供端，通过使用 Spring OAuth 专门的 @Configuration 适配器来简化配置。也可以通过 XML 命名空间来配置 OAuth，XML 的 schema 存在：http://www.springframework.org/schema/security/spring-security-oauth2.xsd。命令空间是 http://www.springframework.org/schema/security/oauth2

Spring Security 学习之数据库认证 http://www.linuxidc.com/Linux/2014-02/97407.htm

Spring Security 学习之 LDAP 认证 http://www.linuxidc.com/Linux/2014-02/97406.htm

Spring Security 学习之 OpenID 认证 http://www.linuxidc.com/Linux/2014-02/97405.htm

Spring Security 学习之 X.509 认证 http://www.linuxidc.com/Linux/2014-02/97404.htm

Spring Security 学习之 HTTP 基本认证和 HTTP 摘要认证 http://www.linuxidc.com/Linux/2014-02/97403.htm

Spring Security 学习之 HTTP 表单验证 http://www.linuxidc.com/Linux/2014-02/97402.htm

授权服务器配置

配置授权服务器时, 您必须考虑的 grant 类型，从终端用户那，客户端会使用获取到的访问令牌(如授权代码、用户凭证、刷新令牌)。服务器的配置是用于提供一些实现，像客户端细节服务和令牌服务还有启用或禁用某些方面的全球机制。但是请注意, 每个客户端可以专门配置权限能够使用某些授权机制和访问授权。即仅仅因为您的提供者配置为支持“客户证书”grant 类型, 并不意味着一个特定的客户端被授权使用 grant 类型。

@EnableAuthorizationServer 注释用于配置 OAuth 2.0 授权服务器机制，加上任意一个 @Beans 去实现 AuthorizationServerConfigurer (这是一个 hander 适配器实现的空方法)。以下功能委托给由 spring 创造的独立 configurers 而且传递到 AuthorizationServerConfigurer：

ClientDetailsServiceConfigurer: 这个 configurer 定义了客户端细节服务。客户详细信息可以被初始化, 或者你可以参考现有的商店。
AuthorizationServerSecurityConfigurer: 在令牌端点上定义了安全约束。
AuthorizationServerEndpointsConfigurer: 定义了授权和令牌端点和令牌服务

提供端配置中重要的一项是提供给 OAuth 客户端的授权码。OAuth 客户端通过将终端用户导向一个可以输入证书 / 口令的授权验证页面来获取授权码，然后，将授权码传递给提供端授权服务器，服务器验证后重定向页面。在 OAuth 2 说明文档中有详细的示例。

在 xml 配置文件中，可以使用 <authorization-server/> 节点配置 OAuth 2.0 授权服务器。

配置客户端详细步骤

ClientDetailsServiceConfigurer 类（AuthorizationServerConfigurer 类中的一个调用类）可以用来定义一个基于内存的或者 JDBC 的客户端信息服务。

客户端对象重要的属性有：

clientId：（必须）客户端 id。
secret：（对于可信任的客户端是必须的）客户端的私密信息。
scope：客户端的作用域。如果 scope 未定义或者为空（默认值），则客户端作用域不受限制。
authorizedGrantTypes：授权给客户端使用的权限类型。默认值为空。
authorities：授权给客户端的权限（Spring 普通的安全权限）。

在运行的应用中，可以通过直接访问隐藏的存储文件（如：JdbcClientDetailsService 中用到的数据库表）或者通过实现 ClientDetailsManager 接口（也可以实现 ClientDetailsService 接口，或者实现两个接口）来更新客户端信息。

管理令牌

AuthorizationServerTokenServices 接口里定义了 OAuth 2.0 令牌的操作方法。注意以下几点：

创建一个访问令牌时，必须保存权限信息，这样后续令牌才可以引用它。
访问令牌用于加载创建令牌时的授权信息。

创建 AuthorizationServerTokenServices 接口的实现类时，你可以考虑使用DefaultTokenServices 类，它使用随机值创建令牌，并处理除永久令牌以外的所有令牌，对于永久令牌，它委托 TokenStore 类进行处理。令牌默认采用基于内存实现的存储方式，但也有一些其它的存储方式。下面是其中一些方式的简介：

默认的 InMemoryTokenStore 处理类对于单服务器场景非常适用（优点有：低阻塞，宕机时无需热切换到备份服务器）。大部分项目可以在开始时或者在开发模式下使用这种方式，这样比较容易启动一个没有其它依赖的服务器。
JdbcTokenStore 类是实现存储令牌的 JDBC 版本，它将令牌信息保存到关系型数据库中。如果服务器间共享数据库或者同一个服务器有多个实例或者授权服务器、资源服务器有多个组件，那么可以使用JDBC 方式存储令牌。使用 JdbcTokenStore 类时，需要将 spring-jdbc 组件 jar 包添加到工程的编译路径中。
JSON 网页令牌（JWT）可以加密所有令牌授权访问的数据（因此不需要在后台存储数据，这就是 JWT 一个重要的优点）。缺点是你不能方便地撤销一个已授权的令牌（因此一般它们被授权的有效期较短，撤销授权的操作在刷新令牌中进行）。另一个缺点是存储的令牌数据会越来越大因为在令牌里面存储了大量的用户证书信息。JwtTokenStore 类不是一个真正的存储类，它未持久化（保存）任何数据，但是它在传输令牌信息和授权信息（在 DefaultTokenServices 类中实现）中扮演了同样的角色。JwtTokenStore（接口）类依赖 JwtAccessTokenConverter 类，授权服务器和资源服务器都需要接口的实现类（因此他们可以安全地使用相同的数据并进行解码）。令牌以默认方式进行签名，资源服务器为了能够验证这些签名，它需要有与授权服务器相同的对称密钥（服务器共享对称密钥），或者它需要有可以匹配签名私钥的公钥（公有私有密钥或混合密钥）。为了使用 JwtTokenStore 类，你需要在工程编译路径下添加 spring-security-jwt 组件 jar 包（你可以在 Spring OAuth 的github资源库中找到，但是两者的版本号是不一致的）。

Grant 类型

AuthorizationEndpoint 通过 AuthorizationServerEndpointsConfigurer 可以配置支持 Grant 类型。默认情况下支持所有的 grant 类型，除了密码(有关详细信息, 请参阅下面的信息如何开启和关闭)。以下属性影响 grant 类型：
• authenticationManager：密码授予被注入一个 authenticationManager 开启。
• authorizationCodeServices：为了身份验证代码授予定义了授权代码服务(org.springframework.security.oauth2.provider.code.AuthorizationCodeServices 实例).
• implicitGrantService：在隐式授予管理状态。
• tokenGranter:TokenGranter(完全掌控的授予和忽略上面的其他属性) 在 XML grant 类型包括 authorization-server 的子元素。

更多详情见请继续阅读下一页的精彩内容：http://www.linuxidc.com/Linux/2014-10/107716p2.htm

使用 @EnableOAuth2Client 对 OAuth2.0 的客户端的配置比较简单。主要要做两件事情：

创建一个过滤 bean(用 oauth2ClientContextFilter)来存储当前的请求和上下文。在这种情况下需要在请求期间授权，来管理从重定向的位置和 OAuth 已认证的 url。
在请求作用域中创建一个 AccessTokenRequest 类型的 bean。这个类型的 bean 可以在个人用户的冲突中被识别码识别（或隐式的），授权客户端保持授权状态。

这个过滤器需要能够连接到应用（例如，使用 Servlet 初始化程序或者 web.xml 配置文件配置一个和 DelegatingFilterProxy 相同名称的代理）。

在一个 OAuth2RestTemplate 中 AccessTokenRequest 可以这样使用：

@Autowired
private OAuth2ClientContext oauth2Context;

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

OAuth2ClientContext 可以在 Session 的作用域中保持不同用户不同的状态。如果没有这个功能，你需要在你自己的服务强上管理等效的数据结构，映射不用用户进来的请求并且用相互隔离的 OAuth2ClientContext 实例连接各个用户。

在 XML 文件中，有一个带有 id 属性的 <client/> 标签用于表示 servlet 的 Filter 的 bean id，这个必须映射成一个和 DelegatingFilterProxy 有相同名称的 @Configuration 注解。

访问受保护的资源

一旦，你已经提供了所有的资源服务器配置时，现在你可以访问这些资源。建议的访问这些资源是通过使用在 Spring3 中提到的 RestTemplate。Spring Security OAuth 已经提供了一个扩展的 RestTemplate，只需要提供一个 OAuth2ProtectedResourceDetails 的实例。使用它与 user-tokens(授权代码授予)你应该考虑使用 @EnableOAuth2Client 配置(或 XML 等价 < oauth:rest-template / >), 造成了一些请求和会话作用域上下文对象, 要求不同的用户在运行时不发生冲突。

客户端持久化访问令牌

客户端不需要持久化令牌, 但是它可以很好的用户不需要批准一个新的令牌格兰特每次重新启动客户机应用程序。ClientTokenServices 接口定义所需的操作持续 OAuth 2.0 为特定用户令牌。提供一个 JDBC 实现, 但是如果你喜欢的话你可以实现自己的服务以存储的访问令牌持久数据库和相关的验证实例。如果你想使用此功能, 你需要提供一个专门配置 TokenProvider theOAuth2RestTemplate 如

@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;}