# 目录


# 1. 申请应用

访问飞书开放平台 https://open.feishu.cn/ (opens new window) 并登录

进入“开发者后台”页面,选择“创建企业自建应用”

创建完成后,进入应用详情页,可以在首页看到 App IdApp Secret

从右侧菜单中,进入“安全设置”页面,配置回调地址

从右侧菜单中,进入“权限管理”页面,配置应用权限

注:

  • 如需获取用户邮箱,请添加“获取用户邮箱”权限
  • 如需获取用户手机号,请添加“获取用户手机号”权限
  • 其他必选如“获取用户 userid”、“获取用户统一ID”、“获取用户基本信息”
  • 其他权限,请开发者根据自身要求添加

copy以下三个信息:App IDApp Secret重定向 URL

重要提示

“应用密钥”可保护你应用程序的安全,因此请确保其不会泄露!也不要与任何人共享你的“应用密钥”!!!

# 2. 集成JustAuth

# 2.1 引入依赖

<dependency>
  <groupId>me.zhyd.oauth</groupId>
  <artifactId>JustAuth</artifactId>
  <version>${latest.version}</version>
</dependency>
1
2
3
4
5

${latest.version}表示当前最新的版本,可以在这儿 (opens new window)获取最新的版本信息。

# 2.2 创建Request

AuthRequest authRequest = new AuthFeishuRequest(AuthConfig.builder()
                .clientId("App ID")
                .clientSecret("App Secret")
                .redirectUri("重定向 URL")
                .build());
1
2
3
4
5

# 2.3 生成授权地址

我们可以直接使用以下方式生成第三方平台的授权链接:

String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
1

这个链接我们可以直接后台重定向跳转,也可以返回到前端后,前端控制跳转。前端控制的好处就是,可以将第三方的授权页嵌入到iframe中,适配网站设计。

# 2.4 以上完整代码如下

import me.zhyd.oauth.config.AuthConfig;
import me.zhyd.oauth.request.AuthFeishuRequest;
import me.zhyd.oauth.model.AuthCallback;
import me.zhyd.oauth.request.AuthRequest;
import me.zhyd.oauth.utils.AuthStateUtils;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;


@RestController
@RequestMapping("/oauth")
public class RestAuthController {

    @RequestMapping("/render")
    public void renderAuth(HttpServletResponse response) throws IOException {
        AuthRequest authRequest = getAuthRequest();
        response.sendRedirect(authRequest.authorize(AuthStateUtils.createState()));
    }

    @RequestMapping("/callback")
    public Object login(AuthCallback callback) {
        AuthRequest authRequest = getAuthRequest();
        return authRequest.login(callback);
    }

    private AuthRequest getAuthRequest() {
        return new AuthFeishuRequest(AuthConfig.builder()
                .clientId("App ID")
                .clientSecret("App Secret")
                .redirectUri("重定向 URL")
                .build());
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

授权链接访问成功后会看到以下页面内容:

点击同意授权即可完成飞书的 oauth 登录。

# 3. 关于 App Access Token

飞书平台,code 换 token 时需要传递 app_access_token,详情见获取登录用户身份 (opens new window)

关于企业自建应用的 app_access_token 获取方式,见获取 app_access_token(企业自建应用) (opens new window)

app_access_token 有效期为 2 小时,在此期间调用该接口 app_access_token 不会改变。当 app_access_token 有效期小于 30 分的时候,再次请求获取 app_access_token 的时候,会生成一个新的 app_access_token,与此同时老的 app_access_token 依然有效。

所以,JA 为了降低不必要的重复 http 请求,会对以获取到的 app_access_token 进行缓存,缓存时间为获取 app_access_token(企业自建应用) (opens new window)接口返回的 expire

注意

JA 默认缓存是存到 Map 中的(本地内存),如果开发者的服务涉及到集群应用,如果不修改缓存实现,可能会出现以下问题异常相关 - illegal-state-xx,除此问题外,还会导致几乎每次(视集群内服务数)获取 access token 时,都会重新请求获取 app_access_token(企业自建应用) (opens new window)接口

自定义缓存请参考:自定义 state 缓存

# 4. 推荐

官方推荐使用 JustAuth-demo (opens new window) 示例项目进行测试。

使用步骤:

  1. clone: https://github.com/justauth/JustAuth-demo.git (opens new window)
  2. 将上面申请的应用信息填入到RestAuthController#getAuthRequest方法的对应位置中:
  3. 启动项目,访问 http://localhost:8443 (opens new window)
  4. 选择对应的平台进行授权登录
  5. 登录完成后,可以访问http://localhost:8443/users (opens new window)查看已授权的用户

注意

  1. 如果直接使用 JustAuth-demo 项目进行测试,那么在配置测试应用的“回调地址”时要严格按照以下格式配置:http://localhost:8443/oauth/callback/{平台名}
  2. 平台名参考 JustAuthPlatformInfo 枚举类 names
上次更新: 1/7/2021, 12:40:15 PM