场景简介

1.用户名密码认证是最基本也是使用最多的主认证方式，熟悉了用户名密码认证流程后，要实现其他类型的主认证流程是完全一致的，只是在传递认证参数上有点区别。

2.https帐号认证，ldap用户认证以及radius认证是常用的外部认证方式，由于都属于账号登录，调用接口基本与用户名/密码一致，原理上也都是联动外部第三方服务器做认证，只是在调用认证接口传递认证参数上有点区别。

前置步骤

1.在实际集成之前，我们要确保已经进行过开发准备，选择了对应的集成方式

2.在aTurst控制台创建测试用户，并配置好用户名密码认证，参考产品手册

3.使用对应的Demo程序验证可以正常使用

流程图

集成步骤

1.初始化SDK

初始化SDK接口详情

初始化接口会配置服务器的接入地址，并进行SDK内部的其他初始流程。该接口调用之后，后续的所有包括登录、注销、以及事件监听等与服务器地址相关的操作都将基于该接口中配置的服务器地址进行。

示例代码

atrust_error_code ec = atrust_initial(m_sdpcAddr);
switch (ec) {
// 成功
case atrust_error_code::OK: 
    // aTrust SDK初始化成功!
    break;
// 地址格式错误
case atrust_error_code::HOST_FORMAT_ERROR: 
    // 输入地址参数格式错误！
    return;
// 未知的业务执行过程失败
default: 
    // 接口调用失败！请在atrust_code.h中检查错误码，或尝试重试。错误码：ec
    return;
}

注意：

1. 该接口只会初始化SDK内部变量，不会检查当前是否已经安装aTurst客户端。

2.用户名密码主认证

用户名密码主认证接口详情

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

示例代码

atrust_auth_type nextAuth;
void *data;
atrust_error_code ec = atrust_sync_login_by_pwd(m_userName, m_userPwd, m_isForceLogin, &nextAuth, &data);
switch (ec) {
// 成功
case atrust_error_code::OK:
    // 用户名密码认证成功!
    break;
case atrust_error_code::PASSPORT_FAILED:
    // 认证失败，可能是用户名密码错误，或者用户已过期等原因。
    return;
case atrust_error_code::AUTH_PARAM_EMPTY:
    // 输入的参数为空！
    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::NO_PHONE_NUMBER_FOR_SMS_AUTH:
    // 设置了短信认证，但没有配置有效的号码。
    return;
case atrust_error_code::BAD_ALLOC_ERROR:
    // 内存分配失败。
    return;
case atrust_error_code::UNSOPPORTED_NEXT_AUTH_TYPE:
    // 服务端设置了不支持的增强认证方式。
    return;
// 未知的业务执行过程失败
default:
    // 接口调用失败！请在atrust_code.h中检查错误码，或尝试重试。错误码：ec
    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;
case atrust_auth_type::ATRUST_AUTH_TYPE_SMS: {
    // 用户名密码验证成功！下一步辅助认证：短信验证码
    atrust_auth_sms_phone_number_data *phoneData = static_cast<atrust_auth_sms_phone_number_data *>(data);
    if (phoneData != NULL) {
        // 用户手机号：phoneData->phone_number;
    }
    break;
}
default:
    // 用户名密码认证成功，但服务器返回了不支持的辅助认证类型
}

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

注意：

1. 这里的用户名可能会包含认证域。如果该用户不是服务器本地用户，而是ldap或其他外部认证域的用户，请在输入携带认证域的用户名。比如，用户wyx是ldap用户，使用“wyx@ldap”作为username的参数，而不是“wyx”，否则将导致认证错误。

2.1 认证成功

当认证接口atrust_sync_login_by_pwd返回结果为atrust_error_code::OK时表示本次认证操作已经成功。如果管理员未配置二次认证策略，主认证成功之后表示已经完成登录操作，登录成功之后aTrust客户端后台服务进程会从控制器上获取应用策略启动隧道服务，此时还不能立即访问隧道资源，需要等待隧道启动成功。

2.2 认证失败

当认证接口atrust_sync_login_by_pwd返回结果不为atrust_error_code::OK时表示认证不成功，需要根据不同的错误码进行不同的操作，详情可参考demo程序或错误码说明。

2.3 处理下一次认证

当认证接口atrust_sync_login_by_pwd返回结果为atrust_error_code::OK,但是nextAuth的结果不为atrust_auth_type::ATRUST_AUTH_TYPE_OK时，说明管理员开启了二次认证，需要进行二次认证才能继续完成登录操作。

3.查询隧道状态

状态查询接口详情

示例代码

atrust_status *data = NULL;
atrust_error_code ec = atrust_sync_query_status(&data);

if (ec != atrust_error_code::OK) {
    switch (ec) {  
    case atrust_error_code::OUT_PARAM_WRITE_ERROR:
        // 出参无法写入！
        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;
    }
}

// 成功
// 状态查询成功！
// 用户状态：data->user_status
// 隧道状态：data->tunnel_status

if (data->tunnel_status != 
   //
}

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

注意：

1. 状态查询接口可以获取当前用户在线状态和隧道状态 隧道状态分为可用状态和不可用状态，认证成功之后，需要等隧道状态为可用状态时，才能真正的访问发布的资源应用。

4.监听客户端状态变化

事件监听接口详情

除了主动调用接口主动查询隧道状态是否

示例代码

```cpp
//事件回调处理函数
void event_handler(atrust_event_type event, atrust_event_data data) {
    // 事件监听器收到事件! 事件类型: event
    // 注意回调函数所在的线程
    switch (event) {
    case atrust_event_type::USER_LOGOUT:
        // 用户 data.data.logout.username 
        // 已从服务器 data.data.logout.sdpc 注销！
        // 注销类型：data.data.logout.type 
        // 描述: data.data.logout.typeDescribe

        // 注意，这里可能是强制登录时产生的注销事件，且收到注销事件的时间可能在强制登录成功之后。
        // 因此，如果希望利用该事件设置用户状态，请在收到该事件之后调用一次atrust_sync_query_status接口确保用户已经离线
        break;
    case atrust_event_type::TUNNEL_STATUS: 
        // 新的隧道状态：data.data.tunnel_status.tunnelStatus 
        // 描述 data.data.tunnel_status.tunnelStatusDescribe
        break;
    default:
      //其它不关注的事件
    }
}

//注册事件回调接口
atrust_regist_listener(event_handler);

注意：

1. 收到atrust_event_type::USER_LOGOUT事件，表示当前登录的用户已经被注销，集成程序需要处理对应的注销逻辑。如提示用户aTurst已经下线，需要重新登录上线，否则资源将无法正常访问。

2. 收到atrust_event_type::TUNNEL_STATUS事件，表示当前隧道状态正在发生变化，当隧道状态返回可用状态，则表示隧道已经启动成功。