Поделиться через


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

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

Синтаксис

BOOL LogonUserA(
  [in]           LPCSTR  lpszUsername,
  [in, optional] LPCSTR  lpszDomain,
  [in, optional] LPCSTR  lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

Параметры

[in] lpszUsername

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

[in, optional] lpszDomain

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

[in, optional] lpszPassword

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

[in] dwLogonType

Тип выполняемой операции входа. Этот параметр может быть одним из следующих значений, определенных в Winbase.h.

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

Этот тип входа поддерживается только поставщиком LOGON32_PROVIDER_WINNT50 входа.

Примечание. По состоянию на январь 2023 г. невозможно использовать тип входа LOGON32_LOGON_NEW_CREDENTIALS с групповой управляемой учетной записью службы (gMSA).

LOGON32_LOGON_SERVICE
Указывает тип входа службы. Для предоставленной учетной записи необходимо включить привилегию службы.
LOGON32_LOGON_UNLOCK
GINAs больше не поддерживаются.

Windows Server 2003 и Windows XP: Этот тип входа предназначен для библиотек DLL GINA , которые входят в систему пользователей, которые будут использовать компьютер в интерактивном режиме. Этот тип входа может создать уникальную запись аудита, которая показывает, когда рабочая станция была разблокирована.

[in] dwLogonProvider

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

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

[out] phToken

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

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

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

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

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

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

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

Комментарии

Тип LOGON32_LOGON_NETWORK входа является самым быстрым, но имеет следующие ограничения:

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

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

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

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

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

Примеры

Токен LocalService можно создать с помощью следующего кода.

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

Примечание

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

Требования

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

См. также раздел

Контроль доступа клиента или сервера

Функции контроль доступа клиента и сервера

CloseHandle

CreateProcessAsUser

DuplicateTokenEx

ImpersonateLoggedOnUser