Authing 文档文档
快速开始
概念
使用指南
开发集成 V2 arrow
  • V2 文档
  • V3 文档
应用集成
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
快速开始
概念
使用指南
开发集成 V2 arrow
  • V2 文档
  • V3 文档
应用集成
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
旧版
开发集成
  • JavaScript SDK 索引
  • 单点登录(SSO)
  • 登录组件 (Guard)

  • JavaScript / Node.js

  • Java / Kotlin

  • Python

  • C#

  • PHP

  • Go

  • Ruby
  • Delphi
  • Android

    • 快速开始
    • 托管页
    • 超组件

    • APIs

      • 核心认证 API
      • 标准协议 API
      • 多因素认证 API
      • 扫码认证 API
    • 第三方身份源

    • 典型场景

    • 私有化部署
    • Android Guard 更新日志
    • 返回码对照表
  • iOS

  • Flutter

  • 微信小程序
  • 微信网页授权
  • React Native
  • 框架集成

  • Radius
  • 错误代码

¶ 标准协议 API

更新时间: 2022-12-06 21:48:37
编辑

¶ OIDC

OpenID Connect 简称 OIDC (opens new window),是 OAuth 2.0 的一个扩展,主要增加了语义化的用户信息字段。

¶ 初始化

OIDCClient 会自动获取控制台默认回调,如需要自定义 scope, redirect_uri 等参数,可创建 AuthRequest 对象,重新给 scope 或 redirect_uri 属性赋值。

¶ 生成 OIDC 协议的用户登录链接

生成登录 URL,传给 WebView 加载

public String buildAuthorizeUrl(Callback<String> callback)

参数

  • callback 回调

示例

AuthRequest authRequest = new AuthRequest();

new OIDCClient(authRequest).buildAuthorizeUrl(new Callback<String>() {
  	@Override
  	public void call(boolean ok, String data) {
    	myWebView.loadUrl(data);
  	}
});

设置 scope 参数

默认值为 openid profile email phone username address offline_access roles extended_fields

authRequest.setScope(String scope)

设置回调参数

SDK 会自动获取控制台默认回调。如果在控制台修改了回调,则需要设置 authRequest 回调地址。

authRequest.setRedirectURL(String redirectURL)

¶ Code 换 Token

通过 OIDC 授权码认证,返回的 UserInfo 里面包含 access token 和 id token。如果登录 url 的 scope 里面包含 offline_access,则该接口也会返回 refresh token

public void authByCode(String code, AuthRequest authRequest, @NotNull AuthCallback<UserInfo> callback)

参数

  • code OIDC 授权码。通过 webview 的回调获取,每个 Code 只能使用一次。
  • authRequest 请求参数。

示例

myWebView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
        String url = request.getUrl().toString();
        if (url.startsWith(authRequest.getRedirectURL())) {
            try {
                String authCode = Util.getAuthCode(url);
                if (authCode != null) {
                    new OIDCClient().authByCode(authCode, authRequest, (code, message, userInfo) -> {
                        // got user info
                    });
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
            return true;
        }
        return false;
    }
});

¶ 获取用户信息

通过 access token 获取用户信息。返回的 userInfo 对像和参数传入的是同一个 userInfo 对象,此接口只返回协议相关用户信息字段。

public void getUserInfoByAccessToken(UserInfo userInfo, @NotNull AuthCallback<UserInfo> callback)

参数

  • userInfo 包含 access token 的用户信息
  • callback 函数回调。通过此回调获取用户信息

示例

new OIDCClient().getUserInfoByAccessToken(userInfo, (code, message, data)->{
    if (code == 200) {
        // data 为更新了用户信息的 UserInfo 对象,和参数是同一个对象
    }
});

¶ 通过 Refresh Token 获取新的 Access Token 和 ID Token

access token 的有效期通常较短,比如几个小时或者 1 天。当 access token 过期后,App 不能频繁的弹出登录界面让用户认证,那样体验比较糟糕。所以通常的做法是通过代码,用一个有效期比较长的 refresh token 去刷新 access token,从而保持登录状态。只有当 refresh token 过期才弹出登录界面。

public void getNewAccessTokenByRefreshToken(String refreshToken, @NotNull AuthCallback<UserInfo> callback)

参数

  • refreshToken 刷新凭证。注意登录 URL 里面的参数配置,请参考 “生成 OIDC 协议的用户登录链接”
  • callback 函数回调。通过此回调获取用户信息

示例

new OIDCClient().getNewAccessTokenByRefreshToken(rt, (code, message, data)->{
    if (code == 200) {
        Log.d(TAG, "new at:" + data.getAccessToken());
        Log.d(TAG, "new id token:" + data.getIdToken());
        Log.d(TAG, "new rt:" + data.getRefreshToken());
    }
});

