6.3 辅助认证

如果您的服务器针对用户只配置了用户名密码认证方式，则您的程序只需要调用用户名密码主认证接口，即可完成登录流程；如果您的服务器针对用户额外配置了增强认证方式，比如短信验证码认证、TOTP认证或Radius认证，那么需要调用其他增强认证接口来完成整个认证流程，并最终完成登录上线。

6.3.1 短信辅助认证

如果您的服务器设置了短信验证的增强认证方式，在完成上一次认证后，会要求继续进行短信辅助认证，（对应nextAuth == atrust_auth_type::ATRUST_AUTH_TYPE_SMS），

6.3.1.1 获取短信验证码

在进行短信认证之前，需要先调用获取短信验证码接口获取到验证码，需要注意的是，您在调用获取短信验证码接口前，已经能够从上一次认证接口的data参数中获取到用户配置的手机号码了。

接口定义

atrust_error_code ATRUST_API atrust_sync_fetch_sms(void **data);

参数和返回值说明

示例代码

void* data;
atrust_error_code ec = atrust_sync_fetch_sms(&data);
switch (ec) {
// 成功
case atrust_error_code::OK:
    // 短信验证码获取成功!
    break;
case atrust_error_code::AUTH_CHAIN_INCOMPLETE:
    // 认证链不完整，没有按照正确的顺序调用认证请求。
    return;
case atrust_error_code::OUT_PARAM_WRITE_ERROR:
    // 出参无法写入！
    return;
case atrust_error_code::SDPC_UNINITIALIZED:
    // 未调用初始化接口！
    return;
case atrust_error_code::ATRUST_CONNECT_ERROR:
    // aTrust客户端连接失败！如果重试任然失败，请检查aTrust客户端是否正确安装并运行。
    return;
case atrust_error_code::BAD_ALLOC_ERROR:
    // 内存分配失败。
    return;
// 未知的业务执行过程失败
default:
    // 接口调用失败！请在atrust_code.h中检查错误码，或尝试重试。错误码：ec
    return;
}

if (data != NULL) {
    atrust_auth_sms_data *smsdata = static_cast<atrust_auth_sms_data *>(data);
    // 提示信息，注意编码方式以防乱码
    // std::string tipsTranslate = Utf8ToGbk(smsdata->tips);
    // 重新获取等待时间：smsdata->interval

    // 释放内存
    atrust_free(data);
    data = nullptr;
}

6.3.1.2 短信验证码认证

在您获取到短信验证码之后，您可以使用短信验证码进行认证登录。短信认证的思路和流程与用户名密码主认证基本相同。事实上，短信验证接口的出参格式合用户名密码主认证是一样的，但返回的内容有所不同。

认证结束后，用户可能登录成功并上线，此时nextAuth等于等于ATRUST_AUTH_TYPE_OK（0）并且返回的错误码为OK（0）；也可能进入认证链的下一步增强认证；也有可能认证失败。

接口定义

atrust_error_code ATRUST_API
atrust_sync_login_by_sms(const char *code, atrust_auth_type *nextAuth, void **data);

参数和返回值说明

接口出参data说明

• 接口返回成功
  1. 接口返回成功则nextAuth出参非空，可根据nextAuth参数的取值，将data转换为对应的数据结构，其对应关系参考atrust_code.h。
  2. 如果配置了第三方认证服务器，则可以通过data出参中的authServerInfo字段获取aTrust服务端透传的认证服务器信息。
• 接口返回失败 接口返回失败 且 data非空的情况下，可以将data转换为通用的错误信息结构并从中获取错误码和具体的错误信息。其中错误码和接口返回值保持一致，错误信息与错误码一致。特殊地，如果是服务端返回的错误并且错误中包含动态信息，则可以从data中获取信息。

示例代码

atrust_auth_type nextAuth;
void *data;
atrust_error_code ec = atrust_sync_login_by_sms(m_sms, &nextAuth, &data);
switch (ec) {
// 成功
case atrust_error_code::OK:
    // 短信认证成功!
    break;
case atrust_error_code::PASSPORT_FAILED:
    // 认证失败，可能是验证码错误。
    atrust_free(data);
    return;
case atrust_error_code::AUTH_PARAM_EMPTY:
    // 输入的参数为空！
    atrust_free(data);
    return;
case atrust_error_code::OUT_PARAM_WRITE_ERROR:
    // 出参无法写入！
    atrust_free(data);
    return;
case atrust_error_code::SDPC_UNINITIALIZED:
    // 未调用初始化接口！
    atrust_free(data);
    return;
case atrust_error_code::ATRUST_CONNECT_ERROR:
    // aTrust客户端连接失败！如果重试任然失败，请检查aTrust客户端是否正确安装并运行。
    atrust_free(data);
    return;
case atrust_error_code::UNSOPPORTED_NEXT_AUTH_TYPE:
    // 服务端设置了不支持的增强认证方式。
    atrust_free(data);
    return;
// 未知的业务执行过程失败
default:
    // 接口调用失败！请在atrust_code.h中检查错误码，或尝试重试。错误码：ec
    if(data != NULL) {
        atrust_common_error_info* errInfo = static_cast<atrust_common_error_info*>(data);
        data->code;     // 获取错误码
        data->message;  // 获取错误信息
    }
    atrust_free(data);
    data = NULL;
    return;
}

