ICredentialProvider

資格情報プロバイダーのセットアップと操作に使用されるメソッドを公開します。すべての資格情報プロバイダーはこのインターフェイスを実装する必要があります。

このインターフェイスは、アプリケーション用の Logon UI および Credential UI とやり取りするための手段です。

インスタンス化された資格情報プロバイダーは、Logon UI の存続期間全体にわたって保持されます。このため、Logon UI は資格情報プロバイダーの状態を保持できます。特に、どのプロバイダーとタイルが資格情報を提供したかを記憶します。つまり、CREDENTIAL_PROVIDER_USAGE_SCENARIO が CPUS_LOGON、CPUS_UNLOCK_WORKSTATION、CPUS_CHANGE_PASSWORD の場合には、状態情報を保存できる可能性があります。Credential UI ではこれは当てはまりません。Credential UI は、アプリケーションが CredUIPromptForWindowsCredentials を呼び出すたびに、プロバイダーの新しいインスタンスを作成します。このため、Credential UI は資格情報プロバイダーの状態を記憶できません。

あるシナリオで生成された CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION が保存され、後続の使用シナリオで使用される可能性があることに注意してください。このため、ICredentialProvider の実装がこのシナリオを処理できるだけの堅牢性を備えていることを確認する必要があります。

Windows 8 では、資格情報プロバイダー API に新機能が追加されており、主にユーザーごとに資格情報をグループ化する機能があります。

資格情報プロバイダーが有効となるシナリオを定義します。資格情報プロバイダーが初期化されるたびに呼び出されます。

型: HRESULT

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

このメソッドは必須であり、資格情報プロバイダーが自身の使用方法を示すことを可能にします。

呼び出しは完了したものの要求された使用シナリオがサポートされていない場合、このメソッドは E_NOTIMPL を返す必要があります。メソッドが成功し使用シナリオがサポートされている場合は、S_OK を返す必要があります。

資格情報プロバイダーのシリアル化特性を設定します。

型: HRESULT

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

このメソッドは必須です。資格情報を受け取り、pcpcs が部分的な資格情報であったか完全な資格情報であったかを判断します。部分的な資格情報の場合、不完全であるか、ユーザーに何らかの情報を表示する目的で渡されたものです。完全な資格情報の場合は、シリアル化して送信する必要があります。入力の処理方法を判断するには、CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION のメンバーと、SetUsageScenario で渡されたフラグを使用します。入力の整合性を検証する責任は資格情報プロバイダーにあります。Credential UI と Logon UI は、構造体を資格情報プロバイダーに渡す前にチェックを一切行いません。

SetSerialization は常に SetUsageScenario の後に呼び出されます。Logon UI は、フィルターが UpdateRemoteCredential を通じて資格情報を返したときにも SetSerialization を呼び出します。CredentialsChanged の呼び出しによってタイルを再列挙する場合には、このメソッドは使用しません。Credential UI は、アプリケーションによって入力資格情報が提供されたときに SetSerialization を呼び出します。

Credential UI は、SetUsageScenario が呼び出されたときに定義された、このコンテンツプロバイダーインスタンスの dwFlags に基づいて次のルールを適用します。

• フラグに CREDUIWIN_IN_CRED_ONLY が含まれる場合、S_OK を返すすべての資格情報プロバイダーが有効になります。
• フラグに CREDUIWIN_AUTHPACKAGE_ONLY が含まれる場合、成功ステータスを返すすべての資格情報プロバイダーが有効になります。
• これらのフラグのいずれも含まれない場合、Credential UI は Logon UI と同じロジックに従い、CREDENTIAL_PROVIDER_USAGE_SCENARIO の CPUS_REDUI を実装するすべての資格情報プロバイダーが、返されるステータス値に関係なく有効になります。

CREDENTIAL_PROVIDER_USAGE_SCENARIO の CPUS_LOGON を実装し、このメソッドから失敗を返す資格情報プロバイダーも、引き続き有効になります。

資格情報プロバイダーが、コールバックインターフェイスを通じて Logon UI または Credential UI 内でイベントを開始できるようにします。

型: HRESULT

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

