移动应用聆客登录

移动应用Link登录是基于【OAuth2.0 协议标准】构建的授权登录系统。在进行Link OAuth2.0授权登录之前,在 开发者平台注册应用 并获得相应的ClientIdClientSecret

需要注意:

[1] 移动应用上Link登录只提供原生的登录方式,需要用户安装Link客户端才能配合使用。

[2] 建议开发者接入Link登录时,先检测用户手机是否已安装Link客户端(使用sdk中isLinkInstalled函数 ),对未安装的用户隐藏登录按钮,请引导用户下载安装Link客户端。

授权流程说明

[1] 第三方发起Link授权登录请求,用户允许授权第三方应用后,Link回拉起第三方应用并且带上授权码;

[2] 通过授权码参数加上ClientIdClientSecret等,通过API换取access_token等认证信息;

[3] 通过access_token进行接口调用(header中带上),获取用户基本数据或帮助用户实现基本操作。

授权协议整体过程:

授权登录实现

第一步,请求授权码(AuthCode)

Android平台应用授权接入代码示例:(请参考Android接入指南)

//向Link发起授权登录请求
AuthReq req = new AuthReq();
req.setLinkAppId("com.bingosoft.linkonline");
app.ilinkapi.sendReq(this, req);

iOS平台应用授权接入代码示例:(请参考iOS接入指南)

AuthReq* req = [AuthReq new];
req.linkAppId = @"com.bingosoft.linkonline";
[LinkApi sendReq:req];

经过这个步骤可以拉起Link授权登录界面:

返回说明

用户点击授权后,Link客户端会被拉起,跳转至授权界面,用户在该界面点击允许或取消,SDK通过onResp返回数据给调用方。返回的对象是AuthResp类型。

返回值 描述
resultCode 200(授权成功),100(取消授权),101(加载客户端失败),102(客户端不可用),103(获取授权码失败),140(不合法的参数)
error 错误概述
errorDescription 错误明细
authCode 授权码,用于交换access_token,将 BaseResp 强制转成 AuthResp 即可获取authCode

第二步,通过code获取access_token

获取第一步的code之后,使用SDK内置的SSOClient来获取认证信息Authentication,包含了AccessToken。

Android平台调用代码如下:

public void onResp(BaseResp resp)中实现如下:

@Override
public void onResp(BaseResp resp) {
    //授权系统客户端对象
    SSOClient ssoClient = new SSOClient("authServerUrl", "clientId", "clientSecret");
    //获取授权码
    String authCode = ((AuthResp) resp).authCode;
    //授权码凭证
    AuthorizationCodeCredentials credentials = new AuthorizationCodeCredentials(authCode);
    ssoClient.doLogin(credentials, new SSOLoginListener() {
        @Override
        public void onSuccess(Authentication auth) {
             //获取认证信息成功             
        }
        @Override
        public void onError(SingleSignOnException ex) {
             //获取认证信息失败
        }
    });
}

iOS平台调用代码如下:

-(void) onResp:(BaseResp *)resp中实现如下:

- (void) onResp:(BaseResp *)resp {
    if ([resp isKindOfClass:[AuthResp class]]) {
        AuthResp* resp_ = (AuthResp*)resp;
        if (resp.resultCode == RespCodeOK) {
            //授权码凭证
            BGSSOAuthorizationCodeCredential* credential = [BGSSOAuthorizationCodeCredential new];
            credential.code = resp_.authCode;

            //SSOClient
            BGSSOClient* client = [BGSSOClient sharedInstance];
            client.ignoreCert = YES;
            client.clientId = SSOV3_CLIENT_ID;
            client.clientSecret = SSOV3_CLIENT_SECRET;
            client.endpointUrl = SSOV3_URL;

            [client authorize:credential completionHandler:^(BGSSOAuthentication * _Nullable auth, NSError * _Nullable error) {
                if (auth) {
                      //获得 BGSSOAuthentication 对象
                      //auth.accessToken.tokenString
                }
            }];
        } else if (resp.resultCode == RespCodeUserCancel) {
                //用户取消
        } else {
                //其他错误
        }
    }
}

返回说明

获取认证信息成功,返回Authentication对象和BGSSOAuthentication对象:

返回值 描述
uid 用户id
eCode 用户所在企业编码
status 用户状态:0 禁用 1启用
accessToken 授权令牌
refreshToken 用于刷新accessToken的令牌

获取认真信息失败,Android平台返回SingleSignOnException对象:

返回值 描述
error 错误概要信息
description 错误详细信息
errorCode 错误编码【参考 Oauth2 错误响应编码】

获取认真信息失败,iOS平台返回NSError对象:

返回值 描述
_domain 错误域(NSInteger)
_code 错误标示(NSString *)
_userInfo 错误详细信息(NSDictionary *)

第三步,通过access_token调用接口

获取access_token后,进行接口调用,有个前提access_token有效且未超时。应对无效或者超时的情况,请看下一步【刷新access_token有效期】。

对于网络请求接口获取数据,请在请求头(header)中带上access_token,参考:

Android平台:

headers.put("Authorization", "Bearer g3MonUZtNHkdmzicIlibx6iaFqAc56vx");

iOS平台:(如AFNetworking):

[manager.requestSerializer setValue:@"Bearer g3MonUZtNHkdmzicIlibx6iaFqAc56vx" forHTTPHeaderField:@"Authorization"];

第四步,刷新access_token

access_token已过期,那么进行refresh_token会获取一个新的access_token和新的超时时间。使用SDK内置的SSOClient来进行获取, 其中ssoClient是第一次交换access_token的时候使用的对象,会在内存中保留RefreshToken,以供下次刷新access_token使用。

Android平台调用代码如下:

//令牌刷新凭证
RefreshTokenCredentials rtc = new RefreshTokenCredentials(ssoClient.getRefreshToken());
ssoClient.doLogin(credentials, new SSOLoginListener() {
    @Override
    public void onSuccess(Authentication auth) {
         //获取认证信息成功             
    }
    @Override
    public void onError(SingleSignOnException ex) {
         //获取认证信息失败
    }
});

iOS平台调用代码如下:

BGSSORefreshTokenCredential* credential = [BGSSORefreshTokenCredential new];
credential.refreshToken=[BGSSOClient sharedInstance].lastAuthentication;
[[BGSSOClient sharedInstance] authorize:credential completionHandler:^(BGSSOAuthentication * _Nullable auth, NSError * _Nullable error) {
    if (auth) {
        ...           
    }          
}];

F.A.Q

1. 什么是授权码(AuthCode)?

答:第三方需要获取access_token,必须得到这个授权码(authCode),默认有效时间为5分钟,一个授权码只能成功换取一次access_token。授权码的临时性保障了Link登录的安全性。

2. 什么access_token ?

答:access_token是调用授权关系接口的调用凭证,默认有效时间为10个小时。过期后需要重新刷新获得最新的access_token

上一篇:IOS接入指南 下一篇:Web应用