OAuth 2 开发人员指南

这是支持OAuth2.0的用户指南。对于OAuth1.0，一切都是不一样的，因此看它的用户指南。
本用户指南分为两个部分，第一部分是OAuth2.0提供端（OAuth 2.0 Provider），第二部分是OAuth2.0的客户端（OAuth 2.0 Client）
OAuth2.0提供端

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

在 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

配置受权服务器时,您必须考虑的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的子元素。

	
配置端点的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。 它有上面提到的全部的属性。

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


Knowvin
Knowvin
翻译于 9个月前
0人顶
顶 翻译的不错哦!
为外部 OAuth2 提供者定制客户端

一些外部OAuth2提供商(如Facebook)不彻底实现正确规范,不然他们只是困在一个旧版本比Spring Security OAuth的规范。在您的客户机应用程序使用这些供应商可能须要适应客户端基础设施的各个部分。
使用Facebook做为一个例子,有一个Facebook功能tonr2应用程序(您须要更改配置添加你本身的,有效的,客户机id和秘密,他们很容易生成在Facebook网站上)。
Facebook响应令牌也包含一个不一致的、有失效时间的JSON实体(他们使用到期而不是expires_in),因此若是你想在应用程序中使用失效时间你将不得不使用一个自定义OAuth2SerializationService手动解码。

 

 

https://github.com/ymero/HeidCloud/blob/master/OAuth%202%20%E5%BC%80%E5%8F%91%E4%BA%BA%E5%91%98%E6%8C%87%E5%8D%97.md