CredUIPromptForCredentialsW 関数 (wincred.h)
CredUIPromptForCredentials 関数は、ユーザーからの資格情報を受け入れる構成可能なダイアログ ボックスを作成して表示します。
次の理由から、Windows Vista または Windows Server 2008 を対象とするアプリケーションでは、この関数ではなく CredUIPromptForWindowsCredentials を呼び出す必要があります。
- CredUIPromptForWindowsCredentials は、現在の Windows ユーザー インターフェイスと一致しています。
- CredUIPromptForWindowsCredentials は拡張性が高く、生体認証やスマート カードなどの追加の認証メカニズムを統合できます。
- CredUIPromptForWindowsCredentials は、共通条件の仕様に準拠しています。
構文
CREDUIAPI DWORD CredUIPromptForCredentialsW(
[in, optional] PCREDUI_INFOW pUiInfo,
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PWSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
パラメーター
[in, optional] pUiInfo
ダイアログ ボックスの外観をカスタマイズするための情報を含む CREDUI_INFO 構造体へのポインター。
[in] pszTargetName
資格情報のターゲットの名前 (通常はサーバー名) を含む null で終わる文字列へのポインター。 分散ファイル システム (DFS) 接続の場合、この文字列は ServerName\ShareName という形式です。 このパラメーターは、資格情報の格納と取得時にターゲット情報を識別するために使用されます。
[in] pContext
このパラメーターは将来使用するために予約されています。 NULL である必要があります。
[in, optional] dwAuthError
資格情報ダイアログ ボックスが必要な理由を指定します。 呼び出し元は、別の認証呼び出しによって返されるこの Windows エラー パラメーターを渡して、ダイアログ ボックスが特定のエラーに対応できるようにします。 たとえば、パスワードの有効期限が切れた状態コードが渡された場合、ダイアログ ボックスでユーザーにアカウントのパスワードの変更を求めるメッセージが表示される場合があります。
[in, out] pszUserName
資格情報のユーザー名を含む null で終わる文字列へのポインター。 0 以外の長さの文字列を渡すと、ダイアログ ボックスの UserName オプションに文字列が事前に入力されます。 UserName/Password 以外の資格情報の場合は、資格情報のマーシャリング形式を渡すことができます。 この文字列は、 CredMarshalCredential を呼び出すことによって作成されます。
この関数は、ユーザー指定の名前をこのバッファーにコピーし、最大 ulUserNameMaxChars 文字をコピーします。 この形式は、CredUIParseUsername を使用して UserName/パスワード形式に変換できます。 マーシャリングされた形式は、 セキュリティ サポート プロバイダー (SSP) に直接渡すことができます。
CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、 CredUIParseUsername に渡す以外の検査、印刷、または永続化を行わないフォームです。 CredUIParseUsername の後続の結果は、WNetAddConnection や SSP 関数などのクライアント側認証関数にのみ渡すことができます。
このパラメーターの一部としてドメインまたはサーバーが指定されていない場合は、ドメインとして pszTargetName パラメーターの値が DomainName\UserName ペアを形成するために使用されます。 出力時に、このパラメーターは、その DomainName UserName\ ペアを含む文字列を受け取ります。
[in] ulUserNameBufferSize
pszUserName にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] pszPassword
資格情報のパスワードを含む null で終わる文字列へのポインター。 pszPassword に長さ 0 以外の文字列を指定すると、ダイアログ ボックスの password オプションに文字列が事前に入力されます。
この関数は、ユーザー指定のパスワードをこのバッファーにコピーし、最大 ulPasswordMaxChars 文字をコピーします。 CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、 WNetAddConnection や SSP 関数などのクライアント側認証関数に渡す以外に検査、印刷、または永続化しないフォームです。
パスワードの使用が完了したら、 SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。 パスワードの保護の詳細については、「パスワードの 処理」を参照してください。
[in] ulPasswordBufferSize
pszPassword にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] save
[チェック保存] ボックスの初期状態を指定し、ユーザーがダイアログ ボックスに応答した後に [チェック保存] ボックスの状態を受け取る BOOL へのポインター。 この値が NULL ではなく、CredUIPromptForCredentials がNO_ERRORを返す場合、pfSave は、ユーザーがダイアログ ボックスで [OK] を選択したときに [チェック保存] ボックスの状態を返します。
CREDUI_FLAGS_PERSIST フラグを指定すると、[チェック保存] ボックスは表示されませんが、選択されていると見なされます。
CREDUI_FLAGS_DO_NOT_PERSIST フラグを指定し、CREDUI_FLAGS_SHOW_SAVE_CHECK_BOXが指定されていない場合、[チェック保存] ボックスは表示されませんが、クリアされたと見なされます。
CredUI を使用してユーザーに資格情報の入力を求める必要があるが、資格情報マネージャーによって提供される資格情報管理サービスは必要ないアプリケーションでは、pfSave を使用して、ユーザーがダイアログ ボックスを閉じる後に [チェック保存] ボックスの状態を受け取ることができます。 これを行うには、呼び出し元が dwFlags でCREDUI_FLAGS_DO_NOT_PERSISTとCREDUI_FLAGS_SHOW_SAVE_CHECK_BOXを指定する必要があります。 CREDUI_FLAGS_DO_NOT_PERSISTとCREDUI_FLAGS_SHOW_SAVE_CHECK_BOXが設定されている場合、アプリケーションは関数が戻った後に *pfSave を調べ、*pfSave が TRUE の場合は、アプリケーションのリソース内にユーザー資格情報を保存するための適切なアクションを実行する必要があります。
[in] dwFlags
この関数の特別な動作を指定する DWORD 値。 この値は、次の値の 0 個以上のビットごとの OR の組み合わせにすることができます。
| 値 | 意味 |
|---|---|
|
資格情報マネージャーの既存の資格情報から資格情報を返すことができる場合でも、ユーザー インターフェイスを表示することを指定します。 このフラグは、CREDUI_FLAGS_GENERIC_CREDENTIALSも指定されている場合にのみ許可されます。 |
|
コンボ ボックスにユーザー名のプロンプトを入力します。 |
|
資格情報を保存したり、チェックボックスを表示したりしないでください。 このフラグをCREDUI_FLAGS_SHOW_SAVE_CHECK_BOX渡すと、[チェック保存] ボックスのみが表示され、結果は pfSave 出力パラメーターに返されます。 |
|
コンボ ボックスにユーザー名/パスワードのみを入力します。 コンボ ボックスに証明書やスマート カードを表示しないでください。 |
|
返された資格情報が実際に有効かどうかを確認した後、呼び出し元 が CredUIConfirmCredentials を呼び出すように指定します。 このメカニズムにより、無効な資格情報が資格情報マネージャーに保存されないことが保証されます。 CREDUI_FLAGS_DO_NOT_PERSISTを指定しない限り、すべての場合にこのフラグを指定します。 |
|
ユーザーが入力した資格情報を汎用資格情報と考えてください。 |
|
"ログオンに失敗しました" バルーン ヒントを表示して、不十分な資格情報をユーザーに通知します。 |
|
指定されたユーザー名の変更をユーザーに許可しないでください。 |
|
コンボ ボックスにパスワードのみを入力します。 ユーザー名の入力を許可しないでください。 |
|
[チェック保存] ボックスは表示されませんが、資格情報はボックスが表示され選択されているかのように保存されます。 |
|
コンボ ボックスにローカル管理者のみを設定します。Windows XP Home Edition: このフラグは、既知の管理者アカウントを除外します。 |
|
コンボ ボックスに証明書とスマート カードのみを入力します。 ユーザー名の入力を許可しないでください。 |
|
コンボ ボックスに証明書またはスマート カードのみを入力します。 ユーザー名の入力を許可しないでください。 |
|
このフラグは、認証が失敗した場合に、ダイアログ ボックスを事前入力するために一致する資格情報を見つける場合にのみ意味があります。 このフラグを指定すると、ワイルドカード資格情報は一致しません。 資格情報を書き込む場合は無効です。 CredUI では、ワイルドカード文字を含む資格情報は作成されません。 見つかったものはすべて、RAS 接続が確立されたときに発生するように、ユーザーによって明示的に作成されたか、プログラムによって作成されました。 |
|
チェック ボックスが選択されている場合は、[チェック保存] ボックスを表示し、pfSave 出力パラメーターで TRUE を返します。それ以外の場合は FALSE を返します。 チェック ボックスでは、 pfSave の値が既定で使用されます。 |
|
資格情報は "runas" 資格情報です。 TargetName パラメーターは、実行するコマンドまたはプログラムの名前を指定します。 プロンプトの目的でのみ使用されます。 |
|
ユーザー名が有効であることを確認します。 |
戻り値
戻り値は DWORD で、次のいずれかの値を指定できます。
| 値 | 説明 |
|---|---|
|
ユーザーが [キャンセル] を選択しました。 pszUserName パラメーターと pszPassword パラメーターは変更されていません。 |
|
この状態は、無効なフラグ構成に対して返されます。 |
|
pszTargetName が NULL であるか、空の文字列であるか、CREDUI_MAX_DOMAIN_LENGTHより長いか、pUiInfo が NULL ではなく、指すCredUI_INFO構造体が次のいずれかの要件を満たしていません。
|
|
資格情報マネージャーを使用できません。 通常、このエラーは CredUIPromptForCredentials を 呼び出し、CREDUI_FLAGS_DO_NOT_PERSIST フラグを渡すことによって処理されます。 |
|
ユーザーが [OK] を選択しました。 pszUserName、pszPassword、および pfSave パラメーターは、前に説明した値を返します。 |
注釈
CredUIPromptForCredentials 関数は、アプリケーション モーダル ダイアログ ボックスを作成して表示します。 ダイアログ ボックスが表示され、ユーザーまたはアプリケーションによって閉じられるまで、アプリケーション内の他のウィンドウをアクティブにすることはできません。
フラグCREDUI_FLAGS_REQUIRE_SMARTCARD、CREDUI_FLAGS_REQUIRE_CERTIFICATE、およびCREDUI_FLAGS_EXCLUDE_CERTIFICATEは相互に排他的です。
CREDUI_FLAGS_DO_NOT_PERSISTを指定する場合は、pszTargetName を指定するか、uiInfo-pszMessageText> と uiInfo-pszCaption> を指定する必要があります。
フラグCREDUI_FLAG_USERNAME_TARGET_CREDENTIALSとCREDUI_FLAGS_GENERIC_CREDENTIALSは相互に排他的です。 どちらも指定しない場合、資格情報はドメイン資格情報です。
X509 証明書には、表示する 拡張キー使用法 (EKU) 値 が szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) である必要があります。
Windows XP: この EKU 値は、X509 証明書を表示するために必要ありません。
CREDUI_FLAGS_GENERIC_CREDENTIALSが指定されていない場合、またはCREDUI_FLAGS_COMPLETE_USERNAMEが指定されている場合は、型指定された名前が 構文チェックされます。 構文チェックでは、 CredUIParseUserName によって適用されるのと同じ規則が適用されます。 入力された名前が無効な場合、ユーザーは有効な名前の入力を求められます。 型指定された名前のドメイン部分が見つからない場合は、ターゲット名に基づいてドメインが指定されます。
CREDUI_FLAGS_GENERIC_CREDENTIALSを指定し、CREDUI_FLAGS_VALIDATE_USERNAMEも指定した場合は、型指定された名前が構文チェックされます。 入力された名前が無効な場合、ユーザーは有効な名前の入力を求められます。
CREDUI_FLAGS_GENERIC_CREDENTIALSが指定されていて、CREDUI_FLAGS_COMPLETE_USERNAMEもCREDUI_FLAGS_VALIDATE_USERNAMEも指定されていない場合、型指定された名前は構文チェックされません。
CREDUI_FLAGS_PERSISTもCREDUI_FLAGS_DO_NOT_PERSISTも設定されていない場合は、[保存チェック] ボックスが表示され、資格情報を保存するかどうかを制御します。
呼び出しモード
- 呼び出し元は、ターゲット リソースへのアクセス、credui の呼び出し (ターゲット リソースの説明とエラー状態の渡し)、 CredUIParseUserName の呼び出し、ターゲット リソースへの再度アクセス、 CredUIConfirmCredentials の呼び出しを試みます。
- 呼び出し元は、CREDUI_FLAGS_DO_NOT_PERSISTを渡すことによって、リソースにアクセスせずに資格情報の入力を求めることができます。
- 汎用資格情報の場合、認証パッケージはありません。 そのため、アプリケーションは認証を行うために資格情報にアクセスする必要があります。 最初の認証の前にCREDUI_FLAGS_ALWAYS_SHOW_UIを渡さないで、資格情報の入力を求めます。 ユーザー インターフェイスは、資格情報マネージャーに資格情報がない場合にのみ表示されます。 アプリケーション内からの後続のすべてのメッセージで、資格情報マネージャーの資格情報がそのリソースに対して明らかに無効であるため、CREDUI_FLAGS_ALWAYS_SHOW_UIが渡されます。
[ターゲット情報] は、アクセスするリソースの場所に関する情報です。 リソースのすべての潜在的なターゲット名の一覧については、 CredGetTargetInfo を呼び出します。 CredGetTargetInfo は、これらのパッケージの 1 つが名前付きターゲットに対する認証に使用されたときに、Negotiate、NTLM、または Kerberos 認証パッケージによってキャッシュされた情報を返します。 CredGetTargetInfo は、ターゲットの次の名前の一部またはすべてを返します。
- コンピューターの NetBIOS サーバー名
- コンピューターの DNS サーバー名
- コンピューターが属しているドメインの NetBIOS ドメイン名
- コンピューターが属しているドメインの DNS ドメイン名
- コンピューターが属しているツリーの DNS ツリー名
- 情報を収集したパッケージの名前
資格情報は、ターゲット名に基づいて資格情報マネージャーに格納されます。 各ターゲット名は、資格情報マネージャーに既に格納されている資格情報と照合することなく、可能な限り一般的に格納されます。 資格情報はターゲット名によって格納されるため、特定のユーザーは、資格情報マネージャーに格納されているターゲットごとに 1 つの資格情報のみを持つことができます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincred.h |
| Library | Credui.lib |
| [DLL] | Credui.dll |