Функция LogonUserExA (winbase.h)

Статья
08/27/2023

Функция LogonUserEx пытается войти пользователя на локальный компьютер. Локальный компьютер — это компьютер, с которого был вызван LogonUserEx . Вы не можете использовать LogonUserEx для входа на удаленный компьютер. Вы указываете пользователя с помощью имени пользователя и домена и проверяете подлинность пользователя с помощью пароля в формате обычного текста. При успешном выполнении функции вы получите дескриптор маркера, который представляет пользователя, выполнившего вход. Затем этот дескриптор маркера можно использовать для олицетворения указанного пользователя или, в большинстве случаев, для создания процесса , который выполняется в контексте указанного пользователя.

Синтаксис

BOOL LogonUserExA(
  [in]            LPCSTR        lpszUsername,
  [in, optional]  LPCSTR        lpszDomain,
  [in, optional]  LPCSTR        lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

Параметры

[in] lpszUsername

Указатель на строку, завершающуюся нулевым значением, которая указывает имя пользователя. Это имя учетной записи пользователя для входа. При использовании формата имени участника-пользователя (UPN) user@DNS_domain_name параметр lpszDomain должен иметь значение NULL.

[in, optional] lpszDomain

Указатель на строку со значением NULL, которая указывает имя домена или сервера, база данных учетных записей которого содержит учетную запись lpszUsername . Если этот параметр имеет значение NULL, имя пользователя должно быть указано в формате имени участника-пользователя. Если этот параметр имеет значение ".", функция проверяет учетную запись, используя только базу данных локальной учетной записи.

[in, optional] lpszPassword

Указатель на строку, завершающуюся значением NULL, которая указывает пароль в виде открытого текста для учетной записи пользователя, указанной в параметре lpszUsername. Завершив использование пароля, очистите пароль из памяти, вызвав функцию SecureZeroMemory . Дополнительные сведения о защите паролей см. в разделе Обработка паролей.

[in] dwLogonType

Тип выполняемой операции входа. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
LOGON32_LOGON_BATCH	Этот тип входа предназначен для серверов пакетной службы, где процессы могут выполняться от имени пользователя без его прямого вмешательства. Этот тип также предназначен для серверов с более высокой производительностью, которые одновременно обрабатывают множество попыток проверки подлинности в виде открытого текста, таких как почтовые или веб-серверы. Функция LogonUserEx не кэширует учетные данные для этого типа входа.
LOGON32_LOGON_INTERACTIVE	Этот тип входа предназначен для пользователей, которые будут использовать компьютер в интерактивном режиме, например для пользователя, вошедшего в систему с помощью сервера терминалов , удаленной оболочки или аналогичного процесса. Этот тип входа включает дополнительные расходы на кэширование сведений о входе в систему для отключенных операций; таким образом, он не подходит для некоторых клиентских или серверных приложений, таких как почтовый сервер.
LOGON32_LOGON_NETWORK	Этот тип входа предназначен для высокопроизводительных серверов для проверки подлинности паролей в виде открытого текста. Функция LogonUserEx не кэширует учетные данные для этого типа входа.
LOGON32_LOGON_NETWORK_CLEARTEXT	Этот тип входа сохраняет имя и пароль в пакете проверки подлинности, что позволяет серверу устанавливать подключения к другим сетевым серверам при олицетворении клиента. Сервер может принимать учетные данные в виде открытого текста от клиента, вызывать LogonUserEx, проверять, что пользователь может получить доступ к системе по сети, и по-прежнему обмениваться данными с другими серверами.
LOGON32_LOGON_NEW_CREDENTIALS	Этот тип входа позволяет вызывающей объекту клонировать текущий маркер и указывать новые учетные данные для исходящих подключений. Новый сеанс входа имеет тот же локальный идентификатор, но использует другие учетные данные для других сетевых подключений. Этот тип входа поддерживается только поставщиком LOGON32_PROVIDER_WINNT50 входа.
LOGON32_LOGON_SERVICE	Указывает тип входа службы. Для предоставленной учетной записи необходимо включить привилегию службы.
LOGON32_LOGON_UNLOCK	Этот тип входа предназначен для библиотек DLL GINA , которые входят в систему пользователей, которые будут использовать компьютер в интерактивном режиме. Этот тип входа может создать уникальную запись аудита, которая показывает, когда рабочая станция была разблокирована.

[in] dwLogonProvider

Поставщик входа. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
LOGON32_PROVIDER_DEFAULT	Используйте стандартный поставщик входа в систему. Поставщик безопасности по умолчанию — NTLM.
LOGON32_PROVIDER_WINNT50	Используйте поставщик с согласованием входа.
LOGON32_PROVIDER_WINNT40	Используйте поставщик входа NTLM.

[out, optional] phToken

Указатель на переменную дескриптора, которая получает дескриптор маркера, представляющего указанного пользователя.

Возвращаемый дескриптор можно использовать в вызовах функции ImpersonateLoggedOnUser .

В большинстве случаев возвращаемый дескриптор является основным маркером , который можно использовать в вызовах функции CreateProcessAsUser . Однако если указать флаг LOGON32_LOGON_NETWORK, LogonUserEx возвращает маркер олицетворения , который нельзя использовать в CreateProcessAsUser , если только вы не вызовете DuplicateTokenEx для преобразования маркера олицетворения в первичный.

Если этот дескриптор больше не нужен, закройте его, вызвав функцию CloseHandle .

[out, optional] ppLogonSid

Указатель на указатель на идентификатор безопасности (SID), который получает идентификатор безопасности пользователя, выполнившего вход.

Завершив использование идентификатора безопасности, освободите его, вызвав функцию LocalFree .

[out, optional] ppProfileBuffer

Указатель на указатель, который получает адрес буфера, содержащего профиль пользователя, выполнившего вход.

[out, optional] pdwProfileLength

Указатель на DWORD , получающий длину буфера профиля.

[out, optional] pQuotaLimits

Указатель на структуру QUOTA_LIMITS , получающую сведения о квотах для вошедшего в систему пользователя.

Возвращаемое значение

Если функция выполняется успешно, функция возвращает ненулевое значение.

Если функция завершается сбоем, она возвращает ноль. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция возвращает токен олицетворения, а не основной маркер. Этот маркер нельзя использовать непосредственно в функции CreateProcessAsUser . Однако можно вызвать функцию DuplicateTokenEx , чтобы преобразовать маркер в первичный, а затем использовать его в CreateProcessAsUser.
Если вы преобразуете маркер в первичный и используете его в CreateProcessAsUser для запуска процесса, новый процесс не сможет получить доступ к другим сетевым ресурсам, таким как удаленные серверы или принтеры, через перенаправление. Исключением является то, что если доступ к сетевому ресурсу не контролируется, новый процесс сможет получить к нему доступ.

Привилегия SE_TCB_NAME не требуется для этой функции, если вы не входите в учетную запись Passport.

Учетная запись, указанная параметром lpszUsername , должна иметь необходимые права. Например, чтобы войти в систему пользователя с флагом LOGON32_LOGON_INTERACTIVE, пользователь (или группа, к которой принадлежит пользователь) должен иметь право на SE_INTERACTIVE_LOGON_NAME учетную запись. Список прав учетной записи, влияющих на различные операции входа, см. в статье Права доступа к объектам учетной записи.

Пользователь считается вошедшего в систему, если существует хотя бы один маркер. Если вызвать CreateProcessAsUser , а затем закрыть маркер, пользователь по-прежнему входит в систему до завершения процесса (и всех дочерних процессов).

Если вызов LogonUserEx выполнен успешно, система уведомляет сетевых поставщиков о том, что вход произошел, вызвав функцию точки входа NPLogonNotify поставщика.

Примечание

Заголовок winbase.h определяет LogonUserEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll