Функция LogonUserExExW

Статья
06/13/2023

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

Эта функция похожа на функцию LogonUserEx , за исключением того, что она принимает дополнительный параметр pTokenGroups, который представляет собой набор из одного или нескольких идентификаторов безопасности (SID), которые добавляются в маркер, возвращаемый вызывающему объекту при успешном входе.

Эта функция не объявлена в общедоступном заголовке и не имеет связанной библиотеки импорта. Для динамической связи с Advapi32.dll необходимо использовать функции LoadLibrary и GetProcAddress .

Синтаксис

BOOL WINAPI LogonUserExExW(
  _In_      LPTSTR        lpszUsername,
  _In_opt_  LPTSTR        lpszDomain,
  _In_opt_  LPTSTR        lpszPassword,
  _In_      DWORD         dwLogonType,
  _In_      DWORD         dwLogonProvider,
  _In_opt_  PTOKEN_GROUPS pTokenGroups,
  _Out_opt_ PHANDLE       phToken,
  _Out_opt_ PSID          *ppLogonSid,
  _Out_opt_ PVOID         *ppProfileBuffer,
  _Out_opt_ LPDWORD       pdwProfileLength,
  _Out_opt_ PQUOTA_LIMITS pQuotaLimits
);

Параметры

lpszUsername [in]

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

lpszDomain [in, необязательный]

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

lpszPassword [in, необязательный]

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

dwLogonType [in]

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

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

dwLogonProvider [in]

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

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

pTokenGroups [in, необязательный]

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

Если этот параметр не равен NULL, вызывающий объект этой функции должен иметь предоставленные и включенные привилегии SE_TCB_PRIVILEGE.

phToken [out, optional]

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

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

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

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

ppLogonSid [out, необязательный]

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

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

ppProfileBuffer [out, optional]

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

pdwProfileLength [out, optional]

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

pQuotaLimits [out, optional]

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

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

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

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

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

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

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

Если указан необязательный параметр pTokenGroups , LSA не будет автоматически добавлять локальный идентификатор безопасности или идентификатор безопасности входа.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Версия	LogonUserExExW также доступен в Windows Server 2003 или Windows XP с общим выпуском дистрибутива.
Заголовок	Winbasep.h
DLL	Advapi32.dll

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

контроль доступа клиента или сервера
Функции контроль доступа клиента или сервера
CloseHandle
CreateProcessAsUser
DuplicateTokenEx
ImpersonateLoggedOnUser
LogonUserEx
QUOTA_LIMITS

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

Функция LogonUserExExW

Синтаксис

Параметры

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

Комментарии

Требования

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

Обратная связь

Дополнительные ресурсы