v1.15.7-x 版本主要解决的问题是增加自定义 scope 的功能，目前已迭代到了 v1.15.7-beta-3 版本（尚处于公测版，如有问题，请随时联系！）。

为什么要自定义 scope？

熟悉 OAuth 的朋友可能非常清楚，scope 参数在 oauth 流程中也非常重要，因为它表示了当前授权的 access_token 所具有的权限。

Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted. —— 以上内容节选自oauth.net《OAuth Scopes》

简单翻译版 “Scope” 是 OAuth 2.0 中的一种权限机制，用于限制 OAuth 应用对用户帐户的访问范围。应用程序可以请求一个或多个 Scope，然后这些信息将在用户授权页中呈现给用户，而向应用程序发出的访问令牌（access token）将被限制在授予的 scope 内（即所有超出当前授权 scope 的用户资源都将不可见）。

在 JA 的 1.15.7 以前的版本，所获取到的 access_token 仅限于访问用户的基本的信息，对于用户的其他权限信息则无权访问，为了解决这一问题，使 JA 的应用场景和功能更加完善，所以开始了 v1.15.7 版本的迭代。

此次迭代记录

v1.15.7-beta.1

• 新增
  • 以下平台支持自定义 Scope 参数：百度、coding、Facebook、gitee、github、gitlab、google、华为、京东·宙斯、酷家乐、领英、微软、小米、Pinterest、QQ、人人网、StackOverflow、微博、微信公众平台
    添加 PR 和 ISSUE 规范和 CODE_OF_CONDUCT 文档
• 合并
  • 合并 Gitee PR#19，修复通过google登录一次后，重新用google登录无法切换谷歌账户的问题。

v1.15.7-beta.3

• 解决微信授权登录中 scope 参数被忽略的问题
• 改进微软平台的授权 scope 流程

注：v1.15.7-beta-2 版本由于发布异常，已不可用，如果有正在使用 v1.15.7-beta-2 版本的并且一直提示依赖出错的，请升级到 v1.15.7-beta-3.

如何使用？

关于 scope 相关的注解说明

这儿需注意，并不是每个平台都支持自定义 scope，平台是否支持需要视第三方的 API 能力。所有支持自定义的平台如下：
百度、Coding、FaceBook、Gitee、Github、Gitlab、Google、华为、京东、酷家乐、领英、微软、小米、Pinterest、QQ、人人、Stackoverflow、微信公众平台和微博。
所有 scope 参数都在 me.zhyd.oauth.enums.scope 包下。

以 me.zhyd.oauth.enums.scope.AuthGoogleScope 为例，每个平台的 scope 注解都支持三个参数：

// 具体的 scope 值
private String scope;
// scope 的用途说明
private String description;
// 是否为平台默认
private boolean isDefault;

所有被标为 isDefault 的 scope 都表示为该平台默认的 scope 值，即如果不传 scope 的情况下，默认使用被标注为isDefault的scope。

如 Google 平台默认的 scope 为三个：

USER_OPENID("openid", "Associate you with your personal info on Google", true),
USER_EMAIL("email", "View your email address", true),
USER_PROFILE("profile", "View your basic profile info", true),

另外， 针对 Google 平台， JA 还根据具体的用户权限，封装了特定的 scope，如下：

详细说明请参考 JA 的 API 文档：https://apidoc.gitee.com/yadong.zhang/JustAuth/me/zhyd/oauth/enums/scope/AuthGoogleScope.html

开发者可以视具体情况进行选择使用。

使用 scope 参数

本文将以 Google 平台演示 scope 的作用，关于 Google 平台的接入方法，请参考：Google登录。

在使用自定义 scope 时，只需要在原来使用方法的基础上做如下调整：

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(CollectionUtil.addAllIfNotContains(AuthGoogleScope.getPeopleScopes(), AuthGoogleScope.getGmailScopes()))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

scope参数为 List<String> 类型，开发者可以自己传入任意有效的 scope 值，也可以使用 JA 提供的相关工具方法。JA 提供了工具类 me.zhyd.oauth.utils.AuthScopeUtils 进行支持，该类提供如下方法：

// 获取 AuthScope 数组中所有的被标记为 default 的 scope
static List<String>	getDefaultScopes(AuthScope[] scopes)

// 从 AuthScope 数组中获取实际的 scope 字符串
static List<String>	getScopes(AuthScope... scopes)

使用方法一: 使用默认 scope

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(AuthScopeUtils.getDefaultScopes(AuthGoogleScope.values()))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

使用方法二: 使用指定的 scope

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(AuthScopeUtils.getScopes(AuthGoogleScope.USER_EMAIL, AuthGoogleScope.USER_PROFILE, AuthGoogleScope.USER_OPENID))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

使用方法三: 使用指定的 scope

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(Arrays.asList(
        AuthGoogleScope.USER_EMAIL.getScope(),
        AuthGoogleScope.USER_PROFILE.getScope(),
        AuthGoogleScope.USER_OPENID.getScope()
    ))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

使用方法四: 使用指定的 scope

此方法变种于方法三

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(Arrays.asList("openid", "email", "profile"))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

使用方法五: 组合使用

此方法变种于方法三

authRequest = new AuthGoogleRequest(AuthConfig.builder()
    .clientId("xxx")
    .clientSecret("xxx")
    .redirectUri("http://localhost:8443/oauth/callback/google")
    .scopes(CollectionUtil.addAllIfNotContains(AuthGoogleScope.getPeopleScopes(), AuthGoogleScope.getGmailScopes()))
    // 针对国外平台配置代理
    .httpConfig(HttpConfig.builder()
            .timeout(15000)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10080)))
            .build())
    .build());

如上所述，scope参数为 List<String> 类型，开发者可以自己传入任意有效的 scope 值。

使用了自定义 scope 后的授权流程

其他平台的授权页面

微软：

Pinterest：

参考资料

• OAuth Scopes
• JustAuth 集成的平台中，允许自定义 scope 的平台文档
  • Baidu: http://developer.baidu.com/wiki/index.php?title=docs/oauth#.E6.8E.88.E6.9D.83.E6.9D.83.E9.99.90.E5.88.97.E8.A1.A8
  • Github: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
  • Dingtalk: https://ding-doc.dingtalk.com/doc#/serverapi2/kymkv6
  • Weibo: http://developer.baidu.com/wiki/index.php?title=docs/oauth/list
  • Coding: https://help.coding.net/docs/project/open/oauth.html#scope-参数
  • QQ: https://wiki.connect.qq.com/api列表
  • 微信公众平台: https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
  • Google: https://developers.google.com/identity/protocols/oauth2/scopes
  • Facebook: https://developers.facebook.com/docs/facebook-login/permissions/
  • Microsoft: https://docs.microsoft.com/zh-cn/graph/permissions-reference
  • 人人: http://open.renren.com/wiki/权限列表
  • stack overflow: https://api.stackexchange.com/docs/authentication#scope
  • 华为: https://developer.huawei.com/consumer/cn/doc/30101
    • 云空间服务：https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides-V5/server-dev-0000001050039664-V5
  • 企业微信: https://open.work.weixin.qq.com/api/doc/90000/90135/91022
  • 酷家乐: https://open.kujiale.com/open/apps/2/docs?doc_id=95#Step1：获取Authorization Code
  • Pinterest: https://developers.pinterest.com/docs/api/overview/?#scopes
  • 领英
    • Migrating From Default Permission Scopes：https://docs.microsoft.com/en-us/linkedin/shared/references/migrations/default-scopes-migration
    • share-api: https://docs.microsoft.com/en-us/linkedin/marketing/integrations/community-management/shares/share-api