このメソッドは実装する必要はなく、実装しない場合は E_NOTIMPL を返す必要があります。Logon UI や Credential UI が変更や更新を一切行わない場合など、このメソッドを呼び出す理由がないこともあります。

このメソッドにより、Logon UI と Credential UI は ICredentialProviderEvents ポインターを資格情報プロバイダーに渡すことができます。これにより、資格情報プロバイダーは Logon UI または Credential UI と非同期のコールバック通信を行えます。たとえば、スマートカードプロバイダーは、新しいスマートカードが挿入されたときに資格情報を再度列挙したい場合があります。Logon UI に資格情報を再取得させるには、資格情報プロバイダーは upAdviseContext 識別子を指定して CredentialsChanged を呼び出す必要があります。

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

Logon UI または Credential UI が、イベントコールバックを受け付けなくなったことを資格情報プロバイダーに通知するために使用します。

型: HRESULT

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

このメソッドは実装する必要はなく、実装しない場合は E_NOTIMPL を返す必要があります。Logon UI や Credential UI が変更や更新を一切行わない場合など、このメソッドを呼び出す理由がないこともあります。

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

このプロバイダーの資格情報を表示するために必要なフィールドの数を取得します。

型: HRESULT

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

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

このメソッドで提供される数は、使用シナリオ全体を通じて有効である必要があります。つまり、非表示のフィールドや特別な状況でのみ表示されるフィールドを含め、すべてのフィールドを含める必要があります。この値は使用シナリオ中に変更できず、プロバイダーに対して新しい SetUsageScenario 呼び出しが行われたとき、または ICredentialProviderEvents インスタンスが別の列挙を強制したときにのみ変更できます。

指定したフィールドを記述するメタデータを取得します。

型: HRESULT

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

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

この資格情報プロバイダーで利用可能な資格情報の数を取得します。

型: HRESULT

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

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

Logon UI または Credential UI がユーザー操作の準備が整うと、既定で 1 つの資格情報が選択されます。各資格情報プロバイダーは既定の資格情報を提供するため、次のルールによって pdwDefault がフォーカスを受け取るか、資格情報が自動的にログインされるかが決まります。

• 既定の資格情報が既に指定されており、その資格情報が自動ログオンに使用することを意図しておらず、かつ pdwDefault が自動ログオンに使用される場合は、pdwDefault が既定として使用されます。
• pdwDefault が最後にログオンしたプロバイダーによるものであり、自動ログオン付きの既定がまだ存在しない場合は、pdwDefault が既定として使用されます。
• 既定が指定されていない場合は、pdwDefault が既定として使用されます。

有効な資格情報の数が変化した場合、資格情報プロバイダーは Advise で提供された ICredentialProviderEvents インスタンスに対して CredentialsChanged を呼び出す必要があります。

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

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

• 秘密情報は常に安全に破棄します。そのためには、秘密情報を保持するために使用したメモリを解放する前に SecureZeroMemory を呼び出します。
• 秘密情報は使用後速やかに安全に破棄します。
• 秘密情報が想定される時間内に本来の目的で使用されない場合は、安全に破棄します。

特定の資格情報を取得します。

型: HRESULT

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

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

利用可能な資格情報の数は ICredentialProvider::GetCredentialCount で取得します。このメソッドは、Logon UI または Credential UI が GetCredentialCount と組み合わせて資格情報を列挙するために使用します。

#define global IID_ICredentialProvider "{D27C3481-5A1C-45B2-8AAA-C20EBBE8229E}"
#usecom global ICredentialProvider IID_ICredentialProvider "{}"
#comfunc global ICredentialProvider_SetUsageScenario         3 int,int
#comfunc global ICredentialProvider_SetSerialization         4 var
#comfunc global ICredentialProvider_Advise                   5 sptr,sptr
#comfunc global ICredentialProvider_UnAdvise                 6
#comfunc global ICredentialProvider_GetFieldDescriptorCount  7 var
#comfunc global ICredentialProvider_GetFieldDescriptorAt     8 int,var
#comfunc global ICredentialProvider_GetCredentialCount       9 var,var,var
#comfunc global ICredentialProvider_GetCredentialAt          10 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。