准备工作

一、下载必备物料

下载最新版OAuth2.0 SDK，快速下载链接：:sunglasses:点我下载
请升级您的开发环境，保证至少为JDK1.7版本，低版本不支持
请确保项目引用的Servlet API版本为3.0以上。建议使用至少tomcat8作为开发容器
这里写一下SDK的javadoc地址：文档地址

二、准备开发工作

请确认您对接的系统已经在认证中心注册，需要提供：
- 外网可访问的地址
- 您的系统id（建议自定义，并且用Base64编码）
  在此步结束后，您应该已经拥有两个字段：
```
ClientId、ClientSecret
```
  这两个字段非常重要，是系统对接的关键。
几个内置的uri需要注意：
- ${您的网站}/oauth/callback : 这是内置Servlet提供的回调地址。用户先访问系统，跳转到认证中心后，
  将会作为回调地址，由SDK接受参数并自动获取token。
- ${认证中心}/login : 这是认证中心的登录地址
全局过滤器Filter（由SDK提供）

SDK提供了默认的过滤器，会对贵方的服务端请求进行全量过滤，原理是通过判断token的有效性来决定放行，
如果token不存在或者无效，将会自动重定向到授权页面，交给用户授权登录。这些均只需要托管即可

Maven项目的依赖配置

<dependencies>
    <!-- https://mvnrepository.com/artifact/javax.servlet/javax.servlet-api -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>com.github.scribejava</groupId>
        <artifactId>scribejava-core</artifactId>
        <version>6.0.0</version>
    </dependency>
   
    <!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.6</version>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-collections4</artifactId>
        <version>4.1</version>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.8</version>
    </dependency>
    <dependency>
        <groupId>commons-io</groupId>
        <artifactId>commons-io</artifactId>
        <version>2.6</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpmime</artifactId>
        <version>4.5.6</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.9.7</version>
    </dependency>
    <dependency>
        <groupId>org.apache.velocity</groupId>
        <artifactId>velocity-engine-core</artifactId>
        <version>2.0</version>
    </dependency>
</dependencies>

maven本地仓库引入包（放到~/.m2目录下即可）

下载地址

在项目中直接添加依赖

<dependency>
    <groupId>com.flyfish.oauth</groupId>
    <artifactId>oauth-client</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

纯java项目，jar包下载

下载地址: lib.zip

三、开始配置

本教程以Spring MVC 4为例，基于@Bean注解的配置方式来描述如何配置：

首先我们注入OAuthClient，新增一个Spring的Configuration Bean

BeanConfiguration.java

package com.flyfish.account.config;

import com.flyfish.oauth.client.DefaultOAuth2SsoClient;
import com.flyfish.oauth.client.OAuth2SsoClient;
import com.flyfish.oauth.configuration.OAuth2SsoProperties;
import com.flyfish.oauth.configuration.OAuth2SsoUserService;
import com.flyfish.oauth.configuration.SSOSessionConverter;
import com.flyfish.oauth.domain.SSOUserInfo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.servlet.http.HttpSession;

@Configuration
public class BeanConfiguration {

    /**
     * 构建Bean
     * @return 结果
     * 可选附带的参数不需要附带，默认值能够满足业务场景
     * 所有参数都可以以http://附带域名来重置默认url行为（serverUrl和localUrl）
     */
    @Bean
    public OAuth2SsoClient ssoClient() {
        // 构造默认客户端
        DefaultOAuth2SsoClient client = new DefaultOAuth2SsoClient();

        // 构造配置
        OAuth2SsoProperties properties = new OAuth2SsoProperties();
        // 你的clientId
        properties.setClientId("test");
        // 你的clientSecret
        properties.setClientSecret("123456");
        // 你的地址
        properties.setLocalUrl("http://demo.flyfish.group");
        // 认证服务地址
        properties.setServerUrl("http://accounts.flyfish.group");
        // 可选附带，登录回调地址，如果此处配置了回调地址，将替换默认的地址
        properties.setRedirectUri("/oauth/callback");
        // 可选附带，传入的获取token的地址
        properties.setAccessTokenUri("/api/login/oauth/token");
        // 可选附带，传入的授权页（登录页URI）
        properties.setUserAuthorizationUri("/login");
        // 可选附带，检查token有效性的URI
        properties.setCheckAccessTokenUri("/login/oauth/check_token");
        // 可选附带，传入获取用户信息的URI
        properties.setUserInfoUri("/accounts/current");
        // 可选附带，默认client，认证作用域
        properties.setScope("client");
        // 赋值
        client.setProperties(properties);

        // 配置会话转换器
        client.setSessionConverter(new DefaultSessionConvertor());
        // 配置用户信息转换器
        client.setUserInfoService(new DefaultUserService());
        // 初始化，必须执行
        client.init();
        // 返回
        return client;
    }
}

