ApiBoot 整合 OAuth2组件

ApiBoot整合OAuth2来完成资源的保护，通过在配置文件的具体配置来完成自动化集成，降低入门门槛。

ApiBoot OAuth同样是提供了两种方式：内存方式、JDBC方式来进行存储Token、客户端等信息，后期规划集成Redis进行存储AccessToken令牌信息，ApiBoot OAuth需要整合ApiBoot Security来配合使用，正因为如此，ApiBoot在构建Starter时将两者合并为了一个。

1. 添加依赖组件

在项目的pom.xml文件内添加如下依赖：

<!--ApiBoot Security Oauth-->
<dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-security-oauth-jwt</artifactId>
</dependency>

注意：如果未添加ApiBoot版本依赖，请访问版本依赖查看添加方式。

2. 内存方式

memory（内存方式）也是ApiBoot OAuth的默认方式，会将生成的access_token存放在内存中，通过我们简单的配置就可以完成快速集成OAuth2来保护你的接口资源，下面详细解释配置的作用。

2.1 配置客户端信息

client的概念在OAuth2里面相信大家并不陌生，只有被授权的客户端才可以访问/oauth/token获取对应的access_token访问令牌，而ApiBoot OAuth的内存方式客户端信息是在application.yml、application.properties文件内进行配置，如下所示：

api:
  boot:
    oauth:
          client-id: ApiBoot
          client-secret: ApiBootSecret

• api.boot.oauth.client-id：配置客户端编号信息（获取access_token时携带的Basic Auth的用户名），该参数默认值为ApiBoot
• api.boot.oauth.client-secret：配置客户端秘钥（获取access_token时携带的Basic Auth的密码），该参数默认值为ApiBootSecret

2.2 设置ResourceID

resource-id是授权访问的资源编号，默认值为api，如需修改如下所示：

api:
  boot:
    oauth:
      resource-id: api

2.3 设置客户端的授权方式（GrantType）

GrantType授权方式的配置，对应着客户端所拥有的权限，如：password对应着使用用户名、密码方式获取access_token，refresh_token则对应access_token过期后使用刷新的方式获取新的access_token，配置如下所示：

api:
  boot:
    oauth:
      grant-types: password,refresh_token

api.boot.oauth.grant-types配置默认值为：password,refresh_token，如果需要新增授权方式，配置多个使用,号隔开。

2.4 设置客户端的作用域（Scope）

Scope是配置客户端所授权的作用域，可以通过该配置进行权限检验，具体详细去了解Spring Security + OAuth2的注解使用，配置如下所示：

api:
  boot:
    oauth:
      scopes: api,admin

api.boot.oauth.scopes参数默认值为api，多个使用,号隔开，至少需要配置一个。

3. JDBC方式

ApiBoot OAuth支持使用JDBC方式将生成的AccessToken存放到数据库，以及在数据库内进行配置客户端的相关信息，比如：client_id、client_secret、grant_type、scopes等。我们如果需要使用ApiBoot OAuth的JDBC方式来实现，需要遵循OAuth2的建表SQL在需要的数据库内执行创建表结构，MySQL数据库对应的语句访问MySQL OAuth2 SQL获取，开启JDBC方式修改application.yml配置如下：

api:
  boot:
    oauth:
      away: jdbc

3.1 配置客户端信息

在使用OAuth2时，oauth_client_details信息表用于配置客户端的基本信息，新增一条数据对应授权一个新的客户端可以进行安全认证，我们可以执行下面SQL创建一个新的客户端信息：

INSERT INTO `oauth_client_details` VALUES ('ApiBoot','api','$2a$10$M5t8t1fHatAj949RCHHB/.j1mrNAbxIz.mOYJQbMCcSPwnBMJLmMK','api','password',NULL,NULL,7200,7200,NULL,NULL);

注意：client_secret列的数据必须通过BCryptPasswordEncoder进行加密，这里存储加密后的字符串。

3.2 设置ResourceID

修改oauth_client_details信息表内对应客户端的resource_ids列的数据内容即可，如果需要配置多个值时使用英文半角逗号隔开。

3.3 设置客户端的授权方式（GrantType）

修改oauth_client_details信息表内对应客户端的authorized_grant_types列的数据内容，如果需要配置多个授权方式同样使用英文半角逗号隔开。

3.4 设置客户端作用域（Scope）

修改oauth_client_details信息表内对应客户端的scope列的数据内容，如果需要配置多个授权方式同样使用英文半角逗号隔开。

4. Redis方式

ApiBoot OAuth从2.1.1.RELEASE版本开始支持使用Redis进行存储AccessToken，提高获取Token的响应效率，开启redis方式修改application.yml配置如下所示：

api:
  boot:
    oauth:
      away: redis

开启后我们还需要添加Redis的支持。

4.1 添加Redis支持

redis的支持需要在pom.xml内添加spring-boot-starter-data-redis依赖，并且在application.yml文件内配置redis相关信息。

4.1.1 添加依赖

在pom.xml文件内添加依赖如下所示：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

4.1.2 配置redis

