Win32 API 日本語リファレンス
ホーム › UI.Shell › ICredentialProviderCredential

ICredentialProviderCredential

COM
📘 Microsoft Learn (日本語) · English
IID63913a93-40c1-481a-818d-4072ff8c70cc継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

資格情報を処理するためのメソッドを公開します。

解説(Remarks)

実装するタイミング

ICredentialProviderCredential は、ユーザー資格情報の入力を求めるログオン UI または資格情報 UI を提供する外部の関係者によって実装されます。このインターフェイスの実装なしにユーザータイルの列挙を行うことはできません。

資格情報プロバイダーのベストプラクティス

資格情報プロバイダーは、ログオンおよびロック解除の要求を完了するために、きわめて機密性の高いユーザーの秘密情報を扱います。ベストプラクティスとして、パスワードや PIN などの秘密情報は細心の注意を払って扱う必要があります。資格情報プロバイダー内で秘密情報を扱う適切な手法は次のとおりです。

メソッド 17

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Advise(ICredentialProviderCredentialEvents* pcpce)

コールバックインターフェイスを介して、資格情報がログオン UI または資格情報 UI 内でイベントを開始できるようにします。このメソッドは、ICredentialProviderCredential インターフェイスの他のメソッドよりも前に呼び出す必要があります。

pcpceICredentialProviderCredentialEvents*in通知メカニズムとして使用される ICredentialProviderCredentialEvents コールバックインターフェイスへのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは省略可能です。このメソッドを実装しない場合は、単に E_NOTIMPL を返してください。

このメソッドを実装する資格情報プロバイダーは、提供された ICredentialProviderCredentialEvents に対して AddRef を呼び出す責任があります。また、それらの資格情報プロバイダーは UnAdvise メソッド内で Release を呼び出す必要があります。

vtbl 4 HRESULT UnAdvise()

イベントコールバックがこれ以上受け付けられないことを資格情報に通知するために、ログオン UI または資格情報 UI によって使用されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは省略可能です。このメソッドを実装しない場合は、単に E_NOTIMPL を返してください。

このメソッドが呼び出された場合、Advise で提供された ICredentialProviderCredentialEvents ポインターがもはや有効でないことを示します。このメソッド内で、提供された ICredentialProviderCredentialEvents ポインターに対して Release を呼び出すのは資格情報プロバイダーの責任です。

vtbl 5 HRESULT SetSelected(BOOL* pbAutoLogon)

資格情報が選択されたときに呼び出されます。実装者がログオンの特性を設定できるようにします。

pbAutoLogonBOOL*outこのメソッドが返るとき、資格情報の選択が直ちに自動的にログオンを試みるべきであることを示す場合は TRUE、そうでない場合は FALSE を格納します。たとえば、パスワードのないアカウントを列挙する資格情報プロバイダーは、これを true として返したい場合があります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

S_OK 以外の値を返すと、ログオン UI および資格情報 UI は選択が行われなかったかのように動作します。

Windows 10 では、資格情報プロバイダーが、Windows が適切でないと判断する状況でユーザーを自動的にログオンさせようとした場合、システムは速度制限としてサインインボタンを表示します。その一例は、空のパスワードを持つユーザーがコンピューターをロックまたはサインアウトした場合です。そのシナリオでは、Windows はユーザーを直接ログオンし直しません。

vtbl 6 HRESULT SetDeselected()

資格情報が選択を失ったときに呼び出されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

資格情報プロバイダーは、このメソッドを使用して、パスワードや個人識別番号 (PIN) などの機密情報を含むすべてのバッファーをパージする必要があります。これは、それらを格納するクラスのデストラクターでパージすることに加えて行います。

vtbl 7 HRESULT GetFieldState(DWORD dwFieldID, CREDENTIAL_PROVIDER_FIELD_STATE* pcpfs, CREDENTIAL_PROVIDER_FIELD_INTERACTIVE_STATE* pcpfis)

フィールドの状態を取得します。ログオン UI および資格情報 UI はこれを使用して、資格情報のフィールドに関する情報を取得し、その情報をユーザータイルに表示します。

