次の方法で共有


CredUIPromptForCredentialsA 関数 (wincred.h)

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

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

  • CredUIPromptForWindowsCredentials は、現在の Windows ユーザー インターフェイスと一貫性があります。
  • CredUIPromptForWindowsCredentials は拡張性が高く、生体認証やスマート カードなどの追加の認証メカニズムを統合できます。
  • 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) 接続の場合、この文字列は ServerNameShareName形式です。 このパラメーターは、資格情報を格納および取得するときにターゲット情報を識別するために使用されます。

[in] pContext

このパラメーターは、将来使用するために予約されています。 これは NULLする必要があります。

[in, optional] dwAuthError

資格情報ダイアログ ボックスが必要な理由を指定します。 呼び出し元は、別の認証呼び出しによって返されるこの Windows エラー パラメーターを渡して、ダイアログ ボックスが特定のエラーに対応できるようにします。 たとえば、パスワードの有効期限が切れた状態コードが渡された場合、ダイアログ ボックスでユーザーにアカウントのパスワードの変更を求めるメッセージが表示される場合があります。

[in, out] pszUserName

資格情報のユーザー名を含む null で終わる文字列へのポインター。 0 以外の長さの文字列を渡すと、ダイアログ ボックスの UserName オプションに文字列が事前に入力されます。 UserName/Password以外の資格情報の場合は、資格情報のマーシャリング形式を渡すことができます。 この文字列は、credMarshalCredential呼び出すことによって作成されます。

この関数は、ユーザー指定の名前をこのバッファーにコピーし、最大 ulUserNameMaxChars 文字をコピーします。 この形式は、CredUIParseUsernameを使用して、UserName/Password 形式に変換できます。 マーシャリングされた形式は、セキュリティ サポート プロバイダー (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 以外の文字列 指定すると、ダイアログ ボックスのパスワード オプションに文字列が事前入力されます。

この関数は、ユーザーが指定したパスワードをこのバッファーにコピーし、最大 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 個以上のビットごとのまたは の組み合わせにすることができます。

価値 意味
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]選択しました。 pszUserNamepszPassword、および pfSave パラメーターは、前に説明した値を返します。

備考

CredUIPromptForCredentials 関数は、アプリケーション モーダル ダイアログ ボックスを作成して表示します。 ダイアログ ボックスが表示され、ユーザーまたはアプリケーションによってダイアログ ボックスが閉じられるまで、アプリケーション内の他のウィンドウをアクティブにすることはできません。

フラグCREDUI_FLAGS_REQUIRE_SMARTCARD、CREDUI_FLAGS_REQUIRE_CERTIFICATE、およびCREDUI_FLAGS_EXCLUDE_CERTIFICATEは相互に排他的です。

CREDUI_FLAGS_DO_NOT_PERSISTを指定する場合は、pszTargetName を指定するか、または uiInfo->pszMessageTextuiInfo->pszCaption を指定する必要があります。

フラグCREDUI_FLAG_USERNAME_TARGET_CREDENTIALSとCREDUI_FLAGS_GENERIC_CREDENTIALSは相互に排他的です。 どちらも指定されていない場合、資格情報はドメイン資格情報です。

X509 証明書には、szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.20.2.2) の 拡張キー使用法 (EKU) 値が表示されている必要があります。

Windows XP: X509 証明書を表示するためにこの EKU 値は必要ありません。

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 は、これらのパッケージのいずれかが名前付きターゲットに対する認証に使用されたときに、ネゴシエート、NTLM、または Kerberos 認証パッケージによってキャッシュされた情報を返します。 CredGetTargetInfo は、ターゲットの次の名前の一部またはすべてを返します。

  • コンピューターの NetBIOS サーバー名
  • コンピューターの DNS サーバー名
  • コンピューターが属しているドメインの NetBIOS ドメイン名
  • コンピューターが属しているドメインの DNS ドメイン名
  • コンピューターが属しているツリーの DNS ツリー名
  • 情報を収集したパッケージの名前
情報がターゲット コンピューターに適用されない場合、この情報の一部が見つからない可能性があります。 たとえば、ワークグループのメンバーであるコンピューターには、NetBIOS ドメイン名がありません。

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

手記

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

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー wincred.h
ライブラリ Credui.lib
DLL Credui.dll

関連項目

CredGetTargetInfo の

CredMarshalCredential

CredUIConfirmCredentials の

CredUIParseUserName

CredUIPromptForWindowsCredentials の

CredUI_INFO

WNetAddConnection の