CredUIPromptForCredentialsA 関数 (wincred.h)

  • [アーティクル]

CredUIPromptForCredentials 関数は、ユーザーからの資格情報を受け入れる構成可能なダイアログ ボックスを作成して表示します。

次の理由から、Windows Vista または Windows Server 2008 を対象とするアプリケーションでは、この関数の代わりに CredUIPromptForWindowsCredentials を呼び出す必要があります。

構文

CREDUIAPI DWORD CredUIPromptForCredentialsA(
  [in, optional] PCREDUI_INFOA pUiInfo,
  [in]           PCSTR         pszTargetName,
  [in]           PCtxtHandle   pContext,
  [in, optional] DWORD         dwAuthError,
  [in, out]      PSTR          pszUserName,
  [in]           ULONG         ulUserNameBufferSize,
  [in, out]      PSTR          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 文字を含む)。

メモ CREDUI_MAX_USERNAME_LENGTHには、終端の null 文字は含まれません。
 

[in, out] pszPassword

資格情報のパスワードを含む null で終わる文字列へのポインター。 pszPassword に長さ 0 以外の文字列を指定すると、ダイアログ ボックスの password オプションに文字列が事前に入力されます。

この関数は、ユーザー指定のパスワードをこのバッファーにコピーし、最大 ulPasswordMaxChars 文字をコピーします。 CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、 WNetAddConnection や SSP 関数などのクライアント側認証関数に渡す以外に検査、印刷、または永続化すべきではない形式になります。

パスワードの使用が完了したら、 SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。 パスワードの保護の詳細については、「パスワードの 処理」を参照してください。

[in] ulPasswordBufferSize

pszPassword にコピーできる最大文字数 (終端の null 文字を含む)。

メモ CREDUI_MAX_PASSWORD_LENGTHには、終端の 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_ALWAYS_SHOW_UI
0x00080
 資格情報マネージャーの既存の資格情報から資格情報を返すことができる場合でも、ユーザー インターフェイスを表示することを指定します。 このフラグは、CREDUI_FLAGS_GENERIC_CREDENTIALSも指定されている場合にのみ許可されます。
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
 コンボ ボックスにユーザー名のプロンプトを入力します。
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
 資格情報を保存したり、チェックボックスを表示したりしないでください。 このフラグをCREDUI_FLAGS_SHOW_SAVE_CHECK_BOX渡すと、[チェック保存] ボックスのみが表示され、結果は pfSave 出力パラメーターに返されます。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
 コンボ ボックスにユーザー名/パスワードのみを入力します。 コンボ ボックスに証明書やスマート カードを表示しないでください。
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
 返された資格情報が実際に有効かどうかを確認した後、呼び出し元 が CredUIConfirmCredentials を呼び出すように指定します。 このメカニズムにより、無効な資格情報が資格情報マネージャーに保存されないことが保証されます。 CREDUI_FLAGS_DO_NOT_PERSISTが指定されていない限り、すべてのケースでこのフラグを指定します。
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
 ユーザーが入力した資格情報を汎用資格情報と見なします。
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
 "ログオンに失敗しました" バルーン ヒントを表示して、不十分な資格情報をユーザーに通知します。
CREDUI_FLAGS_KEEP_USERNAME
0x100000
 指定されたユーザー名の変更をユーザーに許可しないでください。
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
 コンボ ボックスにパスワードのみを入力します。 ユーザー名の入力を許可しないでください。
CREDUI_FLAGS_PERSIST
0x01000
 [チェック保存] ボックスは表示されませんが、資格情報はボックスが表示され、選択されているかのように保存されます。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
 コンボ ボックスにローカル管理者のみを設定します。Windows XP Home Edition: このフラグは、既知の管理者アカウントを除外します。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
 コンボ ボックスに証明書とスマート カードのみを入力します。 ユーザー名の入力を許可しないでください。
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
 コンボ ボックスに証明書またはスマート カードのみを入力します。 ユーザー名の入力を許可しないでください。
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
 このフラグは、認証が失敗した場合に、ダイアログ ボックスを事前入力するために一致する資格情報を見つける場合にのみ意味があります。 このフラグを指定すると、ワイルドカード資格情報は一致しません。 資格情報を書き込む場合は無効です。 CredUI では、ワイルドカード文字を含む資格情報は作成されません。 見つかったものはすべて、RAS 接続が確立されたときに発生するように、ユーザーによって明示的に作成されたか、プログラムによって作成されました。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
 チェック ボックスが選択されている場合は、[チェック保存] ボックスを表示し、pfSave 出力パラメーターで TRUE を返します。それ以外の場合は FALSE を返します。 チェック ボックスでは、 pfSave の値が既定で使用されます。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
 資格情報は "runas" 資格情報です。 TargetName パラメーターは、実行するコマンドまたはプログラムの名前を指定します。 プロンプトの目的でのみ使用されます。
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
 ユーザー名が有効であることを確認します。

戻り値

戻り値は DWORD で、次のいずれかの値を指定できます。

値 説明
ERROR_CANCELLED
 ユーザーが [キャンセル] を選択しました。 pszUserName パラメーターと pszPassword パラメーターは変更されていません。
ERROR_INVALID_FLAGS
 この状態は、無効なフラグ構成に対して返されます。
ERROR_INVALID_PARAMETER
 pszTargetName が NULL であるか、空の文字列であるか、CREDUI_MAX_DOMAIN_LENGTHより長いか、pUiInfo が NULL ではなく、指すCredUI_INFO構造体が次のいずれかの要件を満たしていません。
  • cbSize メンバーは 1 である必要があります。
  • hbmBanner メンバーが NULL でない場合は、OBJ_BITMAP型である必要があります。
  • pszMessageText メンバーが NULL でない場合は、CREDUI_MAX_MESSAGE_LENGTHより大きくすることはできません。
  • pszCaptionText メンバーが NULL でない場合は、CREDUI_MAX_CAPTION_LENGTHより大きくすることはできません。
ERROR_NO_SUCH_LOGON_SESSION
 資格情報マネージャーを使用できません。 通常、このエラーは CredUIPromptForCredentials を 呼び出し、CREDUI_FLAGS_DO_NOT_PERSIST フラグを渡すことによって処理されます。
NO_ERROR
 ユーザーが [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 ツリー名
  • 情報を収集したパッケージの名前
情報がターゲット コンピューターに適用されない場合、この情報の一部が見つからない可能性があります。 たとえば、ワークグループのメンバーであるコンピューターには NetBIOS ドメイン名がありません。

資格情報は、ターゲット名に基づいて資格情報マネージャーに格納されます。 各ターゲット名は、資格情報マネージャーに既に格納されている資格情報と照合することなく、可能な限り一般的に格納されます。 資格情報はターゲット名によって格納されるため、特定のユーザーは、資格情報マネージャーに格納されているターゲットごとに 1 つの資格情報のみを持つことができます。

注意

wincred.h ヘッダーは CredUIPromptForCredentials をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー wincred.h
Library Credui.lib
[DLL] Credui.dll

こちらもご覧ください

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection