6.2 认证登录

登录流程是SDK最基础的业务流程。通过该流程，用户将登录您的服务器设备，并可以进一步使用对应的隧道业务等等。

登录流程一般紧随初始化之后，需要按顺序执行1个或多个步骤：

1. 用户名密码主认证。
2. 辅助认证（可选）

如果您的服务器针对用户只配置了用户名密码认证方式，则您的程序只需要调用用户名密码主认证接口，即可完成登录流程；用户名密码主认证方式是必须的，也是第一步的认证方式。

6.2.1 用户名密码主认证

6.2.1.1 接口定义

atrust_error_code ATRUST_API
atrust_sync_login_by_pwd(const char *username, const char *password, unsigned char force, atrust_auth_type *nextAuth,void **data);

参数和返回值说明

6.2.1.2 接口参数详细说明

1.用户名参数：

与网页端登录不同，使用CSSDK登录时，需要在原有账号密码后面附加 @认证域 。如果该用户不是服务器上的本地用户，而是ldap或其他外部认证域的用户时，需要再用户名上携带上认证域信息。例如，ladp认证域配置为ladp，用户test使用ldap认证域进行认证时，需要使用 test@ldap 作为username的参数，而不是 test，否则将导致认证错误。

认证域是管理员在控制中心配置的，可以前往认证服务器配置查看：

2.是否强制登录参数：

登录接口中的force参数标识是否强制登录。他们的区别如下：

1. 非强制登录 如果已经有任意其他用户登录（不管是哪个用户还是哪个服务器），都会返回已有用户登录的错误，并终止登录流程。

2. 强制登录 如果已经有任意其他用户登录（不管是哪个用户还是哪个服务器），之前已经登录成功的用户都会被注销，然后再执行当前username和password对应的登录流程。

而如果之前没有用户登录过，非强制登录和强制登录的效果是一样的。

这里需要特别注意的是，强制登录有可能导致一次注销流程。如果您订阅并关注了注销事件（后续【事件监听】中的内容），可能会在登录过程中收到注销事件。此时请不要认为登录失败并进入了注销状态。在您调用登录接口，并返回了OK（0）之后，您可以执行后续的【状态查询】流程来确认用户是否在线。

3.登录接口出参data说明

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

6.2.1.3 示例代码

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:
    // 认证失败，可能是用户名密码错误，或者用户已过期等原因。
    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::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;
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;

大多数情况下，您的服务器也许不会设置包括短信验证码认证在内的增强认证方式。因此，您的代码通常将会比上述示例代码更加的精简。

6.2.2 错误码说明

注意：

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