ICredentialProviderCredential2

ICredentialProviderCredential インターフェイスを拡張し、ユーザーのセキュリティ識別子 (SID) を取得するメソッドを追加します。この資格情報は当該ユーザーに関連付けられ、そのユーザーのタイルの下にグループ化できます。

このクラスは V2 資格情報プロバイダーを作成するために必要です。V2 資格情報プロバイダーは、ユーザーに対してパーソナライズされたサインオン エクスペリエンスを提供します。これは、資格情報プロバイダーがログオン UI に対して、あるユーザーに利用可能なサインイン オプションを伝えることで実現されます。新しい資格情報プロバイダーは V2 資格情報プロバイダーとして作成することを推奨します。

ICredentialProviderCredential2 インスタンスを作成するには、GetUserSid 関数によって有効な SID が返される必要があります。ここでいう「有効」とは、返された SID が現在ログオン UI によって列挙されているユーザーのいずれかに対応するものであることを意味します。

利用可能なユーザーを取得し、どのユーザーと関連付けるかを判断するのに便利なツールが ICredentialProviderUserArray オブジェクトです。このオブジェクトには、列挙対象となるユーザーに関する情報を照会できる ICredentialProviderUser オブジェクトのリストが含まれています。たとえば、GetStringValue に PKEY_Identity_PrimarySid または PKEY_Identity_USerName をパラメーターとして渡すことで、それぞれユーザーの SID またはユーザー名を取得できます。さらに SetProviderFilter を使用して結果をフィルターし、利用可能なユーザーの一部のみを表示することもできます。

ICredentialProviderUserArray の使用は任意ですが、有効な SID 値を作成するために必要な情報を取得する便利な方法です。ログオン UI によって列挙されるユーザーのリストを取得するには、ICredentialProviderSetUserArray インターフェイスを実装し、SetUserArray から ICredentialProviderUserArray オブジェクトを取得します。ログオン UI は GetCredentialCount の前に SetUserArray を呼び出すため、資格情報プロバイダーが資格情報を返そうとする時点で ICredentialProviderUserArray オブジェクトは準備完了しています。

V2 資格情報プロバイダーは、「サインイン オプション」リンクの下に表示されるアイコンで表現されます。資格情報プロバイダーにアイコンを提供するには、資格情報自体の中で CPFT_TILE_IMAGE の CREDENTIAL_PROVIDER_FIELD_TYPE を定義します。その上で、CREDENTIAL_PROVIDER_FIELD_DESCRIPTOR の guidFieldType が CPFG_CREDENTIAL_PROVIDER_LOGO に設定されていることを確認してください。アイコンの推奨サイズは 72 × 72 ピクセルです。

資格情報プロバイダーのアイコンを指定するのと同様に、資格情報プロバイダーを識別するためのテキスト文字列を指定することもできます。この文字列は、ユーザーがアイコンにマウス ポインターを合わせたときにポップアップ ウィンドウに表示されます。これを行うには、資格情報自体の中で CPFT_SMALL_TEXT の CREDENTIAL_PROVIDER_FIELD_TYPE を定義します。その上で、CREDENTIAL_PROVIDER_FIELD_DESCRIPTOR の guidFieldType が CPFG_CREDENTIAL_PROVIDER_LABEL に設定されていることを確認してください。この文字列は前述の資格情報プロバイダー アイコンを補完するものであり、ユーザーがそれが何であるかを理解できる程度に説明的である必要があります。たとえば、ピクチャ パスワード プロバイダーの説明は「ピクチャ パスワード」です。

実装するタイミング

この資格情報に関連付けられているユーザーのセキュリティ識別子 (SID) を取得します。

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

ログオン UI は、このメソッドから返された SID を使用して、資格情報タイルをユーザー タイルに関連付けます。資格情報をログオン UI の「他のユーザー」ユーザー タイルに関連付けるには、このメソッドは S_FALSE と null の SID を返す必要があります。「他のユーザー」タイルは通常、PC がドメインに参加している場合にのみ有効です。

例

次の例は、このメソッドの実装例を示しています。資格情報に対応するユーザーの SID を取得します。

ここで使用している _pszUserSid 変数は、このメソッドの外部で定義され、ユーザーの SID が設定されたクラスのプライベート メンバーであることを前提としています。

ppszSid が指すリソースはログオン UI によって解放されるため、ここで解放する必要はありません。

ユーザーの SID が利用できない場合、このメソッドは S_FALSE と null の SID を返し、資格情報を匿名ユーザー タイルに関連付けます。これにより、ドメインに参加している PC で「他のユーザー」タイルが選択されたときにタイルが表示されます。

// 資格情報に対応するユーザーの SID を取得します。
HRESULT CSampleCredential::GetUserSid(__deref_out PWSTR *ppszSid) 
{
    *ppszSid = nullptr;
    HRESULT hr = E_UNEXPECTED;

    // _pszUserSid は CSampleCredential のプライベート メンバーです
    if (_pszUserSid != nullptr)
    {
        // ppszSid はログオン UI によって解放されます
        hr = SHStrDupW(_pszUserSid, ppszSid);
    }
    // 資格情報を匿名ユーザー タイルに関連付けるには、
    // ppszSid に null の SID を設定して S_FALSE を返します。
    else if (_fIsOtherUserTile)
    {
        hr = S_FALSE;
    }

    return hr;
}