dwFieldIDDWORDinフィールドの識別子。
pcpfsCREDENTIAL_PROVIDER_FIELD_STATE*out資格情報プロバイダーのフィールド状態へのポインター。これは、フィールドをユーザータイルに表示するタイミングを示します。
pcpfisCREDENTIAL_PROVIDER_FIELD_INTERACTIVE_STATE*out資格情報プロバイダーのフィールドの対話状態へのポインター。これは、ユーザーがフィールドを操作できるタイミングを示します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 8 HRESULT GetStringValue(DWORD dwFieldID, LPWSTR* ppsz)

テキストフィールドを持つ資格情報からテキストを取得できるようにします。

dwFieldIDDWORDinフィールドの識別子。
ppszLPWSTR*outログオン UI または資格情報 UI に返す、null で終わる Unicode 文字列を含むメモリへのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは省略可能です。

ログオン UI および資格情報 UI は、このメソッドを使用してフィールドの pszLabel を取得します。この情報は、CPFT_LARGE_TEXT、CPFT_SMALL_TEXT、CPFT_COMMAND_LINK、CPFT_EDIT_TEXT、CPFT_PASSWORD_TEXT の各フィールドの値を取得するために必要です。

資格情報プロバイダーのベストプラクティス

資格情報プロバイダーは、ログオンおよびロック解除の要求を完了するために、きわめて機密性の高いユーザーの秘密情報を扱います。ベストプラクティスとして、パスワードや PIN などの秘密情報は細心の注意を払って扱う必要があります。資格情報プロバイダー内で秘密情報を扱う適切な手法は次のとおりです。
vtbl 9 HRESULT GetBitmapValue(DWORD dwFieldID, HBITMAP* phbmp)

ビットマップフィールドを持つ資格情報からビットマップデータを取得できるようにします。

dwFieldIDDWORDinフィールドの識別子。
phbmpHBITMAP*outビットマップのハンドルへのポインターを格納します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは省略可能です。

vtbl 10 HRESULT GetCheckboxValue(DWORD dwFieldID, BOOL* pbChecked, LPWSTR* ppszLabel)

チェックボックスの値を取得します。

dwFieldIDDWORDinフィールドの識別子。
pbCheckedBOOL*outチェックボックスの状態を示します。TRUE はチェックボックスがオンであることを示し、そうでない場合は FALSE です。
ppszLabelLPWSTR*outチェックボックスのラベルを指します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 11 HRESULT GetSubmitButtonValue(DWORD dwFieldID, DWORD* pdwAdjacentTo)

ログオン UI において送信ボタンを隣に配置すべきフィールドの識別子を取得します。

dwFieldIDDWORDin送信ボタンの値が必要なフィールドの識別子。
pdwAdjacentToDWORD*out

送信ボタンを隣に配置すべきフィールドのフィールド ID を受け取る値へのポインター。

実装者への注意: このパラメーターにビットマップのフィールド ID を返さないでください。送信ボタンをビットマップの隣に配置するのは良い UI 設計ではなく、そうすることでログオン UI で障害が発生する可能性があります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

送信ボタンにはそのようなラベルが付いているわけではありません。これは、資格情報を送信するためにクリックするボタンを指す一般的な呼び方にすぎません。このボタンは通常、右向きの矢印を含む円形のボタンとして表示されますが、この外観は今後のリリースで変更される可能性があります。詳細については、CPFT_SUBMIT_BUTTON を参照してください。

資格情報プロバイダーが常に自動送信を行う場合を除き、送信ボタンを非表示にしないでください。そうしないと、ユーザーは資格情報を送信する方法が見えなくなるため、混乱を招く可能性があります。

このメソッドは、ログオン UI を組み立てるときに呼び出します。使用例については、Windows Software Development Kit (SDK) に含まれる資格情報プロバイダーのサンプルを参照してください。

。

