Функция LogonUserExW (winbase.h)
Функция LogonUserEx пытается войти пользователя на локальный компьютер. Локальный компьютер — это компьютер, с которого был вызван LogonUserEx . Вы не можете использовать LogonUserEx для входа на удаленный компьютер. Вы указываете пользователя с помощью имени пользователя и домена и выполняете проверку подлинности пользователя с помощью пароля в виде открытого текста. Если функция выполнена успешно, вы получите дескриптор маркера, представляющего вошедшего в систему пользователя. Затем этот дескриптор маркера можно использовать для олицетворения указанного пользователя или, в большинстве случаев, для создания процесса , который выполняется в контексте указанного пользователя.
Синтаксис
BOOL LogonUserExW(
[in] LPCWSTR lpszUsername,
[in, optional] LPCWSTR lpszDomain,
[in, optional] LPCWSTR 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
Указатель на строку, завершающуюся значением NULL, которая указывает имя пользователя. Это имя учетной записи пользователя для входа. При использовании формата имени участника-пользователя (UPN) user@DNS_domain_name параметр lpszDomain должен иметь значение NULL.
[in, optional] lpszDomain
Указатель на строку, завершающуюся значением NULL, которая указывает имя домена или сервера, база данных учетной записи которого содержит учетную запись lpszUsername . Если этот параметр имеет значение NULL, имя пользователя должно быть указано в формате имени участника-пользователя. Если этот параметр имеет значение ". ", функция проверяет учетную запись, используя только локальную базу данных учетных записей.
[in, optional] lpszPassword
Указатель на строку, завершающуюся значением NULL, которая указывает пароль в виде открытого текста для учетной записи пользователя, указанной параметром lpszUsername. Завершив использование пароля, очистите его из памяти, вызвав функцию SecureZeroMemory . Дополнительные сведения о защите паролей см. в разделе Обработка паролей.
[in] dwLogonType
Тип выполняемой операции входа. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Этот тип входа предназначен для серверов пакетной службы, где процессы могут выполняться от имени пользователя без его прямого вмешательства. Этот тип также предназначен для серверов с более высокой производительностью, которые одновременно обрабатывают множество попыток проверки подлинности в виде открытого текста, например почтовых или веб-серверов. Функция LogonUserEx не кэширует учетные данные для этого типа входа. |
|
Этот тип входа предназначен для пользователей, которые будут использовать компьютер в интерактивном режиме, например для пользователя, вошедшего в систему с помощью сервера терминалов , удаленной оболочки или аналогичного процесса. Этот тип входа имеет дополнительные расходы на кэширование сведений о входе в систему для отключенных операций; поэтому он не подходит для некоторых клиентских или серверных приложений, таких как почтовый сервер. |
|
Этот тип входа предназначен для высокопроизводительных серверов для проверки подлинности паролей в виде открытого текста. Функция LogonUserEx не кэширует учетные данные для этого типа входа. |
|
Этот тип входа сохраняет имя и пароль в пакете проверки подлинности, что позволяет серверу устанавливать подключения к другим сетевым серверам при олицетворении клиента. Сервер может принимать учетные данные в виде открытого текста от клиента, вызывать LogonUserEx, проверять, может ли пользователь получить доступ к системе по сети, и по-прежнему взаимодействовать с другими серверами. |
|
Этот тип входа позволяет вызывающей объекту клонировать текущий маркер и указать новые учетные данные для исходящих подключений. Новый сеанс входа имеет тот же локальный идентификатор, но использует другие учетные данные для других сетевых подключений.
Этот тип входа поддерживается только поставщиком LOGON32_PROVIDER_WINNT50 входа. |
|
Указывает на вход типа службы. Для предоставленной учетной записи необходимо включить привилегии службы. |
|
Этот тип входа предназначен для библиотек DLL GINA , которые входят в систему пользователей, которые будут использовать компьютер в интерактивном режиме. Этот тип входа может создать уникальную запись аудита, которая показывает, когда рабочая станция была разблокирована. |
[in] dwLogonProvider
Поставщик входа. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Используйте стандартный поставщик входа в систему. Поставщик безопасности по умолчанию — NTLM. |
|
Используйте поставщик для согласования входа. |
|
Используйте поставщик входа 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.
Комментарии
Тип входа LOGON32_LOGON_NETWORK является самым быстрым, но имеет следующие ограничения:
- Функция возвращает маркер олицетворения, а не первичный маркер. Этот маркер нельзя использовать непосредственно в функции CreateProcessAsUser . Однако можно вызвать функцию DuplicateTokenEx , чтобы преобразовать маркер в первичный, а затем использовать его в CreateProcessAsUser.
- Если вы преобразуете маркер в первичный и используете его в CreateProcessAsUser для запуска процесса, новый процесс не сможет получить доступ к другим сетевым ресурсам, таким как удаленные серверы или принтеры, через перенаправитель. Исключением является то, что если доступ к сетевому ресурсу не контролируется, новый процесс сможет получить к нему доступ.
Привилегия SE_TCB_NAME не требуется для этой функции, если только вы не входите в учетную запись Passport.
Учетная запись, указанная параметром lpszUsername , должна иметь необходимые права учетной записи. Например, чтобы войти в систему пользователя с флагом LOGON32_LOGON_INTERACTIVE, пользователь (или группа, к которой принадлежит пользователь) должен иметь право SE_INTERACTIVE_LOGON_NAME учетной записи. Список прав учетной записи, влияющих на различные операции входа, см. в разделе Права доступа к объектам учетной записи.
Пользователь считается вошедшего в систему, если существует хотя бы один маркер. Если вызвать CreateProcessAsUser , а затем закрыть маркер, пользователь по-прежнему входит в систему до завершения процесса (и всех дочерних процессов).
Если вызов LogonUserEx выполнен успешно, система уведомляет сетевых поставщиков о входе, вызвав функцию точки входа NPLogonNotify поставщика.
Примечание
Заголовок winbase.h определяет LogonUserEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbase.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
Контроль доступа клиента или сервера