注意,每次调用会得到新的 refresh token


¶ 获取 Access Token、ID Token 和 Refresh Token

¶ 邮箱注册

使用邮箱注册帐号,邮箱不区分大小写且用户池内唯一。此接口不要求用户对邮箱进行验证,用户注册之后 emailVerified 字段会为 false 。

public void registerByEmail(String email, String password, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • email 邮箱
  • password 明文密码
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().registerByEmail("test@example.com", "xxxxxx", context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2003 非法邮箱地址
  • 2026 邮箱已注册

¶ 邮箱验证码注册

使用邮箱验证码注册帐号,邮箱不区分大小写且用户池内唯一。此接口不要求用户对邮箱进行验证,用户注册之后 emailVerified 字段会为 false,需要先调用 发送邮件 接口(场景值为 VERIFY_CODE)。

public void registerByEmailCode(String email, String vCode, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • email 邮箱
  • vCode 验证码
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().registerByEmailCode("test@example.com", "1234", context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2003 非法邮箱地址
  • 2026 邮箱已注册

¶ 短信验证码注册

通过手机号和短信验证码注册帐号。手机号需要在用户池内唯一。调用此接口之前,需要先调用 发送短信验证码 接口以获取短信验证码

public void registerByPhoneCode(String phoneCountryCode, String phone, String code, String password, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • phoneCountryCode 电话国家码。可以为空,为空时默认为 +86
  • phone 手机号
  • code 短信验证码
  • password 明文密码,如果没有可传 “” 或者 null
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().registerByPhoneCode("+86", "188xxxx8888", "1234", "xxxxxx", context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2001 验证码错误
  • 2026 手机号已注册

¶ 自定义字段注册

使用自定义字段注册的账号,可直接使用账号密码登录。

public static void registerByExtendField(String fieldName, String account, String password, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • fieldName 字段名称
  • account 账号
  • password 明文密码,如果没有可传 “” 或者 null
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().registerByExtendField("extendId", "188xxxx8888", "xxxxxx", context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2026 用户名已存在

¶ 帐号密码登录

public void loginByAccount(String account, String password, boolean autoRegister, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • account 可以是手机号 / 邮箱 / 用户名
  • password 明文密码
  • autoRegister 是否自动注册。如果检测到用户不存在,会根据登录账密自动创建一个账号。
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().loginByAccount("test", "xxxxxx", false, context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2333 帐号或密码错误

¶ 邮箱验证码登录

通过邮箱验证码登录,需要先调用 发送邮件 接口(场景值为 VERIFY_CODE)。

public void loginByEmailCode(String email, String code, boolean autoRegister, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • email 邮箱
  • code 验证码
  • autoRegister 是否自动注册。如果检测到用户不存在,会根据登录账密自动创建一个账号。
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().loginByEmailCode("test@example.com", "1234", false, context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2001 验证码不正确

¶ 短信验证码登录

通过短信验证码登录,需要先调用 发送短信验证码 接口。

public void loginByPhoneCode(String phoneCountryCode, String phone, String code, boolean autoRegister, String context, @NotNull AuthCallback<UserInfo> callback)

参数

  • phoneCountryCode 电话国家码。可以为空,为空时默认为 +86
  • phone 手机号
  • code 短信验证码
  • autoRegister 是否自动注册。如果检测到用户不存在,会根据登录账密自动创建一个账号。
  • context 请求上下文,这里设置的 context 可以在 pipeline 的 context (opens new window) 中获取到,如不需要可传 null。

示例

JSONObject context = new JSONObject();
context.put("userId", "userId");
new OIDCClient().loginByPhoneCode("+86", "188xxxx8888", "1234", false, context.toString(), (code, message, userInfo)->{
    if (code == 200) {
        // userInfo:用户信息
    }
});

错误码

  • 2001 短信验证码不正确

上一篇: 核心认证 API 下一篇: 多因素认证 API
  • OIDC
  • 生成 OIDC 协议的用户登录链接
  • Code 换 Token
  • 获取用户信息
  • 通过 Refresh Token 获取新的 Access Token 和 ID Token
  • 获取 Access Token、ID Token 和 Refresh Token
  • 自定义字段注册

用户身份管理

集成第三方登录
手机号闪验 (opens new window)
通用登录表单组件
自定义认证流程

企业内部管理

单点登录
多因素认证
权限管理

开发者

开发文档
框架集成
博客 (opens new window)
GitHub (opens new window)
社区用户中心 (opens new window)

公司

400 888 2106
sales@authing.cn
北京市朝阳区北辰世纪中心 B 座 16 层(总)
成都市高新区天府五街 200 号 1 号楼 B 区 4 楼 406 室(分)

京ICP备19051205号

beian京公网安备 11010802035968号

© 北京蒸汽记忆科技有限公司