switch (nextAuth) {
case atrust_auth_type::ATRUST_AUTH_TYPE_OK:
    // 登录成功！
    break;
// 一般不会出现双重辅助认证的情况
case atrust_auth_type::ATRUST_AUTH_TYPE_RADIUS:
    // 短信认证成功！下一步辅助认证：Radius
    break;
case atrust_auth_type::ATRUST_AUTH_TYPE_TOTP:
    // 短信认证成功！下一步辅助认证：TOTP令牌
    break;
default:
    // 短信认证成功，但服务器返回了不支持的辅助认证类型
}

// 释放内存
atrust_free(data);
data = nullptr;

6.3.2 TOTP辅助认证

如果您的服务器设置了TOTP的增强认证方式，在完成上一次认证后，会要求继续进行TOTP辅助认证，（对应nextAuth == atrust_auth_type::ATRUST_AUTH_TYPE_TOTP

TOTP认证之前不需要像短信认证一样需要调用额外的接口，而是直接调用TOTP认证接口进行认证。TOTP认证接口的出参类型和用户名密码主认证相同，内容也几乎一样。

接口定义

atrust_error_code ATRUST_API
atrust_sync_login_by_totp(const char *totpToken, atrust_auth_type *nextAuth, void **data);

参数和返回值说明

接口出参data说明

• 接口返回成功
  1. 接口返回成功则nextAuth出参非空，可根据nextAuth参数的取值，将data转换为对应的数据结构，其对应关系参考atrust_code.h。
  2. 如果配置了第三方认证服务器，则可以通过data出参中的authServerInfo字段获取aTrust服务端透传的认证服务器信息。
• 接口返回失败 接口返回失败 且 data非空的情况下，可以将data转换为通用的错误信息结构并从中获取错误码和具体的错误信息。其中错误码和接口返回值保持一致，错误信息与错误码一致。特殊地，如果是服务端返回的错误并且错误中包含动态信息，则可以从data中获取信息。

示例代码

atrust_auth_type nextAuth;
void *data;
atrust_error_code ec = atrust_sync_login_by_totp(m_totp, &nextAuth, &data);
switch (ec) {
// 成功
case atrust_error_code::OK:
    // TOTP令牌认证成功!
    break;
case atrust_error_code::PASSPORT_FAILED:
    // 认证失败，可能是TOTP过期或错误。
    atrust_free(data);
    return;
case atrust_error_code::AUTH_PARAM_EMPTY:
    // 输入的参数为空！
    atrust_free(data);
    return;
case atrust_error_code::OUT_PARAM_WRITE_ERROR:
    // 出参无法写入！
    atrust_free(data);
    return;
case atrust_error_code::SDPC_UNINITIALIZED:
    // 未调用初始化接口！
    atrust_free(data);
    return;
case atrust_error_code::ATRUST_CONNECT_ERROR:
    // aTrust客户端连接失败！如果重试任然失败，请检查aTrust客户端是否正确安装并运行。
    atrust_free(data);
    return;
case atrust_error_code::NO_PHONE_NUMBER_FOR_SMS_AUTH:
    // 设置了短信认证，但没有配置有效的号码。
    atrust_free(data);
    return;
case atrust_error_code::BAD_ALLOC_ERROR:
    // 内存分配失败。
    atrust_free(data);
    return;
case atrust_error_code::UNSOPPORTED_NEXT_AUTH_TYPE:
    // 服务端设置了不支持的增强认证方式。
    atrust_free(data);
    return;
// 未知的业务执行过程失败
default:
    // 接口调用失败！请在atrust_code.h中检查错误码，或尝试重试。错误码：ec
    if(data != NULL) {
        atrust_common_error_info* errInfo = static_cast<atrust_common_error_info*>(data);
        data->code;     // 获取错误码
        data->message;  // 获取错误信息
    }
    atrust_free(data);
    data = NULL;
    return;
}

switch (nextAuth) {
case atrust_auth_type::ATRUST_AUTH_TYPE_OK:
    // 登录成功！
    break;
//一般不会出现双重辅助认证的情况
case atrust_auth_type::ATRUST_AUTH_TYPE_SMS: {
    // TOTP令牌认证成功！下一步辅助认证：短信验证码
    atrust_auth_sms_phone_number_data *phoneData = static_cast<atrust_auth_sms_phone_number_data *>(data);
    if (phoneData != NULL) {
        // 用户手机号：phoneData->phone_number;
    }
    break;
}
case atrust_auth_type::ATRUST_AUTH_TYPE_RADIUS:
    // TOTP令牌认证成功！下一步辅助认证：Radius认证
    break;
default:
    // TOTP令牌认证成功，但服务器返回了不支持的辅助认证类型
}

// 释放内存
atrust_free(data);
data = nullptr;

6.3.3 Radius辅助认证

a. 辅助认证

如果您的服务器设置了Radius的增强认证方式，在完成上一次认证后，会要求继续进行Radius辅助认证，（对应nextAuth == atrust_auth_type::ATRUST_AUTH_TYPE_RADIUS

Radius作为辅助认证时和TOTP认证接口几乎相同，请注意不要调错了。

接口定义

atrust_error_code ATRUST_API
atrust_sync_login_by_radius(const char *radiusToken, atrust_auth_type *nextAuth, void **data);

参数和返回值说明

示例代码

// 请参考【TOTP认证】

6.3.4 错误码说明

注意： 1.接口调用后的错误信息，既可以通过data出参直接获取错误信息(建议优先使用此方式)，也可以通过atrust_error_string接口获取对应的错误信息。由于历史原因，在服务端返回错误时，atrust_error_string获取的错误信息可能丢弃了服务端的动态参数信息，因此建议优先使用data出参获取错误信息。