vtbl 12 HRESULT GetComboBoxValueCount(DWORD dwFieldID, DWORD* pcItems, DWORD* pdwSelectedItem)

指定されたコンボボックス内の項目数を取得し、どの項目を初期選択とするかを指定します。

dwFieldIDDWORDin情報を収集するコンボボックスの識別子。
pcItemsDWORD*out指定されたコンボボックス内の項目数へのポインター。
pdwSelectedItemDWORD*out初期選択を受け取る項目へのポインターを格納します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

資格情報 UI およびログオン UI は、このメソッドを使用してコンボボックス内の項目数を取得し、どの項目を初期選択とするかを指定します。

vtbl 13 HRESULT GetComboBoxValueAt(DWORD dwFieldID, DWORD dwItem, LPWSTR* ppszItem)

指定されたインデックスにあるコンボボックスのエントリの文字列ラベルを取得します。

dwFieldIDDWORDinクエリするコンボボックスの識別子。
dwItemDWORDin目的の項目のインデックス。
ppszItemLPWSTR*outコンボボックスのラベルを受け取る文字列値へのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 14 HRESULT SetStringValue(DWORD dwFieldID, LPWSTR psz)

ユーザーが入力するのに合わせて、ログオン UI または資格情報 UI が CPFT_EDIT_TEXT フィールドのテキストを更新できるようにします。

dwFieldIDDWORDin更新が必要なフィールドの識別子。
pszLPWSTRin新しいテキストを含むバッファーへのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは省略可能です。

資格情報プロバイダーのベストプラクティス

資格情報プロバイダーは、ログオンおよびロック解除の要求を完了するために、きわめて機密性の高いユーザーの秘密情報を扱います。ベストプラクティスとして、パスワードや PIN などの秘密情報は細心の注意を払って扱う必要があります。資格情報プロバイダー内で秘密情報を扱う適切な手法は次のとおりです。
vtbl 15 HRESULT SetCheckboxValue(DWORD dwFieldID, BOOL bChecked)

ログオン UI および資格情報 UI がチェックボックスの値が変更されたことを示せるようにします。

dwFieldIDDWORDin更新するフィールドの識別子。
bCheckedBOOLinチェックボックスの新しい値を示します。TRUE はチェックボックスをオンにすべきことを、FALSE はオフにすべきことを意味します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 16 HRESULT SetComboBoxSelectedValue(DWORD dwFieldID, DWORD dwSelectedItem)

ログオン UI および資格情報 UI がコンボボックスの値が選択されたことを示せるようにします。

dwFieldIDDWORDin影響を受けるコンボボックスの識別子。
dwSelectedItemDWORDin選択された具体的な項目。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 17 HRESULT CommandLinkClicked(DWORD dwFieldID)

ログオン UI および資格情報 UI がリンクがクリックされたことを示せるようにします。

dwFieldIDDWORDinクリックされたフィールドの識別子。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドには、資格情報プロバイダーがクリックに応答するために使用するロジックが含まれます。

vtbl 18 HRESULT GetSerialization(CREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE* pcpgsr, CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION* pcpcs, LPWSTR* ppszOptionalStatusText, CREDENTIAL_PROVIDER_STATUS_ICON* pcpsiOptionalStatusIcon)

この資格情報を基盤となる認証エンジンに送信しようとする試みに応じて呼び出されます。

pcpgsrCREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE*out資格情報をシリアル化する試みの成否を示します。
pcpcsCREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION*out資格情報へのポインター。結果によっては、有効な資格情報が存在しない場合があります。
ppszOptionalStatusTextLPWSTR*outシリアル化の後にログオン UI によって表示される Unicode 文字列値へのポインター。NULL でもかまいません。
pcpsiOptionalStatusIconCREDENTIAL_PROVIDER_STATUS_ICON*outGetSerialization の呼び出しが返った後に資格情報によって表示されるアイコンへのポインター。この値は NULL でもかまいません。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは必須です。

CREDENTIAL_PROVIDER_USAGE_SCENARIO は、ユーザーが資格情報を送信しようとしたときに適切な応答が何であるかを示します。次の表は、使用シナリオに基づいてどのように応答するかを示しています。