在application.yml文件内添加对redis的配置，如下所示：

spring:
  redis:
    # 密码根据你的配置填写
    password: 123456
    # redis主机IP
    host: 127.0.0.1

4.2 配置客户端信息

ApiBoot OAuth从2.1.1.RELEASE版本开始支持多客户端配置，redis方式的配置与memory内存方式一致，在application.yml配置文件内对应配置客户端信息，如下所示：

api:
  boot:
    oauth:
      # 开启使用redis存储token
      away: redis
      # 启用jwt
      jwt:
        enable: true
      # 配置oauth2客户端列表
      clients:
        - client-id: admin
          client-secret: admin_secret
        - client-id: platform
          client-secret: platform_secret

5. 获取AccessToken

获取access_token是我们集成ApiBoot OAuth的必经之路，我们需要携带access_token去访问受保护的资源，下面提供了多种途径获取access_token，按需选择使用。

5.1 CURL方式

在Mac、Linux系统下可以直接通过curl命令行进行获取access_token，命令如下所示：

~ curl ApiBoot:ApiBootSecret@localhost:8080/oauth/token -d "grant_type=password&username=apiboot&password=abc321"
获取结果：
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiYXBpIl0sInVzZXJfbmFtZSI6ImFwaWJvb3QiLCJzY29wZSI6WyJhcGkiXSwiZXhwIjoxNTYwNDQ2NDc5LCJhdXRob3JpdGllcyI6WyJST0xFX2FwaSJdLCJqdGkiOiI2ZmQ0ZDdiNi1kN2JkLTRiMmUtYmFlYi1iNGMwMmRlMjM0YmYiLCJjbGllbnRfaWQiOiJBcGlCb290In0.l_38N6gJbSug_uzJLope9uJQsA12BfJNDlGFmB-UQMU","token_type":"bearer","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiYXBpIl0sInVzZXJfbmFtZSI6ImFwaWJvb3QiLCJzY29wZSI6WyJhcGkiXSwiYXRpIjoiNmZkNGQ3YjYtZDdiZC00YjJlLWJhZWItYjRjMDJkZTIzNGJmIiwiZXhwIjoxNTYyOTk1Mjc5LCJhdXRob3JpdGllcyI6WyJST0xFX2FwaSJdLCJqdGkiOiIxNmZhZThlNi00ZDM3LTQ1NTctOTZiYi1hMWQ4MjBkOTk2NTYiLCJjbGllbnRfaWQiOiJBcGlCb290In0.egICzqsReO0hxheUv2i7u-3vloo7kYf1-_JqMcSR240","expires_in":42378,"scope":"api","jti":"6fd4d7b6-d7bd-4b2e-baeb-b4c02de234bf"}

根据上面的curl命令，各个组成部分值解释：

• ApiBoot：客户端编号，取决于client_id配置的值
• ApiBootSecret，客户端秘钥，取决于client_secret配置的值
• grant_type=password：授权方式，取决于配置的授权方式。
• apiboot：当grant_type=password时传递的ApiBoot Security配置的用户名（username）
• abc123：当grant_type=password时传递的ApiBoot Security配置的密码（password）

5.2 PostMan方式

注意：

1. 获取access_token的请求方式是POST。
2. 使用Basic方式认证客户端信息
3. 不要混淆客户端的clientId、clientSecret与用户的username、password的概念。

5.3 RestTemplate方式

// 获取Token请求路径
String access_token_uri = "http://localhost:8080/oauth/token?grant_type=password&username=apiboot&password=abc321";
// 客户端Id
String clientId = "ApiBoot";
// 客户端Secret
String clientSecret = "ApiBootSecret";
// basic认证的格式
String basicAuth = "Basic %s";
// 可以使用注入RestTemplate方式获取对象实例
RestTemplate restTemplate = new RestTemplate();
// 请求头
HttpHeaders headers = new HttpHeaders();
// 设置客户端的basic认证信息
headers.set("Authorization", String.format(basicAuth, Base64Utils.encodeToString((clientId + ":" + clientSecret).getBytes())));
// 请求主体
HttpEntity<String> httpEntity = new HttpEntity<>(headers);
// 发送请求，获取access_token
String access_token = restTemplate.postForObject(access_token_uri, httpEntity, String.class);
System.out.println(access_token);

6. 自定义授权方式（GrantType）

OAuth2内部提供了一些内置的grant_type，根据业务需求有时需要自定义，比如：手机号验证码登录、第三方微信登录等，针对这种场景ApiBoot OAuth提供了自定义授权的方式，我们需要通过实现接口ApiBootOauthTokenGranter来完成自定义授权的业务编写。

6.1 了解OAuth2内置的GrantType

以下是集成OAuth2常用的几种授权方式：

• password：用户名密码方式
• refresh_token：刷新access_token
• authorization_code：授权码方式
• client_credentials：客户端方式

6.2 了解ApiBootOauthTokenGranter接口

ApiBootOauthTokenGranter接口是ApiBoot OAuth提供的自定义授权方式的定义。

6.2.1 grantType方法

/**
* oauth2 grant type for ApiBoot
*
* @return grant type
*/
String grantType();

