LogonUserExA 関数 (winbase.h)

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

構文

BOOL LogonUserExA(
  [in]            LPCSTR        lpszUsername,
  [in, optional]  LPCSTR        lpszDomain,
  [in, optional]  LPCSTR        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

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

[in, optional] lpszPassword

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

[in] dwLogonType

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

[in] dwLogonProvider

ログオン プロバイダー。 このパラメーターには、次の値のいずれかを指定できます。

[out, optional] phToken

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

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

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

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

[out, optional] ppLogonSid

ログオンしているユーザーの SID を受け取る セキュリティ識別子 (SID) へのポインターへのポインター。

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

[out, optional] ppProfileBuffer

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

[out, optional] pdwProfileLength

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

[out, optional] pQuotaLimits

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

戻り値

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

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

解説

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

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

Passport アカウントにログオンしている場合を除き、この機能にはSE_TCB_NAME特権は必要ありません。

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

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

LogonUserEx 呼び出しが成功した場合、システムは、プロバイダーの NPLogonNotify エントリ ポイント関数を呼び出すことによって、ログオンが発生したことをネットワーク プロバイダーに通知します。

要件

こちらもご覧ください

クライアント/サーバー Access Control

クライアント/サーバー Access Control関数

CloseHandle

CreateProcessAsUser

DuplicateTokenEx

ImpersonateLoggedOnUser

QUOTA_LIMITS