当然，上面的例子也可以用XML很直观的注入，看大家自己喜欢哪种方式了！

关于用户信息转换器OAuth2SsoUserService：这是返回用户数据的入口，很重要。目前只支持返回到Session处理接口。
关于会话转换器：会话转换器，第一个参数是当前session，第二个是用户信息转换器转换后的用户数据，数据类型为系统自己的类型，请重载后实现！
在这个方法里可以往session写用户数据，页面就能取到了！

2018-12-1更新： 为了方便大家对接，在新的sdk中提供了默认实现，具体源码：
DefaultSessionConverter.java
DefaultUserService.java
Javadoc也同步更新了，请持续关注

在业务中添加同步逻辑

大家在使用认证中心和数据共享开始，往往想要同步数据，同步数据的方式比较简单，这里提供两种方案：
- Quartz 定时同步数据，每次同步一部分。
- 初始同步全量数据, 之后在数据中心维护
同步数据的方式很多，大家自由选择。关于同步接口，有详细的接口文档，猛戳：

接口文档地址
 同步相关javadoc

关于调用方式，建议使用Apache HttpClient的最新版。调用时需要鉴权，鉴权方式是
~~增加Authorization的Header~~
```
Authorization: Basic YnJvd3Nlcjo=
```
~~注意：这里Basic后面有一个空格，后面的字符串是clientId:clientSecret进行Base64编码的结果，上面的例子是browser:空密码的例子~~

~~具体HttpClient使用方式大家自己百度吧，我就不细说了。~~

上述鉴权方式已经废弃：
【新】SDK封装了实用上下文提供必需数据的获取，参照:
https://www.flyfish.group/javadoc/com/flyfish/oauth/filter/OAuthContext.html

请使用单点登录SDK获取到accessToken（使用上述工具类可以直接获取）后调用同步接口，同步接口请查看接口文档。

简单示例，以SDK自带的RestClient为例：

import com.flyfish.oauth.filter.OAuthContext;
import com.flyfish.oauth.client.RestClient;
import com.flyfish.oauth.configuration.OAuth2SsoProperties;
import com.flyfish.oauth.domain.OAuthSSOToken;
import com.flyfish.oauth.domain.SSOUserInfo;
import com.flyfish.oauth.utils.JacksonUtil;

public class SyncTest {
    public void requestWithCredentials() {
         // 获取accessToken
         String accessToken = OAuthContext.clientToken().getAccessToken();
         // 发起请求
         String result = RestClient.create()
                        .post()
                        .url(OAuthContext.getProperties().getServerUrl() + "/roles/sync")
                        .addHeader(AUTH_HEADER, OAuthSSOToken.BEARER_TYPE + " " + accessToken)
                        .build()
                        .executeForString();
         // SyncResult是自定义返回值类，返回类型请参照接口文档
         SyncResult result = JacksonUtil.fromJson(result, SyncResult.class);
         System.out.println("result is:" + result.getMsg());
    }
}

更多的自定义操作

大家可以有选择的继承SSOClient，实现自己的业务逻辑，也可以重写AuthenticationServlet。更多方式我们群里交流。

完毕，请尽情享用

Thanks! 大家空余时间多关注我的博客，我会提供更多干货。刚搭建的博客，基于Hexo。

MIT
本文链接：http://blog.flyfish.group/2018/11/29/quick-start/

准备工作

一、下载必备物料

二、准备开发工作

三、开始配置

2018-12-1更新： 为了方便大家对接，在新的sdk中提供了默认实现，具体源码：

DefaultSessionConverter.java

DefaultUserService.java

Javadoc也同步更新了，请持续关注

完毕，请尽情享用

2018-12-1更新：为了方便大家对接，在新的sdk中提供了默认实现，具体源码：