该方法返回自定义授权方式，如该方法返回phone_code，对应在获取access_token时使用/oauth/token?grant_type=phone_code。

6.2.2 loadByParameter方法

/**
* load userDetails by parameter
*
* @param parameters parameter map
* @return UserDetails
* @throws ApiBootTokenException
* @see UserDetails
*/
UserDetails loadByParameter(Map<String, String> parameters) throws ApiBootTokenException;

loadByParameter方法的参数是一个请求参数的集合，是在发起获取access_token时所携带的参数列表，我们拿到参数后可以进行数据校验，校验通过后返回实现UserDetails接口的具体类型实例。

6.3 自定义授权方式

在上面简单介绍了ApiBootOauthTokenGranter接口，下面提供一个短信验证码登录的示例。

6.3.1 短信验证码方式登录示例

/**
 * 短信验证码登录示例
 *
 * @author 恒宇少年 - 于起宇
 * <p>
 * DateTime：2019-06-06 09:15
 * Blog：http://blog.yuqiyu.com
 * WebSite：http://www.jianshu.com/u/092df3f77bca
 * Gitee：https://gitee.com/hengboy
 * GitHub：https://github.com/hengboy
 */
@Component
public class PhoneCodeOauthTokenGranter implements ApiBootOauthTokenGranter {
    /**
     * logger instance
     */
    static Logger logger = LoggerFactory.getLogger(PhoneCodeOauthTokenGranter.class);
    /**
     * 获取Token时使用grant_type=phone_code授权方式
     */
    private static final String GRANT_TYPE = "phone_code";
    /**
     * 参数：手机号
     */
    private static final String PARAM_PHONE = "phone";
    /**
     * 参数：验证码
     */
    private static final String PARAM_CODE = "code";
    @Override
    public String grantType() {
        return GRANT_TYPE;
    }
    /**
     * 该方法参数集合是获取Token时携带的参数
     * 获取Token路径：/oauth/token?grant_type=phone_code&phone=171xxxxx&code=196523
     * phone=171xxxxx
     * code=196523
     *
     * @param parameters parameter map
     * @return
     * @throws ApiBootTokenException
     */
    @Override
    public UserDetails loadByParameter(Map<String, String> parameters) throws ApiBootTokenException {
        String phone = parameters.get(PARAM_PHONE);
        String code = parameters.get(PARAM_CODE);
        logger.debug("手机号：{}", phone);
        logger.debug("验证码：{}", code);
        // 自定义数据逻辑校验验证码是否正确、是否与该手机号匹配等
        // 校验通过后返回实现SpringSecurity提供的UserDetails接口的数据实体即可
        return new UserDetails() {
            @Override
            public Collection<? extends GrantedAuthority> getAuthorities() {
                return null;
            }
            @Override
            public String getPassword() {
                return null;
            }
            @Override
            public String getUsername() {
                return phone;
            }
            @Override
            public boolean isAccountNonExpired() {
                return true;
            }
            @Override
            public boolean isAccountNonLocked() {
                return true;
            }
            @Override
            public boolean isCredentialsNonExpired() {
                return true;
            }
            @Override
            public boolean isEnabled() {
                return true;
            }
        };
    }
}

6.3.2 配置客户端支持自定义授权方式

在上面我们定义短信验证码方式的授权，我们需要让客户端支持该授权方式，内存方式参考本章文档[2.3]，JDBC方式参考本章文档[3.3]

6.3.3 获取自定义授权方式AccessToken

ApiBoot OAuth修改了Oauth2内部有关授权的源码方式进行实现，所以获取Token跟内置的授权方式没有区别，只不过是grant_type参数有所变动，针对上面自定义短信验证码登录的授权方式获取Token如下所示：

curl ApiBoot:ApiBootSecret@localhost:8080/oauth/token -d "grant_type=phone_code&phone=171xxxx&code=026492"

本次获取access_token的所有参数都会传递给ApiBootOauthTokenGranter#loadByParameter方法的参数集合内。

7. 使用JWT格式化AccessToken

使用JWT格式化access_token是一个很常见的需求，因此ApiBoot OAuth内部针对JWT进行了支持，通过简单的配置参数就可以使用JWT对access_token进行格式化。

7.1 配置JWT秘钥

JWT内部使用RSA方式进行加密，加密时需要使用秘钥Key，ApiBoot Security Oauth内部默认使用ApiBoot作为秘钥Key，如果需要修改我们可以通过api.boot.oauth.jwt.sign-key参数进行设置，如下所示：

api:
  boot:
    oauth:
      away: jdbc
      jwt:
        # 转换Jwt时所需加密key，默认为ApiBoot
        sign-key: 恒宇少年 - 于起宇

7.2 开启JWT

在ApiBoot Security Oauth内默认集成了JWT格式化Oauth Access Token的转换方式，但是并未启用，需要通过api.boot.oauth.jwt.enable来开启JWT，如下所示：

api:
  boot:
    oauth:
      away: jdbc
      jwt:
        # 开启Jwt转换AccessToken
        enable: true