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
ユーザーの名前を指定する null で終わる文字列へのポインター。 これは、ログオン先のユーザー アカウントの名前です。 ユーザー プリンシパル名 (UPN) 形式の User@DNSDomainName を使用する場合、lpszDomain パラメーターは NULL である必要があります。
[in, optional] lpszDomain
アカウント データベースに lpszUsername アカウントが含まれているドメインまたはサーバーの名前を指定する null で終わる文字列へのポインター。 このパラメーターが NULL の場合、ユーザー名は UPN 形式で指定する必要があります。 このパラメーターが "." の場合、関数はローカル アカウント データベースのみを使用してアカウントを検証します。
[in, optional] lpszPassword
lpszUsername で指定されたユーザー アカウントのプレーンテキスト パスワードを指定する null で終わる文字列へのポインター。 パスワードの使用が完了したら、 SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。 パスワードの保護の詳細については、「パスワードの 処理」を参照してください。
[in] dwLogonType
実行するログオン操作の種類。 このパラメーターには、Winbase.h で定義されている次のいずれかの値を指定できます。
| 値 | 意味 |
|---|---|
|
このログオンの種類は、直接の介入なしにユーザーに代わってプロセスを実行できるバッチ サーバーを対象としています。 この種類は、メールや Web サーバーなど、一度に多くのプレーンテキスト認証試行を処理するパフォーマンスの高いサーバーにも使用されます。 |
|
このログオンの種類は、 ターミナル サーバー、リモート シェル、または同様のプロセスによってログオンされているユーザーなど、コンピューターを対話的に使用するユーザーを対象としています。 このログオンの種類には、切断された操作のログオン情報をキャッシュする追加の費用がかかります。そのため、メール サーバーなどの一部のクライアント/サーバー アプリケーションには不適切です。 |
|
このログオンの種類は、ハイ パフォーマンス サーバーがプレーンテキスト パスワードを認証することを目的としています。 LogonUser 関数は、このログオンの種類の資格情報をキャッシュしません。 |
|
このログオンの種類では 、認証パッケージ内の名前とパスワードが保持されます。これにより、サーバーはクライアントの偽装中に他のネットワーク サーバーに接続できるようになります。 サーバーは、クライアントからのプレーンテキスト資格情報を受け入れ、 LogonUser を呼び出し、ユーザーがネットワーク経由でシステムにアクセスできることを確認し、引き続き他のサーバーと通信できます。 |
|
このログオンの種類により、呼び出し元は現在のトークンを複製し、送信接続の新しい資格情報を指定できます。 新しいログオン セッションは同じローカル識別子を持ちますが、他のネットワーク接続には異なる資格情報を使用します。
このログオンの種類は、LOGON32_PROVIDER_WINNT50 ログオン プロバイダーでのみサポートされます。 注: 2023 年 1 月の時点で、グループ管理サービス アカウント (gMSA) でLOGON32_LOGON_NEW_CREDENTIALSログオンの種類を使用することはできません。 |
|
サービスの種類のログオンを示します。 指定されたアカウントでは、サービス特権が有効になっている必要があります。 |
|
GINA はサポートされなくなりました。
Windows Server 2003 および Windows XP: このログオンの種類は、コンピューターを対話的に使用するユーザーにログオンする GINA DLL 用です。 このログオンの種類では、ワークステーションのロックが解除された日時を示す一意の監査レコードを生成できます。 |
[in] dwLogonProvider
ログオン プロバイダーを指定します。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 意味 |
|---|---|
|
システムの標準ログオン プロバイダーを使用します。 ドメイン名に NULL を渡し、ユーザー名が UPN 形式でない場合を除き、既定のセキュリティ プロバイダーはネゴシエートされます。 この場合、既定のプロバイダーは NTLM です。 |
|
ネゴシエート ログオン プロバイダーを使用します。 |
|
NTLM ログオン プロバイダーを使用します。 |
[out] phToken
指定したユーザーを表すトークンへのハンドルを受け取るハンドル変数へのポインター。
返されたハンドルは、 ImpersonateLoggedOnUser 関数の呼び出しで使用できます。
ほとんどの場合、返されるハンドルは、CreateProcessAsUser 関数の呼び出しで使用できるプライマリ トークンです。 ただし、LOGON32_LOGON_NETWORK フラグを指定すると、DuplicateTokenEx を呼び出してプライマリ トークンに変換しない限り、LogonUser は CreateProcessAsUser で使用できない偽装トークンを返します。
このハンドルが不要になったら、 CloseHandle 関数を呼び出して閉じます。
戻り値
関数が成功した場合、関数は 0 以外の値を返します。
関数が失敗すると、0 が返されます。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
LOGON32_LOGON_NETWORKログオンの種類は最速ですが、次の制限があります。
- 関数は、プライマリ トークンではなく、 偽装トークンを返します。 このトークンは、 CreateProcessAsUser 関数では直接使用できません。 ただし、 DuplicateTokenEx 関数を呼び出してトークンをプライマリ トークンに変換し、 CreateProcessAsUser で使用できます。
- トークンをプライマリ トークンに変換し、 CreateProcessAsUser で使用してプロセスを開始した場合、新しいプロセスはリダイレクターを介してリモート サーバーやプリンターなどの他のネットワーク リソースにアクセスできません。 例外として、ネットワーク リソースがアクセス制御されていない場合、新しいプロセスでアクセスできるようになります。
Passport アカウントにログオンしている場合を除き、この機能にはSE_TCB_NAME特権は必要ありません。
lpszUsername で指定されたアカウントには、必要なアカウント権限が必要です。 たとえば、LOGON32_LOGON_INTERACTIVE フラグを使用してユーザーにログオンするには、ユーザー (またはユーザーが属するグループ) に SE_INTERACTIVE_LOGON_NAME アカウント権限が必要です。 さまざまなログオン操作に影響するアカウント権限の一覧については、「 Account Rights Constants」を参照してください。
少なくとも 1 つのトークンが存在する場合、ユーザーはログオンしたと見なされます。 CreateProcessAsUser を呼び出してトークンを閉じると、システムは、プロセス (およびすべての子プロセス) が終了するまで、ユーザーがまだログオンしたと見なします。
LogonUser 呼び出しが成功した場合、システムは、プロバイダーの NPLogonNotify エントリ ポイント関数を呼び出すことによって、ログオンが発生したことをネットワーク プロバイダーに通知します。
例
LocalService トークンは、次のコードを使用して生成できます。
LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)
注意
winbase.h ヘッダーは LogonUser をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |