¶ 标准协议 API

更新时间: 2024-07-24 09:31:53

¶ 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