提供基于iotToken的用户身份认证方案,通过和账号及用户SDK、API通道SDK的集成,完成用户身份凭证的生成和管理,以及发起API请求的用户身份的鉴权。

依赖 SDK 概述
API通道 提供API通道能力

初始化

初始化Mobile长连接通道SDK前,请先初始化API通道SDK,请参见API 通道 - 初始化

  • SDK(com.aliyun.iot.aep.sdk:iot-credential)版本小于0.0.1.7,请使用如下方式初始化
    //其中loginAdapter为OLoginAdapter,务必注意在调用之前,保证loginAdapter已经完成初始化(即完成了用户和账号SDK的初始化)
    IoTCredentialManageImpl.init(loginAdapter, appkey);
  • SDK(com.aliyun.iot.aep.sdk:iot-credential)版本为0.0.1.7以及以上,请使用如下方式初始化
    //务必注意在调用之前,保证完成了用户和账号SDK的初始化
    IoTCredentialManageImpl.init(appKey);

使用方式

当使用API通道执行某些需要IoT身份鉴权的业务请求时,统一身份认证SDK为API通道提供了一个自动完成请求认证信息填充的模块IoTCredentialProviderImpl,使用方式如下。

  • 初始化IoTCredentialProviderImpl模块,代码如下
    IoTAuthProvider provider = new IoTCredentialProviderImpl(IoTCredentialManageImpl.getInstance(app));
    IoTAPIClientImpl.getInstance().registerIoTAuthProvider("iotAuth", provider);
  • 构建需要鉴权的业务请求IoTRequest

    构建IoTRequest时需要增加AuthType参数(参数填写注册IoTCredentialHook时,注册的key,本例为“iotAuth”) ,代码如下所示。

    IoTRequest request = new IoTRequestBuilder()
        .setPath("path")
        .setApiVersion("1.0.4")
        .addParam("request", paramMap)
        .setAuthType("iotAuth")
        .build();
    					

    在 API 通道内部会触发 IoTCredentialProviderImpl ,自动刷新并填充认证信息,完成正常的业务请求。

  • 处理认证失败

    目前服务端逻辑不支持同一个账号多端登录,如果一个账号在多个设备登录,那么只有最后一个登录的账号才可以正常访问IoT服务,其他账号则会返回认证错误,SDK提供一个接口,可以方便开发者随时监听这个错误,接口如下所示。

    IoTCredentialManageImpl.getInstance(app).setIotCredentialListenerList(IoTTokenInvalidListener listener)

    其中IoTTokenInvalidListener定义如下。

    public interface IoTTokenInvalidListener {
        void onIoTTokenInvalid();
    }
    说明 这个API全局只能设置一次,推荐在初始化完成之后,调用这个API,监听IoTToken失效的情况,当onIotTokenInvalid被触发时,需要提示用户当前会话已失效,需要重新登录。

混淆配置

-keep public class com.aliyun.iot.aep.sdk.credential** {
    public <methods>;
    public <fields>;
}

获取/刷新用户凭证

获取用户认证数据代码如下,如果结果返回NULL,可以调用异步刷新接口重新获取。

IoTCredentialManage ioTCredentialManage = IoTCredentialManageImpl.getInstance(app);
if(ioTCredentialManage!=null){
    ioTCredentialManage.getIoTCredential();
}

其中IotCredentialData常用字段解释如下。

public class IoTCredentialData {
    /**
     * 临时令牌,对请求做身份校验
     */
    public String iotToken;

    /**
     * iotToken 创建时间,标准Unix时间戳
     */
    public long iotTokenCreateTime;

    /**
     * iotToken失效时间 -- 时间与云端同步,单位为秒
     */
    public long iotTokenExpireTime;

    /**
     * refreshToken ,用于刷新 iotToken
     */
    public String refreshToken;

    /**
     * refreshToken 创建时间,标准Unix时间戳
     */
    public long refreshTokenCreateTime;

    /**
     * refreshToken失效时间 -- 时间与云端同步,单位为秒
     */
    public long refreshTokenExpireTime;

    /**
     * iot 用户唯一身份标识 identityId
     */
    public String identity;
}

刷新用户认证数据代码如下。

IoTCredentialManage ioTCredentialManage = IoTCredentialManageImpl.getInstance(app);
if (ioTCredentialManage != null) {
    ioTCredentialManage.asyncRefreshIoTCredential(new IoTCredentialListener() {
        @Override        
        public void onRefreshIoTCredentialSuccess(IoTCredentialData ioTCredentialData) {
            Log.i(TAG, "refresh IoTCredentailData success :" + ioTCredentialData.toString());
        }

        @Override
        public void onRefreshIoTCredentialFailed(IoTCredentialManageError ioTCredentialManageError) {
            Log.i(TAG, "refresh IoTCredentailData failed ");
            if (ioTCredentialManageError != null) {
                Log.i(TAG, "error code is:" + ioTCredentialManageError.errorCode);
            }
        }
    });
}

常见错误码含义

错误码 含义
0 账号未登录
1 账号类型错误
2 账号AuthCode无效(即Session失效)
3 refreshToken过期,需要重新登录
4 服务器相应的报文格式错误(请将request和response提工单)
5 账号AuthCode校验错误
-1 其他错误,请查看APIClient返回的具体业务错误或者通过detail字段查看