LogonUserExExW 関数

[アーティクル]
06/13/2023

LogonUserExExW 関数は、ユーザーをローカルコンピューターにログオンしようとします。ローカルコンピューターは、 LogonUserExExW が呼び出されたコンピューターです。 LogonUserExExW を使用してリモートコンピューターにログオンすることはできません。ユーザー名とドメインを使用してユーザーを指定し、プレーンテキストパスワードを使用してユーザーを認証します。関数が成功すると、ログオンしているユーザーを表すトークンへのハンドルを受け取ります。その後、このトークンハンドルを使用して、指定したユーザーを偽装するか、ほとんどの場合、指定したユーザーのコンテキストで実行される プロセス を作成できます。

この関数は LogonUserEx 関数に似ていますが、ログオンが成功したときに呼び出し元に返されるトークンに追加される 1 つ以上のセキュリティ識別子 (SID) のセットである追加パラメーター pTokenGroups を受け取る点が除きます。

この関数はパブリックヘッダーで宣言されておらず、関連付けられたインポートライブラリがありません。 LoadLibrary 関数と GetProcAddress 関数を使用して、Advapi32.dllに動的にリンクする必要があります。

構文

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, optional]

アカウントデータベースに lpszUsername アカウントが含まれているドメインまたはサーバーの名前を指定する、null で終わる文字列へのポインター。このパラメーターが NULL の場合、ユーザー名は UPN 形式で指定する必要があります。このパラメーターが "." の場合、関数はローカルアカウントデータベースのみを使用してアカウントを検証します。

lpszPassword [in, optional]

lpszUsername で指定されたユーザーアカウントのプレーンテキストパスワードを指定する null で終わる文字列へのポインター。パスワードの使用が完了したら、 SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。パスワードの保護の詳細については、「パスワードの処理」を参照してください。

dwLogonType [in]

実行するログオン操作の種類。このパラメーターには、次の値のいずれかを指定できます。

値	説明
LOGON32_LOGON_INTERACTIVE 2	このログオンの種類は、ターミナルサーバー、リモートシェル、または同様のプロセスによってログオンしているユーザーなど、コンピューターを対話的に使用するユーザーを対象としています。このログオンの種類には、切断された操作のログオン情報をキャッシュする追加の費用がかかります。そのため、メールサーバーなどの一部のクライアント/サーバーアプリケーションでは不適切です。
LOGON32_LOGON_NETWORK 3	このログオンの種類は、ハイパフォーマンスサーバーがプレーンテキストパスワードを認証することを目的としています。 LogonUserExExW 関数は、このログオンの種類の資格情報をキャッシュしません。
LOGON32_LOGON_BATCH 4	このログオンの種類は、プロセスがユーザーに代わって直接介入することなく実行されるバッチサーバーを対象としています。この種類は、メールや Web サーバーなど、一度に多数のプレーンテキスト認証の試行を処理するパフォーマンスの高いサーバー向けでもあります。 LogonUserExExW 関数は、このログオンの種類の資格情報をキャッシュしません。
LOGON32_LOGON_SERVICE 5	サービスの種類のログオンを示します。指定されたアカウントで、サービス特権が有効になっている必要があります。
LOGON32_LOGON_UNLOCK 7	このログオンの種類は、コンピューターを対話的に使用するユーザーにログオンする GINA DLL 用です。このログオンの種類では、ワークステーションのロックが解除された日時を示す一意の監査レコードを生成できます。
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, optional]

ログオンの成功時にこの関数が受け取るトークンに追加されるグループ SID の一覧を指定する TOKEN_GROUPS構造体への ポインター。トークンに追加されたすべての SID も、グループの拡張に影響します。たとえば、追加された SID がローカルグループのメンバーである場合、それらのグループも受信したアクセストークンに追加されます。

このパラメーターが NULL でない場合、この関数の呼び出し元には 、SE_TCB_PRIVILEGE 特権が付与され、有効になっている必要があります。

phToken [out, optional]

指定したユーザーを表すトークンへのハンドルを受け取るハンドル変数へのポインター。

返されたハンドルは、 ImpersonateLoggedOnUser 関数の呼び出しで使用できます。

ほとんどの場合、返されるハンドルは、CreateProcessAsUser 関数の呼び出しで使用できるプライマリトークンです。ただし、LOGON32_LOGON_NETWORK フラグを指定すると、LogonUserExExW は、偽装トークンをプライマリ トークンに変換するために DuplicateTokenEx を呼び出さない限り、CreateProcessAsUser で使用できない偽装トークンを返します。

このハンドルが不要になったら、 CloseHandle 関数を呼び出して閉じます。

ppLogonSid [out, optional]

ログオンしているユーザーの SID を受け取る SID へのポインターへのポインター。

SID の使用が完了したら、 LocalFree 関数を呼び出して SID を解放します。

ppProfileBuffer [out, optional]

ログオンしているユーザーのプロファイルを含むバッファーのアドレスを受け取るポインターへのポインター。

pdwProfileLength [out, optional]

プロファイルバッファーの長さを受け取る DWORD へのポインター。

pQuotaLimits [out, optional]

ログオンしている ユーザーのクォータ に関する情報を受け取るQUOTA_LIMITS構造体へのポインター。

戻り値

関数が成功した場合、関数は 0 以外の値を返します。

関数が失敗すると、0 が返されます。詳細なエラー情報を得るには、GetLastError を呼び出します。

注釈

LOGON32_LOGON_NETWORKログオンの種類は最速ですが、次の制限があります。

この関数は、プライマリトークンではなく、 偽装トークンを返します。このトークンは、 CreateProcessAsUser 関数では直接使用できません。ただし、 DuplicateTokenEx 関数を呼び出してトークンをプライマリトークンに変換し、 CreateProcessAsUser で使用できます。
トークンをプライマリトークンに変換し、 CreateProcessAsUser で使用してプロセスを開始した場合、新しいプロセスはリダイレクターを介してリモートサーバーやプリンターなどの他のネットワークリソースにアクセスできません。例外として、ネットワークリソースがアクセス制御されていない場合、新しいプロセスでアクセスできるようになります。

lpszUsername で指定されたアカウントには、必要なアカウント権限が必要です。たとえば、 LOGON32_LOGON_INTERACTIVE フラグを使用してユーザーにログオンするには、ユーザー (またはユーザーが属するグループ) に SE_INTERACTIVE_LOGON_NAME アカウント権限が必要です。さまざまなログオン操作に影響するアカウント権限の一覧については、「 Account Object Access Rights」を参照してください。

少なくとも 1 つのトークンが存在する場合、ユーザーはログオンしたと見なされます。 CreateProcessAsUser を呼び出してトークンを閉じると、ユーザーはプロセス (およびすべての子プロセス) が終了するまでログオンします。

オプションの pTokenGroups パラメーターが指定されている場合、LSA はローカル SID またはログオン SID を自動的に追加しません。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
バージョン	LogonUserExExW は、Windows Server 2003 または一般配布リリースの Windows XP でも使用できます。
ヘッダー	Winbasep.h
[DLL]	Advapi32.dll

次の方法で共有

LogonUserExExW 関数

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

その他のリソース