CPUS_CHANGE_PASSWORD このシナリオでは資格情報のシリアル化は行われません。このシナリオでは、資格情報プロバイダーはユーザーの個人情報を更新し、pcpgsr として CPGSR_NO_CREDENTIAL_FINISHED を返す必要があります。
CPUS_CREDUI 資格情報の情報はシリアル化され、呼び出し元のアプリケーションに配信される必要があります。
CPUS_LOGON、CPUS_UNLOCK_WORKSTATION 資格情報の情報はバイナリストリームにパックされ、Winlogon、最終的には LSA に送信される必要があります。

資格情報プロバイダーのベストプラクティス

資格情報プロバイダーは、ログオンおよびロック解除の要求を完了するために、きわめて機密性の高いユーザーの秘密情報を扱います。ベストプラクティスとして、パスワードや PIN などの秘密情報は細心の注意を払って扱う必要があります。資格情報プロバイダー内で秘密情報を扱う適切な手法は次のとおりです。
vtbl 19 HRESULT ReportResult(NTSTATUS ntsStatus, NTSTATUS ntsSubstatus, LPWSTR* ppszOptionalStatusText, CREDENTIAL_PROVIDER_STATUS_ICON* pcpsiOptionalStatusIcon)

受信したエラーステータスコードを適切なユーザーが読める形式のメッセージに変換します。

ntsStatusNTSTATUSinLsaLogonUser への Winlogon の呼び出しの戻り値を反映する NTSTATUS 値。
ntsSubstatusNTSTATUSinWinlogon によって呼び出された後に LsaLogonUser が返るときに、その SubStatus パラメーターが指す値を反映する NTSTATUS 値。
ppszOptionalStatusTextLPWSTR*outユーザーに表示されるエラーメッセージへのポインター。NULL でもかまいません。
pcpsiOptionalStatusIconCREDENTIAL_PROVIDER_STATUS_ICON*out資格情報に表示されるアイコンへのポインター。NULL でもかまいません。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドはログオン UI に必須です。

このメソッドは、ログオンの試みの結果を資格情報に報告するために使用されます。ntsStatus と ntsSubstatus の情報は、資格情報プロバイダーがカスタムエラーメッセージを生成したい場合にも使用できます。この呼び出しからのステータステキストは、選択された資格情報に表示されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_ICredentialProviderCredential "{63913A93-40C1-481A-818D-4072FF8C70CC}"
#usecom global ICredentialProviderCredential IID_ICredentialProviderCredential "{}"
#comfunc global ICredentialProviderCredential_Advise                    3 sptr
#comfunc global ICredentialProviderCredential_UnAdvise                  4
#comfunc global ICredentialProviderCredential_SetSelected               5 var
#comfunc global ICredentialProviderCredential_SetDeselected             6
#comfunc global ICredentialProviderCredential_GetFieldState             7 int,var,var
#comfunc global ICredentialProviderCredential_GetStringValue            8 int,var
#comfunc global ICredentialProviderCredential_GetBitmapValue            9 int,sptr
#comfunc global ICredentialProviderCredential_GetCheckboxValue          10 int,var,var
#comfunc global ICredentialProviderCredential_GetSubmitButtonValue      11 int,var
#comfunc global ICredentialProviderCredential_GetComboBoxValueCount     12 int,var,var
#comfunc global ICredentialProviderCredential_GetComboBoxValueAt        13 int,int,var
#comfunc global ICredentialProviderCredential_SetStringValue            14 int,wstr
#comfunc global ICredentialProviderCredential_SetCheckboxValue          15 int,int
#comfunc global ICredentialProviderCredential_SetComboBoxSelectedValue  16 int,int
#comfunc global ICredentialProviderCredential_CommandLinkClicked        17 int
#comfunc global ICredentialProviderCredential_GetSerialization          18 var,var,var,var
#comfunc global ICredentialProviderCredential_ReportResult              19 int,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。