Windows Hello コンパニオン (IoT) デバイスを使った Windows のロック解除Windows Unlock with Windows Hello companion (IoT) devices

Windows Hello コンパニオン デバイスは、ユーザー認証のエクスペリエンスを強化するために、Windows 10 のデスクトップと組み合わせて使用できるデバイスです。A Windows Hello companion device is a device that can act in conjunction with your Windows 10 desktop to enhance the user authentication experience. Windows Hello コンパニオン デバイス フレームワークを使用すると、コンパニオン デバイスは、生体認証を利用できない場合 (たとえば、Windows 10 のデスクトップに顔認証のカメラまたは指紋リーダーのデバイスがない場合など) でも、Windows Hello のための優れたエクスペリエンスを提供できます。Using the Windows Hello companion device framework, a companion device can provide a rich experience for Windows Hello even when biometrics are not available (e.g., if the Windows 10 desktop lacks a camera for face authentication or fingerprint reader device, for example).

Microsoft に Windows こんにちはコンパニオン デバイス フレームワーク 2020年の前半での API は非推奨化します。Note Microsoft will be deprecating the API for the Windows Hello companion device framework in the first half of 2020.

注: Windows Hello コンパニオン デバイス フレームワークは特別な機能です。すべてのアプリ開発者が利用できるわけではありません。Note The Windows Hello companion device framework is a specialized feature not available to all app developers. このフレームワークを使用するには、アプリが Microsoft によって明確にプロビジョニングされ、制限された secondaryAuthenticationFactor 機能がアプリ マニフェストに含まれている必要があります。To use this framework, your app must be specifically provisioned by Microsoft and list the restricted secondaryAuthenticationFactor capability in its manifest. 承認を得るには、cdfonboard@microsoft.com にお問い合わせください。To obtain approval, contact cdfonboard@microsoft.com.

概要Introduction

概要については、Channel 9 で Build 2016 の「Windows Unlock with IoT Devices」をご覧ください。For a video overview, see the Windows Unlock with IoT Devices session from Build 2016 on Channel 9.

コード サンプルについては、Windows Hello コンパニオン デバイス フレームワークの GitHub リポジトリをご覧ください。For code samples, see the Windows Hello companion device framework Github repository.

使用事例Use cases

さまざまな方法で Windows Hello コンパニオン デバイス フレームワークを使用して、コンパニオン デバイスによる優れた Windows のロック解除エクスペリエンスを構築できます。There are numerous ways one can use the Windows Hello companion device framework to build a great Windows unlock experience with a companion device. たとえば、ユーザーは、次のことを実行できます。For example, users could:

  • コンパニオン デバイスを USB 経由で PC に接続し、コンパニオン デバイスのボタンにタッチすると、PC のロックが自動的に解除されます。Attach their companion device to PC via USB, touch the button on the companion device, and automatically unlock their PC.
  • PC と Bluetooth でペアリング済みの電話を携帯します。Carry a phone in their pocket that is already paired with PC over Bluetooth. PC の Space キーを押すと、電話が通知を受信します。Upon hitting the spacebar on their PC, their phone receives a notification. 通知を承認するだけで、PC のロックが解除されます。Approve it and the PC simply unlocks.
  • NFC リーダーにコンパニオン デバイスをタップすると、PC のロックがすぐに解除されます。Tap their companion device to an NFC reader to quickly unlock their PC.
  • ユーザーの認証を完了しているフィットネス バンドを装着します。Wear a fitness band that has already authenticated the wearer. PC に近づいて特別なジェスチャ (拍手など) を実行すると、PC のロックが解除されます。Upon approaching PC, and by performing a special gesture (like clapping), the PC unlocks.

生体認証対応 Windows Hello コンパニオン デバイスBiometric enabled Windows Hello companion devices

コンパニオン デバイスが生体認証をサポートしている場合は、Windows Hello コンパニオン デバイス フレームワークよりも Windows 生体認証フレームワークの方が効果的なことがあります。If the companion device supports biometrics, in some cases the Windows Biometric framework may be a better solution than the Windows Hello companion device framework. 適切なアプローチについては、cdfonboard@microsoft.com にお問い合わせください。Please contact cdfonboard@microsoft.com and we'll help you pick the right approach.

ソリューションのコンポーネントComponents of the solution

次の図は、ソリューションのコンポーネントと、各コンポーネントの作成元を示しています。The diagram below depicts the components of the solution and who is responsible for building them.

フレームワークの概要

Windows Hello コンパニオン デバイス フレームワークは、Windows で実行されるサービスとして実装されます (この記事では Companion Authentication Service と呼びます)。The Windows Hello companion device framework is implemented as a service running on Windows (called the Companion Authentication Service in this article). このサービスは、Windows Hello コンパニオン デバイスに保存される HMAC キーによって保護する必要があるロック解除トークンを生成します。This service is responsible for generating an unlock token which needs to be protected by an HMAC key stored on the Windows Hello companion device. これにより、ロック解除トークンにアクセスするには、Windows Hello コンパニオン デバイスが必ず必要になります。This guarantees that access to the unlock token requires Windows Hello companion device presence. 組 (PC、Windows ユーザー) ごとに、一意のロック解除トークンがあります。Per each (PC, Windows user) tuple, there will be a unique unlock token.

Windows Hello コンパニオン デバイス フレームワークとの統合には、以下が必要です。Integration with the Windows Hello Companion Device Framework requires:

  • コンパニオン デバイス用のユニバーサル Windows プラットフォーム (UWP) Windows Hello コンパニオン デバイス アプリ。Windows アプリ ストアからダウンロードできます。A Universal Windows Platform (UWP) Windows Hello companion device app for the companion device, downloaded from the Windows app store.
  • 2 つの 256 ビットの HMAC キーを Windows Hello コンパニオン デバイス上に作成し、HMAC を (SHA-256 を使用して) 生成する能力。The ability to create two 256 bit HMAC keys on the Windows Hello companion device and generate HMAC with it (using SHA-256).
  • 適切に構成された Windows 10 デスクトップのセキュリティ設定。Security settings on the Windows 10 desktop properly configured. Companion Authentication Service では、Windows Hello コンパニオン デバイスが接続される前に PIN が設定されている必要があります。The Companion Authentication Service will require this PIN to be set up before any Windows Hello companion device can be plugged into it. ユーザーは、[設定]、[アカウント]、[サインイン オプション] の順に移動して、PIN を設定する必要があります。The users must set up a PIN via Settings > Accounts > Sign-in options.

上記の要件に加え、Windows Hello コンパニオン デバイス アプリは、次のことに対して責任を負います。In addition to the above requirements, the Windows Hello companion device app is responsible for:

  • 初回登録のユーザー エクスペリエンスとブランディング、およびその後の Windows Hello コンパニオン デバイスの登録解除。User experience and branding of initial registration and later de-registration of the Windows Hello companion device.
  • バック グラウンドで実行、Windows Hello コンパニオン デバイスの検出、Windows Hello コンパニオン デバイスおよび Companion Authentication Service との通信。Running in the background, discovering the Windows Hello companion device, communicating to the Windows Hello companion device and also Companion Authentication Service.
  • エラー処理Error handling

通常、コンパニオン デバイスには、フィットネス バンドの初回の設定などを実行するための初期セットアップ用のアプリが付属します。Normally, companion devices ship with an app for initial setup, like setting up a fitness band for the first time. このドキュメントに記載されている機能は、そのアプリの一部にすることができ、別のアプリは必要ありません。The functionality described in this document can be part of that app and a separate app should not be required.

ユーザー シグナルUser signals

各 Windows Hello コンパニオン デバイスは、3 種類のユーザー シグナルをサポートするアプリと組み合わせる必要があります。Each Windows Hello companion device should be combined with an app that supports three user signals. これらのシグナルは、操作またはジェスチャの形を取ることができます。These signals can be in form of an action or gesture.

  • インテント信号:により、目的のロックを解除、デバイスをコンパニオンで、Windows Helloのボタンを押すなどを表示できます。Intent signal: Allows the user to show his intent for unlock by, for example, hitting a button on the Windows Hello companion device. インテント シグナルは、Windows Hello コンパニオン デバイス側で収集する必要があります。The intent signal must be collected on Windows Hello companion device side.
  • ユーザーのプレゼンス信号:ユーザーのプレゼンスを証明します。User presence signal: Proves the presence of the user. Windows Hello コンパニオン デバイスを使用して PC のロックを解除するには、その前に PIN (PC の PIN と混同しないでください) が必要になることがあります。または、ボタンの押下が必要な場合があります。The Windows Hello companion device might, for instance, require a PIN before it can be used for unlocking PC (not to be confused with PC PIN), or it might require press of a button.
  • 曖昧性除去信号:Windows 10 デスクトップ、ユーザーが複数のオプションが Windows Hello コンパニオン デバイスで使用できるときにロックを解除するあいまいさを解消します。Disambiguation signal: Disambiguates which Windows 10 desktop the user wants to unlock when multiple options are available to the Windows Hello companion device.

任意の数のユーザー シグナルを 1 つに組み合わせることができます。Any number of these user signals can be combined into one. ユーザー プレゼンス シグナルとインテント シグナルは、毎回の使用時に必要です。User presence and intent signals must be required on each use.

登録および登録後の PC と Windows Hello コンパニオン デバイス間の通信Registration and future communication between a PC and Windows Hello companion devices

Windows Hello コンパニオン デバイスは、Windows Hello コンパニオン デバイス フレームワークに接続する前に、フレームワークに登録する必要があります。Before a Windows Hello companion device can be plugged into the Windows Hello companion device framework, it needs to be registered with the framework. 登録エクスペリエンスは、Windows Hello コンパニオン デバイス アプリがすべて管理します。The experience for registration is completely owned by the Windows Hello companion device app.

Windows Hello コンパニオン デバイスと Windows 10 デスクトップ デバイスは、1 対多の関係にできます (つまり、1 台のコンパニオン デバイスを、多数の Windows 10 デスクトップ デバイスで使用できます)。The relationship between the Windows Hello companion device and the Windows 10 desktop device can be one to many (i.e., one companion device can be used for many Windows 10 desktop devices). ただし、各 Windows Hello コンパニオン デバイスは、Windows 10 デスクトップ デバイスごとに 1 人のユーザーのみが使用できます。However, each Windows Hello companion device can only be used for one user on each Windows 10 desktop device.

Windows Hello コンパニオン デバイスは、PC と通信する前に、使用するトランスポートに関して合意する必要があります。Before a Windows Hello companion device can communicate with a PC, they need to agree on a transport to use. その選択肢は Windows Hello コンパニオン デバイス アプリに任されています。Windows Hello コンパニオン デバイス フレームワークによって、Windows Hello コンパニオン デバイスと Windows 10 デスクトップ デバイス側の Windows Hello コンパニオン デバイス アプリの間で使用される、トランスポートの種類 (USB、NFC、WiFi、BT、BLE など) またはプロトコルが制限されることはありません。Such choice is left to the Windows Hello companion device app; the Windows Hello companion device framework does not impose any limitations on transport type (USB, NFC, WiFi, BT, BLE, etc) or protocol being used between the Windows Hello companion device and the Windows Hello companion device app on the Windows 10 desktop device side. ただし、トランスポート層のセキュリティに関する考慮事項が、このドキュメントの「セキュリティ要件」セクションに示されています。It does, however, suggest certain security considerations for the transport layer as outlined in the "Security Requirements" section of this document. これらの要件に対応する責任は、デバイス プロバイダーの側にあります。It is the device provider’s responsibility to provide those requirements. フレームワークがこれらに対応することはありません。The framework does not provide them for you.

ユーザー インタラクション モデルUser Interaction Model

Windows Hello コンパニオン デバイス アプリの検出、インストール、および初回登録Windows Hello companion device app discovery, installation, and first-time registration

一般的なユーザー ワークフローは次のようになります。A typical user workflow is as follows:

  • ユーザーは、Windows Hello コンパニオン デバイスを使用してロックを解除する各 Windows 10 デスクトップ デバイスで PIN を設定します。The user sets up the PIN on each of target Windows 10 desktop devices she wants to unlock with that Windows Hello companion device.
  • ユーザーは、Windows 10 デスクトップ デバイスで Windows Hello コンパニオン デバイス アプリを実行して、自分の Windows Hello コンパニオン デバイスを Windows 10 デスクトップ デバイスに登録します。The user runs the Windows Hello companion device app on their Windows 10 desktop device to register her Windows Hello companion device with Windows 10 desktop.

注:Notes:

  • Windows Hello コンパニオン デバイス アプリの検出、ダウンロード、および起動は効率化し、可能な場合は自動化することをお勧めします (たとえば、Windows Hello コンパニオン デバイスを Windows 10 デスクトップ デバイス側の NFC リーダーでタップしたときに、アプリを自動的にダウンロードできるようにします)。We recommend the discovery, download, and launch of the Windows Hello companion device app is streamlined and, if possible, automated (e.g., the app can be downloaded upon tapping the Windows Hello companion device on an NFC reader on Windows 10 desktop device side). ただし、これは、Windows Hello コンパニオン デバイスと Windows Hello コンパニオン デバイス アプリの責任で実行する必要があります。This is, however, the responsibility of the Windows Hello companion device and Windows Hello companion device app.
  • エンタープライズ環境では、MDM によって Windows Hello コンパニオン デバイス アプリを展開できます。In an enterprise environment, the Windows Hello companion device app can be deployed via MDM.
  • 登録の一部として発生するエラー メッセージの表示は、Windows Hello コンパニオン デバイス アプリが担当します。The Windows Hello companion device app is responsible for showing the user any error messages that happen as part of registration.

登録/登録解除プロトコルRegistration and de-registration protocol

次の図は、登録時の Windows Hello コンパニオン デバイスと Companion Authentication Service の対話方法を示しています。The following diagram illustrates how the Windows Hello companion device interacts with Companion Authentication Service during registration.

登録フロー

このプロトコルでは、2 つのキーが使用されます。There are two keys used in our protocol:

  • デバイス キー (devicekey): PC が Windows のロックを解除するために必要なロック解除トークンを保護するために使用されます。Device key (devicekey): used to protect unlock tokens that the PC needs to unlock Windows.
  • 認証キー (authkey): Windows Hello コンパニオン デバイスと Companion Authentication Service を相互認証するために使用されます。The authentication key (authkey): used to mutually authenticate the Windows Hello companion device and Companion Authentication Service.

デバイス キーと認証キーは、登録時に Windows Hello コンパニオン デバイス アプリと Windows Hello コンパニオン デバイスの間で交換されます。The device key and authentication keys are exchanged at registration time between the Windows Hello companion device app and Windows Hello companion device. このため、Windows Hello コンパニオン デバイス アプリと Windows Hello コンパニオン デバイスは、セキュリティで保護されたトランスポートを使用してキーを保護する必要があります。As a result, the Windows Hello companion device app and Windows Hello companion device must use a secure transport to protect keys.

また、上の図では、Windows Hello コンパニオン デバイスで 2 つの HMAC キーが生成されていますが、これらをアプリで生成して Windows Hello コンパニオン デバイスに送信して保存することもできます。Also, note that while the diagram above displays two HMAC keys generating on the Windows Hello companion device, it is also possible for the app to generate them and send them to the Windows Hello companion device for storage.

認証開始フローStarting authentication flows

ユーザーが Windows Hello コンパニオン デバイス フレームワークを使用して Windows 10 デスクトップへのサインインを開始する (つまりインテント シグナルを提供する) 方法は 2 つあります。There are two ways for the user to start the signing in flow to Windows 10 desktop using Windows Hello companion device framework (i.e., provide intent signal):

  • ノート PC のカバーを開くか、PC で Space キーを押すか画面をスワイプする。Open up the lid on laptop, or hit the space bar or swipe up on PC.
  • Windows Hello コンパニオン デバイス側でジェスチャまたはアクションを実行する。Perform a gesture or an action on the Windows Hello companion device side.

どちらで始めるかは、Windows Hello コンパニオン デバイス側が選択します。It is the Windows Hello companion device's choice to select which one is the starting point. Windows Hello コンパニオン デバイス フレームワークは、オプション 1 が発生したら、それをコンパニオン デバイス アプリに通知します。The Windows Hello companion device framework will inform companion device app when option one happens. オプション 2 では、Windows Hello コンパニオン デバイス アプリがコンパニオン デバイスにクエリを行って、そのイベントがキャプチャされたかどうかを確認する必要があります。For option two, the Windows Hello companion device app should query the companion device to see if that event has been captured. これにより、Windows Hello コンパニオン デバイスがインテント シグナルを収集した後、必ずロック解除が成功します。This ensures the Windows Hello companion device collects the intent signal before the unlock succeeds.

Windows Hello コンパニオン デバイス資格情報プロバイダーWindows Hello companion device credential provider

Windows 10 には、すべての Windows Hello コンパニオン デバイスを処理する新しい資格情報プロバイダーがあります。There is a new credential provider in Windows 10 that handles all Windows Hello companion devices.

トリガーのアクティブ化によるコンパニオン デバイスのバックグラウンド タスクの起動は、Windows Hello コンパニオン デバイス資格情報プロバイダーが担当します。The Windows Hello companion device credential provider is responsible for launching the companion device background task via activating a trigger. トリガーは、PC が起動され、ロック画面が表示されたときに、1 回目の設定が行われます。The trigger is set the first time when the PC awakens and a lock screen is displayed. 2 回目は、PC がログオン UI に移行し、Windows Hello コンパニオン デバイス資格情報プロバイダー タイルが選択された時点です。The second time is when the PC is entering logon UI and the Windows Hello companion device credential provider is the selected tile.

Windows Hello コンパニオン デバイス アプリのヘルパー ライブラリが、ロック画面の状態の変化をリッスンし、Windows Hello コンパニオン デバイスのバック グラウンド タスクに対応するイベントを送信します。The helper library for the Windows Hello companion device app will listen to the lock screen status change and send the event corresponding to the Windows Hello companion device background task.

複数の Windows Hello コンパニオン デバイスのバックグラウンド タスクがある場合は、最初に認証処理を終了したバックンド タスクが PC のロックを解除します。If there are multiple Windows Hello companion device background tasks, the first background task that has finished the authentication process will unlock the PC. コンパニオン デバイス認証サービスは、残りの認証呼び出しを無視します。The companion device authentication service will ignore any remaining authentication calls.

Windows Hello コンパニオン デバイス側のエクスペリエンスは、Windows Hello コンパニオン デバイス アプリが処理と管理を行います。The experience on the Windows Hello companion device side is owned and managed by the Windows Hello companion device app. Windows Hello コンパニオン デバイス フレームワークは、ユーザー エクスペリエンスのこの部分を制御しません。The Windows Hello companion device framework has no control over this part of the user experience. 具体的には、コンパニオン認証プロバイダーは、ログオン UI の状態の変化 (ロック画面が今表示されたことや、ユーザーが Space キーを押してロック画面を消したばかりであることなど) を Windows Hello コンパニオン デバイス アプリに (そのバックグラウンド アプリ経由で) 通知します。その周辺のエクスペリエンス (ユーザーが Space キーを押したときのロック画面の消去や、USB 上のデバイス検索の開始など) の構築は、Windows Hello コンパニオン デバイス アプリが担当します。More specifically, the companion authentication provider informs the Windows Hello companion device app (via its background app) about state changes in logon UI (e.g., lock screen just came down, or the user just dispelled lock screen by hitting spacebar), and it is the responsibility of the Windows Hello companion device app to build an experience around that (e.g., upon user hitting spacebar and dispelling unlock screen, start looking for the device over USB).

Windows Hello コンパニオン デバイス フレームワークには、Windows Hello コンパニオン デバイス アプリが選択できる (ローカライズされた) テキストとエラー メッセージが多数用意されています。The Windows Hello companion device Framework will provide a stock of (localized) text and error messages for the Windows Hello companion device app to choose from. これらは、ロック画面の上部 (またはログオン UI) に表示されます。These will be displayed on top of lock screen (or in logon UI). 詳細については、メッセージとエラーの処理に関するセクションを参照してください。See the Dealing with Messages and Errors section for more details.

認証プロトコルAuthentication protocol

トリガーによって開始された Windows Hello コンパニオン デバイス アプリに関連付けられたバックグラウンド タスクは、Companion Authentication Service によって計算された HMAC 値を検証し、2 つの HMAC 値の計算を支援するように、Windows Hello コンパニオン デバイスに依頼する必要があります。Once the background task associated with a Windows Hello companion device app is trigger started, it is responsible for asking the Windows Hello companion device to validate an HMAC value computed by the Companion Authentication Service and help calculate two HMAC values:

  • サービス HMAC = HMAC (認証キー, サービス nonce || デバイス nonce || セッション nonce) を検証する。Validate Service HMAC = HMAC(authentication key, service nonce || device nonce || session nonce).
  • nonce を使用してデバイス キーの HMAC を計算する。Calculate the HMAC of the device key with a nonce.
  • Companion Authentication Service によって生成された nonce が連結された最初の HMAC 値を持つ認証キーの HMAC を計算する。Calculate the HMAC of the authentication key with first HMAC value concatenated with a nonce generated by the Companion Authentication Service.

2 番目の計算値は、サービスがデバイスを認証し、さらにトランスポート チャネルでのリプレイ攻撃を防ぐために使用されます。The second computed value is used by the service to authenticate the device and also prevent replay attack in transport channel.

登録フロー

ライフサイクルの管理Lifecycle management

一度登録すればどこでも使えるRegister once, use everywhere

バックエンド サーバーなしで、ユーザーは、自分の Windows Hello コンパニオン デバイスを、各 Windows 10 デスクトップ デバイスに個別に登録する必要があります。Without a backend server, users must register their Windows Hello companion device with each Windows 10 desktop device separately.

コンパニオン デバイス ベンダーや OEM は、ユーザーの Windows 10 デスクトップやモバイル デバイスの登録状態をローミングする Web サービスを実装できます。A companion device vendor or OEM can implement a web service to roam the registration state across user Windows 10 desktops or mobile devices. 詳細については、ローミング、無効化、およびフィルター サービスに関するセクションをご覧ください。For more details, see the Roaming, Revocation, and Filter Service section.

PIN 管理PIN management

コンパニオン デバイスを使用する前に、Windows 10 デスクトップ デバイスに PIN を設定する必要があります。Before a companion device can be used, a PIN needs to be set up on Windows 10 desktop device. これにより、ユーザーの Windows Hello コンパニオン デバイスが動作しない場合のバックアップが保証されます。This ensures the user has a backup in case their Windows Hello companion device is not working. PIN は、Windows によって管理されるものであり、アプリがまったく認識しないものです。The PIN is something that Windows manages and that apps never see. これを変更するには、ユーザーは、[設定]、[アカウント]、[サインイン オプション] の順に移動します。To change it, the user navigates to Settings > Accounts > Sign-in options.

管理とポリシーManagement and policy

ユーザーは、Windows 10 デスクトップ デバイス上の Windows Hello コンパニオン デバイス アプリを実行することで、Windows 10 デスクトップから Windows Hello コンパニオン デバイスを削除できます。Users can remove a Windows Hello companion device from a Windows 10 desktops by running the Windows Hello companion device app on that desktop device.

企業では、Windows Hello コンパニオン デバイス フレームワークを制御するためのオプションは 2 つあります。Enterprises have two options for controlling the Windows Hello companion device framework:

  • 機能を有効または無効にするTurn the feature on or off
  • Windows AppLocker を使用して、許可される Windows Hello コンパニオン デバイスのホワイトリストを定義するDefine the whitelist of Windows Hello companion devices allowed using Windows app locker

Windows Hello コンパニオン デバイス フレームワークでは、使用可能なコンパニオン デバイスのインベントリを保持するための一元管理や、許可される Windows Hello コンパニオン デバイスの種類のフィルター処理 (たとえば、シリアル番号が X ~ Y の範囲にあるデバイスのみを許可する) がサポートされません。The Windows Hello companion device framework does not support any centralized way to keep inventory of available companion devices, or a method to further filter which instances of a Windows Hello companion device type is allowed (for example, only a companion device with a serial number between X and Y are allowed). ただし、アプリ開発者は、このような機能を提供するサービスを構築できます。Apps developers can, however, build a service to provide such functionality. 詳細については、ローミング、無効化、およびフィルター サービスに関するセクションをご覧ください。For more details, see the Roaming, Revocation, and Filter Service section.

無効化Revocation

Windows Hello コンパニオン デバイス フレームワークでは、特定の Windows 10 デスクトップ デバイスからリモートでコンパニオン デバイスを削除できません。The Windows Hello companion device framework does not support removing a companion device from a specific Windows 10 desktop device remotely. 代わりに、ユーザーが、Windows 10 デスクトップで実行されている Windows Hello コンパニオン デバイス アプリを介して、Windows Hello コンパニオン デバイスを削除することができます。Instead, users can remove the Windows Hello companion device via the Windows Hello companion device app running on that Windows 10 desktop.

ただし、コンパニオン デバイス ベンダーは、リモート無効化機能を提供するサービスを構築できます。Companion device vendors, however, can build a service to provide remote revocation functionality. 詳細については、ローミング、無効化、およびフィルター サービスに関するセクションを参照してください。For more details, see Roaming, Revocation, and Filter Service section.

ローミングとフィルター サービスRoaming and filter services

コンパニオン デバイス ベンダーは、次のシナリオで使用できる Web サービスを実装できます。Companion device vendors can implement a web service that can be used for the following scenarios:

  • エンタープライズのフィルター サービス:企業では、Windows Hello コンパニオン デバイス動作する、select、環境内で特定のベンダーからいくつかのセットを制限できます。A filter service for enterprise: An enterprise can limit the set of Windows Hello companion devices that can work in their environment to a select few from a specific vendor. たとえば、10,000 台のモデル Y コンパニオン デバイスをベンダー X に発注した Contoso 社は、それらのデバイスのみが Contoso ドメインで動作し、ベンダー X の他のデバイス モデルは動作しないことを保証できます。For example, the company Contoso could order 10,000 Model Y companion devices from Vendor X and ensure only those devices will work in the Contoso domain (and not any other device model from Vendor X).
  • インベントリ:企業は、エンタープライズ環境で使用される既存のコンパニオン デバイスの一覧を確認できます。Inventory: An enterprise can determine the list of existing companion devices used in an enterprise environment.
  • リアルタイムの失効:従業員は、彼のコンパニオン デバイスが紛失または盗難にあったことを報告する場合、そのデバイスを失効させる、web サービスを使用できます。Real time revocation: If an employee reports that his companion device is lost or stolen, the web service can be used to revoke that device.
  • ローミング。ユーザーは、1 回のコンパニオン デバイスを登録するだけにし、彼の Windows 10 デスクトップおよびモバイルのすべてで動作します。Roaming: A user only has to register his companion device once and it works on all of his Windows 10 desktops and Mobile.

これらの機能を実装するには、登録時と使用時に Web サービスを確認する Windows Hello コンパニオン デバイス アプリが必要です。Implementing these features requires the Windows Hello companion device app to check with the web service at registration and usage time. Windows Hello コンパニオン デバイス アプリは、Web サービスの確認を 1 日に 1 回のみ要求するようなキャッシュされたログオン シナリオ用に最適化できます (無効化時間が最大 1 日遅くなります)。The Windows Hello companion device app can optimize for cached logon scenarios like requiring checking with web service only once a day (at the cost of extending the revocation time to up to one day).

Windows Hello コンパニオン デバイス フレームワーク API モデルWindows Hello companion device framework API model

概要Overview

Windows Hello コンパニオン デバイス アプリには、デバイスの登録と登録解除を行う UI を持つフォアグラウンド アプリと、認証を処理するバックグラウンド タスクという 2 つのコンポーネントを含める必要があります。A Windows Hello companion device app should contain two components: a foregroud app with UI responsible for registering and unregistering the device, and a background task that handles authentication.

全体的な API フローは次のようになります。The overall API flow is as follows:

  1. Windows Hello コンパニオン デバイスを登録するRegister the Windows Hello companion device
    • デバイスが近くにあることを確認し、その機能のクエリを実行する (必要な場合)Make sure the device is nearby and query its capability (if required)
    • 2 つの HMAC キーを生成する (コンパニオン デバイス側またはアプリ側のどちらかで実行)Generate two HMAC keys (either on the companion device side or the app side)
    • RequestStartRegisteringDeviceAsync を呼び出すCall RequestStartRegisteringDeviceAsync
    • FinishRegisteringDeviceAsync を呼び出すCall FinishRegisteringDeviceAsync
    • Windows Hello コンパニオン デバイス アプリに HMAC キーが保存されていること (サポートされている場合)、および Windows Hello コンパニオン デバイス アプリによってそのコピーが破棄されていることを確認するMake sure Windows Hello companion device app stores HMAC keys (if supported) and Windows Hello companion device app discards its copies
  2. バックグラウンド タスクを登録するRegister your background task
  3. バック グラウンド タスクで適切なイベントが発生するまで待機するWait for the right event in the background task
    • WaitingForUserConfirmation:Windows Hello コンパニオン デバイス側でユーザー アクション/ジェスチャが認証フローを開始する必要がある場合、このイベントを待つWaitingForUserConfirmation: Wait for this event if the user action/gesture on the Windows Hello companion device side is required to start authentication flow
    • CollectingCredential:Windows Hello コンパニオン デバイスのユーザー アクション/ジェスチャ (など、space キーを押す) によって認証フローを開始する PC の側が依存している場合、このイベントを待つCollectingCredential: Wait for this event if the Windows Hello companion device relies on user action/gesture on the PC side to start authentication flow (e.g., by hitting spacebar)
    • 他のトリガー、スマート カードのようにします。右側の Api を呼び出すの現在の認証状態に対してクエリを実行してください。Other trigger, like a smartcard: Make sure to query for current authentication state to call the right APIs.
  4. エラー メッセージや次に必要な手順について、ShowNotificationMessageAsync を呼び出してユーザーに通知する。Keep user informed about error messages or required next steps by calling ShowNotificationMessageAsync. この API は、インテント シグナルが収集された後でのみ呼び出しますOnly call this API once an intent signal is collected
  5. UnlockUnlock
    • インテント シグナルとユーザー プレゼンス シグナルが収集されたことを確認するMake sure intent and user presence signals were collected
    • StartAuthenticationAsync を呼び出すCall StartAuthenticationAsync
    • コンパニオン デバイスと通信して、必要な HMAC 操作を実行するCommunicate with the companion device to perform required HMAC operations
    • FinishAuthenticationAsync を呼び出すCall FinishAuthenticationAsync
  6. ユーザーの要求に応じて (ユーザーが Windows Hello コンパニオン デバイスを紛失した場合など)、Windows Hello コンパニオン デバイスの登録を解除するUn-register a Windows Hello companion device when the user requests it (for example, if they've lost their companion device)
    • FindAllRegisteredDeviceInfoAsync を使用してログインしているユーザーの Windows Hello コンパニオン デバイスを列挙するEnumerate the Windows Hello companion device for logged in user via FindAllRegisteredDeviceInfoAsync
    • UnregisterDeviceAsync を使用してデバイスの登録を解除するUn-register it using UnregisterDeviceAsync

登録と登録解除Registration and de-registration

登録には、付属の認証サービスへの 2 つの API 呼び出しが必要です。RequestStartRegisteringDeviceAsync FinishRegisteringDeviceAsync.Registration requires two API calls to the Companion Authentication Service: RequestStartRegisteringDeviceAsync and FinishRegisteringDeviceAsync.

これらの呼び出しを行う前に、Windows Hello コンパニオン デバイス アプリは、Windows Hello コンパニオン デバイスが使用可能であることを確認する必要があります。Before any of these calls are made, the Windows Hello companion device app must make sure that the Windows Hello companion device is available. Windows Hello コンパニオン デバイスが HMAC キー (認証キーとデバイス キー) の生成を担当する場合、Windows Hello コンパニオン デバイス アプリは、上記の 2 つの呼び出しを行う前に、それを生成するようコンパニオン デバイスに依頼する必要があります。If the Windows Hello companion device is responsible for generating HMAC keys (authentication and device keys), then the Windows Hello companion device app should also ask the companion device to generate them before making any of the above two calls. Windows Hello コンパニオン デバイス アプリが HMAC キーの生成を担当する場合は、上記の 2 つの呼び出しを行う前にそれを実行する必要があります。If the Windows Hello companion device app is responsible for generating HMAC keys, then it should do so before calling the above two calls.

さらに、Windows Hello コンパニオン デバイス アプリは、最初の API 呼び出し (RequestStartRegisteringDeviceAsync) の一部としてデバイスの機能を決定し、それを API 呼び出しの一部として渡すための準備を行う必要があります (Windows Hello コンパニオン デバイスが HMAC キーのセキュア ストレージをサポートしているかどうかなどを渡します)。Additionally, as part of first API call (RequestStartRegisteringDeviceAsync), the Windows Hello companion device app must decide on device capability and be prepared to pass it as part of the API call; for example, whether the Windows Hello companion device supports secure storage for HMAC keys. 同じ Windows Hello コンパニオン デバイス アプリを使用して、同じコンパニオン デバイスの複数のバージョンとその機能変更を管理する場合 (また、デバイス クエリで管理の対象を決定する必要がある場合)、最初の API 呼び出しを行う前に、そのクエリを実行することをお勧めします。If the same Windows Hello companion device app is used to manage multiple versions of the same companion device and those capabilities change (and requires a device query to decide), we recommend this queries occurs before first API call is made.

最初の API (RequestStartRegisteringDeviceAsync) は、2 番目の API (FinishRegisteringDeviceAsync) で使用されるハンドルを返します。The first API (RequestStartRegisteringDeviceAsync) will return a handle used by the second API (FinishRegisteringDeviceAsync). 登録するための最初の呼び出しは、PIN プロンプトを起動して、ユーザーが存在していることを確認します。The first call for registration will launch the PIN prompt to make sure user is present. PIN が設定されていない場合、この呼び出しは失敗します。If no PIN is set up, this call will fail. Windows Hello コンパニオン デバイス アプリは、KeyCredentialManager.IsSupportedAsync 呼び出しにより、PIN が設定されているかどうかのクエリを実行することもできます。The Windows Hello companion device app can query whether PIN is set up or not via KeyCredentialManager.IsSupportedAsync call as well. ポリシーによって Windows Hello コンパニオン デバイスの使用が無効になっている場合も、RequestStartRegisteringDeviceAsync 呼び出しが失敗することがあります。RequestStartRegisteringDeviceAsync call can also fail if policy has disabled the usage of the Windows Hello companion device.

最初の呼び出しの結果は、SecondaryAuthenticationFactorRegistrationStatus 列挙型で返されます。The result of first call is returned via SecondaryAuthenticationFactorRegistrationStatus enum:

{
    Failed = 0,         // Something went wrong in the underlying components
    Started,            // First call succeeded
    CanceledByUser,     // User cancelled PIN prompt
    PinSetupRequired,   // PIN is not set up
    DisabledByPolicy,   // Companion device framework or this app is disabled
}

2 番目の呼び出し (FinishRegisteringDeviceAsync) は登録を終了します。The second call (FinishRegisteringDeviceAsync) finishes the registration. 登録プロセスの一部として、Windows Hello コンパニオン デバイス アプリは、Companion Authentication Service を使用してコンパニオン デバイスの構成データを保存できます。As part of registration process, the Windows Hello companion device app can store companion device configuration data with Companion Authentication Service. このデータには 4 K というサイズ制限があります。There is a 4K size limit for this data. このデータは、Windows Hello コンパニオン デバイス アプリが認証時に使用できます。This data will be available to the Windows Hello companion device app at authentication time. このデータは、たとえば、Windows Hello コンパニオン デバイスに接続するときに MAC アドレスのように使用できます。また、Windows Hello コンパニオン デバイスにストレージがないときに、PC をストレージ用として使用することをコンパニオン デバイスが望んだ場合、構成データを使用できます。This data can be used, as an example, to connect to the Windows Hello companion device like a MAC address, or if the Windows Hello companion device does not have storage and companion device wants to use PC for storage, then configuration data can be used. データの一部として保存される機密性の高いデータは、Windows Hello コンパニオン デバイスだけが知っているキーを使用して暗号化する必要があることに注意してください。Note that any sensitive data stored as part of configuration data must be encrypted with a key that only the Windows Hello companion device knows. また、構成データが Windows サービスによって保存されるのであれば、Windows Hello コンパニオン デバイス アプリは、ユーザー プロファイルを通してそれを使用できます。Also, given that configuration data is stored by a Windows service, it is available to the Windows Hello companion device app across user profiles.

Windows Hello コンパニオン デバイス アプリは、AbortRegisteringDeviceAsync を呼び出して登録をキャンセルし、エラー コードを渡すことができます。The Windows Hello companion device app can call AbortRegisteringDeviceAsync to cancel the registration and pass in an error code. Companion Authentication Service は、エラーを利用統計情報で記録します。The Companion Authentication Service will log the error in the telemetry data. この呼び出しが適切な例として、Windows Hello コンパニオン デバイスで問題が発生し、登録を終了できなかった場合があります (HMAC キーが保存できなかった、BT 接続が失われた場合など)。A good example for this call would be when something went wrong with the Windows Hello companion device and it could not finish registration (e.g., it cannot store HMAC keys or BT connection was lost).

Windows Hello コンパニオン デバイス アプリには、ユーザーが (Windows Hello コンパニオン デバイスを紛失した場合や、新しいバージョンを購入した場合などに) Windows 10 デスクトップから Windows Hello コンパニオン デバイスの登録を解除するためのオプションが必要です。The Windows Hello companion device app must provide an option for the user to de-register their Windows Hello companion device from their Windows 10 desktop (e.g., if they lost their companion device or bought a newer version). ユーザーがそのオプションを選択したとき、Windows Hello コンパニオン デバイス アプリは、UnregisterDeviceAsync を呼び出す必要があります。When the user selects that option, then the Windows Hello companion device app must call UnregisterDeviceAsync. Windows Hello コンパニオン デバイス アプリからのこの呼び出しによって、コンパニオン デバイス認証サービスは、呼び出し元アプリの特定のデバイス ID とアプリ ID に対応するすべてのデータ (HMAC キーを含む) を PC 側から削除します。This call by the Windows Hello companion device app will trigger the companion device authentication service to delete all data (including HMAC keys) corresponding to the specific device Id and AppId of the caller app from PC side. この API 呼び出しは、Windows Hello コンパニオン デバイス アプリまたはコンパニオン デバイス側からは HMAC キーを削除しません。This API call does not attempt to delete HMAC keys from either the Windows Hello companion device app or companion device side. その実装は、Windows Hello コンパニオン デバイス アプリに任されています。That is left for the Windows Hello companion device app to implement.

登録フェーズと登録解除フェーズ中に発生したエラー メッセージの表示は、Windows Hello コンパニオン デバイス アプリが担当します。The Windows Hello companion device app is responsible for showing any error messages that happen in registration and de-registration phase.

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.Security.Cryptography;
using Windows.UI.Popups;

namespace SecondaryAuthFactorSample
{
    public class DeviceRegistration
    {

        public void async OnRegisterButtonClick()
        {
            //
            // Pseudo function, the deviceId should be retrieved by the application from the device
            //
            string deviceId = await ReadSerialNumberFromDevice();

            IBuffer deviceKey = CryptographicBuffer.GenerateRandom(256/8);
            IBuffer mutualAuthenticationKey = CryptographicBuffer.GenerateRandom(256/8);

            SecondaryAuthenticationFactorRegistration registrationResult =
                await SecondaryAuthenticationFactorRegistration.RequestStartRegisteringDeviceAsync(
                    deviceId,  // deviceId: max 40 wide characters. For example, serial number of the device
                    SecondaryAuthenticationFactorDeviceCapabilities.SecureStorage |
                        SecondaryAuthenticationFactorDeviceCapabilities.HMacSha256 |
                        SecondaryAuthenticationFactorDeviceCapabilities.StoreKeys,
                    "My test device 1", // deviceFriendlyName: max 64 wide characters. For example: John's card
                    "SAMPLE-001", // deviceModelNumber: max 32 wide characters. The app should read the model number from device.
                    deviceKey,
                    mutualAuthenticationKey);

            switch(registerResult.Status)
            {
            case SecondaryAuthenticationFactorRegistrationStatus.Started:
                //
                // Pseudo function:
                // The app needs to retrieve the value from device and set into opaqueBlob
                //
                IBuffer deviceConfigData = ReadConfigurationDataFromDevice();

                if (deviceConfigData != null)
                {
                    await registrationResult.Registration.FinishRegisteringDeviceAsync(deviceConfigData); //config data limited to 4096 bytes
                    MessageDialog dialog = new MessageDialog("The device is registered correctly.");
                    await dialog.ShowAsync();
                }
                else
                {
                    await registrationResult.Registration.AbortRegisteringDeviceAsync("Failed to connect to the device");
                    MessageDialog dialog = new MessageDialog("Failed to connect to the device.");
                    await dialog.ShowAsync();
                }
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.CanceledByUser:
                MessageDialog dialog = new MessageDialog("You didn't enter your PIN.");
                await dialog.ShowAsync();
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.PinSetupRequired:
                MessageDialog dialog = new MessageDialog("Please setup PIN in settings.");
                await dialog.ShowAsync();
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.DisabledByPolicy:
                MessageDialog dialog = new MessageDialog("Your enterprise prevents using this device to sign in.");
                await dialog.ShowAsync();
                break;
            }
        }

        public void async UpdateDeviceList()
        {
            IReadOnlyList<SecondaryAuthenticationFactorInfo> deviceInfoList =
                await SecondaryAuthenticationFactorRegistration.FindAllRegisteredDeviceInfoAsync(
                    SecondaryAuthenticationFactorDeviceFindScope.User);

            if (deviceInfoList.Count > 0)
            {
                foreach (SecondaryAuthenticationFactorInfo deviceInfo in deviceInfoList)
                {
                    //
                    // Add deviceInfo.FriendlyName and deviceInfo.DeviceId into a combo box
                    //
                }
            }
        }

        public void async OnUnregisterButtonClick()
        {
            string deviceId;
            //
            // Read the deviceId from the selected item in the combo box
            //
            await SecondaryAuthenticationFactorRegistration.UnregisterDeviceAsync(deviceId);
        }
    }
}

認証Authentication

認証では、付属の認証サービスへの 2 つの API 呼び出しが必要です。StartAuthenticationAsync FinishAuthencationAsync.Authentication requires two API calls to the Companion Authentication Service: StartAuthenticationAsync and FinishAuthencationAsync.

最初の開始 API は、2 番目の API で使用されるハンドルを返します。The first initiation API will return a handle used by the second API. 最初の呼び出しは、特に nonce を返します。他のデータと連結されるこの nonce は、Windows Hello コンパニオン デバイスに保存されるデバイス キーを HMAC 処理するために必要です。The first call returns, among other things, a nonce that – once concatenated with other things - needs to be HMAC'ed with the device key stored on the Windows Hello companion device. 2 番目の呼び出しは、デバイス キーの HMAC の結果を返し、認証の成功で終了できます (つまり、ユーザーにデスクトップが表示されます)。The second call returns the results of HMAC with device key and can potentially end in successful authentication (i.e., the user will see their desktop).

最初の開始 API (StartAuthenticationAsync) は、初回登録後、ポリシーによってその Windows Hello コンパニオン デバイスが無効になっている場合は失敗します。The first initiation API (StartAuthenticationAsync) can fail if policy has disabled that Windows Hello companion device after initial registration. API 呼び出しは、WaitingForUserConfirmation 状態または CollectingCredential 状態以外のときに行われた場合も失敗します (詳しくは、このセクションで後述します)。It can also fail if the API call was made outside WaitingForUserConfirmation or CollectingCredential states (more on this later in this section). さらに、未登録のコンパニオン デバイス アプリがそれを呼び出した場合も失敗します。It can also fail if an unregistered companion device app calls it. SecondaryAuthenticationFactorAuthenticationStatus 列挙型は、可能な結果を要約します。SecondaryAuthenticationFactorAuthenticationStatus Enum summarizes the possible outcomes:

{
    Failed = 0,                     // Something went wrong in the underlying components
    Started,
    UnknownDevice,                  // Companion device app is not registered with framework
    DisabledByPolicy,               // Policy disabled this device after registration
    InvalidAuthenticationStage,     // Companion device framework is not currently accepting
                                    // incoming authentication requests
}

2 番目の API 呼び出し (FinishAuthencationAsync) は、最初の呼び出しで提供された nonce の有効期限 (20 秒) が終了した場合は失敗します。The second API call (FinishAuthencationAsync) can fail if the nonce that was provided in the first call is expired (20 seconds). SecondaryAuthenticationFactorFinishAuthenticationStatus 列挙型では、可能な結果をキャプチャします。SecondaryAuthenticationFactorFinishAuthenticationStatus enum captures possible outcomes.

{
    Failed = 0,     // Something went wrong in the underlying components
    Completed,      // Success
    NonceExpired,   // Nonce is expired
}

2 つの API 呼び出し (StartAuthenticationAsync と FinishAuthencationAsync) のタイミングは、Windows Hello コンパニオン デバイスがインテント シグナル、ユーザー プレゼンス シグナル、および曖昧性解消シグナル (詳しくは、「ユーザー シグナル」を参照) を収集する方法と合わせる必要があります。The timing of two API calls (StartAuthenticationAsync and FinishAuthencationAsync) needs to align with how the Windows Hello companion device collects intent, user presence, and disambiguation signals (see User Signals for more details). たとえば、2 番目の呼び出しは、インテント シグナルを入手した後で送信します。For example, the second call must not be submitted until intent signal is available. つまり、ユーザーがロック解除の意図を示していない場合、PC のロックは解除すべきではありません。In other words, the PC should not unlock if the user has not expressed intent for it. 具体的に言えば、Bluetooth の近接性を使用して PC のロックを解除する場合は、明確なインテント シグナルを収集する必要があります。そうしないと、ユーザーがキッチンに行く途中で PC の近くを通ったときに PC のロックが解除されます。To make this more clear, assume that Bluetooth proximity is used for PC unlock, then an explicit intent signal must be collected, otherwise, as soon as user walks by his PC on the way to kitchen, the PC will unlock. また、最初の呼び出しから返される nonce には時間制限 (20 秒) があり、一定期間後に有効期限が切れます。Also, the nonce returned from the first call is time bound (20 seconds) and will expire after certain period. このため、最初の呼び出しは、Windows Hello コンパニオン デバイスが確実に存在することをコンパニオン デバイス アプリが認識した (たとえば、コンパニオン デバイスが USB ポートに挿入されたり、NFC リーダーにタップされた) ときにのみ実行する必要があります。As a result, the first call only should be made when the Windows Hello companion device app has good indication of companion device presence, e.g., the companion device is inserted into USB port, or tapped on NFC reader. Bluetooth の場合は、PC 側のバッテリーや、Windows Hello コンパニオン デバイスの存在を確認している時点で進行中の他の Bluetooth アクティビティへの影響を回避することを考慮する必要があります。With Bluetooth, care must be taken to avoid affecting battery on PC side or affecting other Bluetooth activities going on at that point when checking for Windows Hello companion device presence. さらに、(たとえば PIN の入力による) ユーザー プレゼンス シグナルを提供する必要がある場合は、最初の認証呼び出しは、そのシグナルが収集された後でのみ実行することをお勧めします。Also, if a user presence signal needs to be provided (e.g., by typing in PIN), it is recommended that the first authentication call is only made after that signal is collected.

Windows Hello コンパニオン デバイス フレームワークは、ユーザーが認証フローのどこにいるかの全体像を提供することによって、Windows Hello コンパニオン デバイス アプリが十分な情報に基づいて上記 2 つの呼び出しをいつ実行するかを決定できるようにしています。The Windows Hello companion device framework helps the Windows Hello companion device app to make informed decision on when to make above two calls by providing a complete picture of where user is in authentication flow. Windows Hello コンパニオン デバイス フレームワークは、ロック状態変化通知をアプリのバックグラウンド タスクに提供することで、この機能を実現しています。Windows Hello companion device framework provides this functionality by providing lock state change notification to app background task.

コンパニオン デバイス フロー

これらの状態の詳細を次に示します。Details of each of these states are as follows:

状態State 説明Description
WaitingForUserConfirmationWaitingForUserConfirmation この状態変化通知イベントは、ロック画面から移動した場合に発生します (例: ユーザーが Windows + L キーを押下)。This state change notification event is fired when the lock screen comes down (e.g., user pressed Windows + L). この状態のときは、デバイスが見つからないことに関連するすべてのエラー メッセージを要求しないことをお勧めします。We recommend not to request any error messages relating to having difficulty finding a device in this state. 一般に、メッセージの表示は、インテント シグナルが入手されるときにのみ実行することをお勧めします。In general, we recommend to only show messages when intent signal is available. コンパニオン デバイスがインテント シグナル (NFC リーダーのタップ、コンパニオン デバイスのボタンの押下、拍手などの特定のジェスチャなど) を収集する場合、Windows Hello コンパニオン デバイス アプリは、認証するための最初の API 呼び出しを、この状態のときに実行する必要があり、Windows Hello コンパニオン デバイス アプリのバックグラウンド タスクは、インテント シグナルが検出されたことをコンパニオン デバイスから受信します。The Windows Hello companion device app should make the first API call for authentication in this state if the companion device collects the intent signal (e.g., tapping on NFC reader, press of a button on the companion device or a specific gesture, like clapping), and the Windows Hello companion device app background task receives indication from the companion device that intent signal was detected. Windows Hello コンパニオン デバイス アプリが PC に依存して認証フローを開始する場合 (ユーザーによるロック画面のスワイプや Space キーの押下)、その Windows Hello コンパニオン デバイス アプリは、次の状態 (CollectingCredential) になるまで待機する必要があります。Otherwise, if the Windows Hello companion device app relies on the PC to start authentication flow (by having user swipe up the unlock screen or hitting space bar), then the Windows Hello companion device app needs to wait for the next state (CollectingCredential).
CollectingCredentialCollectingCredential この状態変化通知イベントは、ユーザーがノート PC のカバーを開いた、キーボードのいずれかのキーを押した、またはスワイプしてロック解除画面に移ったときに発生します。This state change notification event is fired when the user either opens their laptop lid, hits any key on their keyboard, or swipes up to the unlock screen. Windows Hello コンパニオン デバイスが上記のアクションに依存してインテント シグナルの収集を開始する場合、Windows Hello コンパニオン デバイス アプリは (ユーザーが PC のロック解除を望んでいるかどうかを確認するコンパニオン デバイス上のポップアップなどで) その収集を開始する必要があります。If the Windows Hello companion device relies on the above actions to start collecting the intent signal, then the Windows Hello companion device app should start collecting it (e.g., via a pop up on the companion device asking whether user wants to unlock the PC). Windows Hello コンパニオン デバイス アプリがコンパニオン デバイスにユーザー プレゼンス シグナルを提供すること (Windows Hello コンパニオン デバイスで PIN を入力するなど) をユーザーに要求する場合は、ここでエラー事例を提供することをお勧めします。This would be a good time to provide error cases if the Windows Hello companion device app needs the user to provide a user presence signal on the companion device (like typing in PIN on the Windows Hello companion device).
SuspendingAuthenticationSuspendingAuthentication Windows Hello コンパニオン デバイス アプリがこの状態を受信した場合は、Companion Authentication Service が認証要求の受け入れを停止したことを意味します。When the Windows Hello companion device app receives this state, it means that the Companion Authentication Service has stopped accepting authentication requests.
CredentialCollectedCredentialCollected これは、別の Windows Hello コンパニオン デバイス アプリから 2 番目の API の呼び出しがあり、何が送信されたかを Companion Authentication Service が検証していることを意味します。This means that another Windows Hello companion device app has called the second API and that the Companion Authentication Service is verifying what was submitted. この時点で、Companion Authentication Service は、現在送信されたものが検証に合格しない限り、他の認証要求を受け入れません。At this point, the Companion Authentication Service is not accepting any other authentication requests unless the currently submitted one does not pass verification. Windows Hello コンパニオン デバイス アプリは、次の状態になるまで現在の状態を維持する必要があります。The Windows Hello companion device app should stay tuned until next state is reached.
CredentialAuthenticatedCredentialAuthenticated これは、送信された資格情報が機能したことを意味します。This means that the submitted credential worked. credentialAuthenticated には、成功した Windows Hello コンパニオン デバイスのデバイス ID が含まれます。The credentialAuthenticated has the device ID of the Windows Hello companion device that succeeded. Windows Hello コンパニオン デバイス アプリは、それに関連付けられているデバイスが勝者であるかどうかを確認する必要があります。The Windows Hello companion device app should make sure to check on that to see if its associated device was the winner. そうでない場合、Windows Hello コンパニオン デバイス アプリは、認証後フローの表示 (コンパニオン デバイス上の成功メッセージなど。デバイスのバイブレーションも考えられます) を回避する必要があります。If not, then the Windows Hello companion device app should avoid showing any post authentication flows (like success message on the companion device or perhaps a vibration on that device). 送信された資格情報が機能しなかった場合、状態は CollectingCredential に変化します。Note that if the submitted credential did not work, the state will change to CollectingCredential state.
StoppingAuthenticationStoppingAuthentication 認証が成功し、ユーザーにデスクトップが表示されます。Authentication succeeded and user saw the desktop. この時点で、バックグラウンド タスクを終了します。Time to kill your background task. バックグラウンド タスクを終了する前に、明示的に StageEvent ハンドラーの登録を解除します。Before exiting the backround task, explicitly unregister the StageEvent handler. これは、バックグラウンド タスクをすばやく終了する場合に役立ちます。This will help the background task exit quickly.

Windows Hello コンパニオン デバイス アプリは、最初の 2 つの状態のときにのみ、2 つの認証 API を呼び出す必要があります。Windows Hello companion device apps should only call the two authentication APIs in the first two states. Windows Hello コンパニオン デバイス アプリがチェックする必要があるのは、このイベントがどのシナリオで発生しているかです。Windows Hello companion device apps should check for what scenario this event is being fired. ロック解除とロック解除後という 2 つの可能性があります。There are two possibilities: unlock or post unlock. 現時点では、ロック解除のみがサポートされます。Currently, only unlock is supported. 今後のリリース後で、ロック解除後のシナリオがサポートされる可能性があります。In upcoming releases, post unlock scenarios may be supported. SecondaryAuthenticationFactorAuthenticationScenario 列挙型は、これら 2 つのオプションをキャプチャします。The SecondaryAuthenticationFactorAuthenticationScenario enum captures these two options:

{
    SignIn = 0,         // Running under lock screen mode
    CredentialPrompt,   // Running post unlock
}

完全なコード例:Complete code sample:

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.Security.Cryptography;
using System.Threading;
using Windows.ApplicationModel.Background;

namespace SecondaryAuthFactorSample
{
    public sealed class AuthenticationTask : IBackgroundTask
    {
        private string _deviceId;
        private static AutoResetEvent _exitTaskEvent = new AutoResetEvent(false);
        private static IBackgroundTaskInstance _taskInstance;
        private BackgroundTaskDeferral _deferral;

        private void Authenticate()
        {
            int retryCount = 0;

            while (retryCount < 3)
            {
                //
                // Pseudo code, the svcAuthNonce should be passed to device or generated from device
                //
                IBuffer svcAuthNonce = CryptographicBuffer.GenerateRandom(256/8);

                SecondaryAuthenticationFactorAuthenticationResult authResult = await
                    SecondaryAuthenticationFactorAuthentication.StartAuthenticationAsync(
                        _deviceId,
                        svcAuthNonce);
                if (authResult.Status != SecondaryAuthenticationFactorAuthenticationStatus.Started)
                {
                    SecondaryAuthenticationFactorAuthenticationMessage message;
                    switch (authResult.Status)
                    {
                        case SecondaryAuthenticationFactorAuthenticationStatus.DisabledByPolicy:
                            message = SecondaryAuthenticationFactorAuthenticationMessage.DisabledByPolicy;
                            break;
                        case SecondaryAuthenticationFactorAuthenticationStatus.InvalidAuthenticationStage:
                            // The task might need to wait for a SecondaryAuthenticationFactorAuthenticationStageChangedEvent
                            break;
                        default:
                            return;
                    }

                    // Show error message. Limited to 512 characters wide
                    await SecondaryAuthenticationFactorAuthentication.ShowNotificationMessageAsync(null, message);
                    return;
                }

                //
                // Pseudo function:
                // The device calculates and returns sessionHmac and deviceHmac
                //
                await GetHmacsFromDevice(
                    authResult.Authentication.ServiceAuthenticationHmac,
                    authResult.Authentication.DeviceNonce,
                    authResult.Authentication.SessionNonce,
                    out deviceHmac,
                    out sessionHmac);
                if (sessionHmac == null ||
                    deviceHmac == null)
                {
                    await authResult.Authentication.AbortAuthenticationAsync(
                        "Failed to read data from device");
                    return;
                }

                SecondaryAuthenticationFactorFinishAuthenticationStatus status =
                    await authResult.Authentication.FinishAuthencationAsync(deviceHmac, sessionHmac);
                if (status == SecondaryAuthenticationFactorFinishAuthenticationStatus.NonceExpired)
                {
                    retryCount++;
                    continue;
                }
                else if (status == SecondaryAuthenticationFactorFinishAuthenticationStatus.Completed)
                {
                    // The credential data is collected and ready for unlock
                    return;
                }
            }
        }

        public void OnAuthenticationStageChanged(
            object sender,
            SecondaryAuthenticationFactorAuthenticationStageChangedEventArgs args)
        {
            // The application should check the args.StageInfo.Stage to determine what to do in next. Note that args.StageInfo.Scenario will have the scenario information (SignIn vs CredentialPrompt).

            switch(args.StageInfo.Stage)
            {
            case SecondaryAuthenticationFactorAuthenticationStage.WaitingForUserConfirmation:
                // Show welcome message
                await SecondaryAuthenticationFactorAuthentication.ShowNotificationMessageAsync(
                    null,
                    SecondaryAuthenticationFactorAuthenticationMessage.WelcomeMessageSwipeUp);
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.CollectingCredential:
                // Authenticate device
                Authenticate();
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.CredentialAuthenticated:
                if (args.StageInfo.DeviceId = _deviceId)
                {
                    // Show notification on device about PC unlock
                }
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.StoppingAuthentication:
                // Quit from background task
                _exitTaskEvent.Set();
                break;
            }

            Debug.WriteLine("Authentication Stage = " + args.StageInfo.AuthenticationStage.ToString());
        }

        //
        // The Run method is the entry point of a background task.
        //
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            _taskInstance = taskInstance;
            _deferral = taskInstance.GetDeferral();

            // Register canceled event for this task
            taskInstance.Canceled += TaskInstanceCanceled;

            // Find all device registred by this application
            IReadOnlyList<SecondaryAuthenticationFactorInfo> deviceInfoList =
                await SecondaryAuthenticationFactorRegistration.FindAllRegisteredDeviceInfoAsync(
                    SecondaryAuthenticationFactorDeviceFindScope.AllUsers);

            if (deviceInfoList.Count == 0)
            {
                // Quit the task silently
                return;
            }
            _deviceId = deviceInfoList[0].DeviceId;
            Debug.WriteLine("Use first device '" + _deviceId + "' in the list to signin");

            // Register AuthenticationStageChanged event
            SecondaryAuthenticationFactorRegistration.AuthenticationStageChanged += OnAuthenticationStageChanged;

            // Wait the task exit event
            _exitTaskEvent.WaitOne();

            _deferral.Complete();
        }

        void TaskInstanceCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
        {
            _exitTaskEvent.Set();
        }
    }
}

バックグラウンド タスクの登録Register a background task

Windows Hello コンパニオン デバイス アプリは、最初のコンパニオン デバイスを登録するときに、デバイスとコンパニオン デバイス認証サービス間で認証情報を渡すバックグラウンド タスク コンポーネントも同時に登録する必要があります。When the Windows Hello companion device app registers the first companion device, it should also register its background task component which will pass authentication information between device and companion device authentication service.

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.ApplicationModel.Background;

namespace SecondaryAuthFactorSample
{
    public class BackgroundTaskManager
    {
        // Register background task
        public static async Task<IBackgroundTaskRegistration> GetOrRegisterBackgroundTaskAsync(
            string bgTaskName,
            string taskEntryPoint)
        {
            // Check if there's an existing background task already registered
            var bgTask = (from t in BackgroundTaskRegistration.AllTasks
                          where t.Value.Name.Equals(bgTaskName)
                          select t.Value).SingleOrDefault();
            if (bgTask == null)
            {
                BackgroundAccessStatus status =
                    BackgroundExecutionManager.RequestAccessAsync().AsTask().GetAwaiter().GetResult();

                if (status == BackgroundAccessStatus.Denied)
                {
                    Debug.WriteLine("Background Execution is denied.");
                    return null;
                }

                var taskBuilder = new BackgroundTaskBuilder();
                taskBuilder.Name = bgTaskName;
                taskBuilder.TaskEntryPoint = taskEntryPoint;
                taskBuilder.SetTrigger(new SecondaryAuthenticationFactorAuthenticationTrigger());
                bgTask = taskBuilder.Register();
                // Background task is registered
            }

            bgTask.Completed += BgTask_Completed;
            bgTask.Progress += BgTask_Progress;

            return bgTask;
        }
    }
}

エラーとメッセージErrors and messages

サインインの成功または失敗のユーザーへのフィードバックは、Windows Hello コンパニオン デバイス フレームワークが担当します。The Windows Hello companion device framework is responsible for providing feedback to the user about success or failure of signing in. Windows Hello コンパニオン デバイス フレームワークには、Windows Hello コンパニオン デバイス アプリが選択できる (ローカライズされた) テキストとエラー メッセージが多数用意されています。The Windows Hello companion device framework will provide a stock of (localized) text and error messages for the Windows Hello companion device app to choose from. これらは、ログオン UI に表示されます。These will be displayed in the logon UI.

コンパニオン デバイス エラー

Windows Hello コンパニオン デバイス アプリは、ShowNotificationMessageAsync を使用して、ログオン UI の一部としてユーザーにメッセージを表示できます。Windows Hello companion device apps can use ShowNotificationMessageAsync to show messages to user as part of the logon UI. この API は、インテント シグナルを入手できるときに呼び出します。Call this API when an intent signal is available. インテント シグナルは常に Windows Hello コンパニオン デバイス側で収集する必要があることに注意してください。Note that an intent signal must always be collected on the Windows Hello companion device side.

メッセージには、ガイダンスとエラーの 2 種類があります。There are two types of messages: guidance and errors.

ガイダンス メッセージは、ロック解除プロセスの開始方法をユーザーに表示することを目的としています。Guidance messages are designed to show the user how to start the unlock process. これらのメッセージは、初回のデバイス登録時にユーザーに対して 1 回のみ表示され、その後ロック画面に表示されることはありません。These messages are only shown to the user once on the lock screen, upon first device registration, and never shown there again. ロック画面の下には引き続き表示されています。These messages will continue to be shown under the lock screen.

エラー メッセージは常に表示されます。また、インテント シグナルが提供された後に表示されます。Error messages are always shown and will be shown after an intent signal is provided. ユーザーにメッセージを表示する前にインテント シグナルを収集する必要があるときに、ユーザーがいずれかの Windows Hello コンパニオン デバイスのみを使用して意図を表明するのであれば、複数の Windows Hello コンパニオン デバイスがエラー メッセージを表示するために競争するような状況は発生しません。Given that an intent signal must be collected before showing messages to the user, and the user will provide that intent only using one of the Windows Hello companion devices, there must not be a situation where multiple Windows Hello companion devices race for showing error messages. このため、Windows Hello コンパニオン デバイス フレームワークでは、キューの管理は行われません。As a result, the Windows Hello companion device framework does not maintain any queue. 呼び出し元がエラー メッセージを要求すると、エラー メッセージは 5 秒間表示され、その 5 秒間はエラー メッセージに対するその他のすべての要求は破棄されます。When a caller asks for an error message, it will be shown for 5 seconds and all other requests for showing an error message in that 5 seconds are dropped. 5 秒経過した後、別の呼び出し元がエラー メッセージを表示する機会が発生します。Once 5 seconds has passed, then the opportunity arises for another caller to show an error message. これにより、任意の呼び出し元がエラー チャネルを停滞させることが禁止されます。We prohibit any caller from jamming the error channel.

ガイダンス メッセージとエラー メッセージを次に示します。Guidance and error messages are as follows. デバイス名は、コンパニオン デバイス アプリによって、ShowNotificationMessageAsync の一部として渡されるパラメーターです。Device name is a parameter passed by the companion device app as part of ShowNotificationMessageAsync.

ガイダンスGuidance

  • "Swipe up or press space bar to sign in with device name." (デバイス名にサインインするには、上にスワイプするか Space キーを押してください。)"Swipe up or press space bar to sign in with device name."
  • "Setting up your companion device."Setting up your companion device. Please wait or use another sign-in option." (コンパニオン デバイスをセットアップしています。しばらく待機するか、別のサインイン オプションを使用してください。)Please wait or use another sign-in option."
  • "サインインするには、デバイス名 を NFC リーダーにタップしてください。""Tap device name to the NFC reader to sign in."
  • "デバイス名 を探しています...""Looking for device name ..."
  • "サインインするには、デバイス名 を USB ポートに差し込んでください。""Plug device name into a USB port to sign in."

エラーErrors

  • "デバイス名 にサインインする方法を確認してください。""See device name for sign-in instructions."
  • "デバイス名 を使用してサインインするには、Bluetooth をオンにしてください。""Turn on Bluetooth to use device name to sign in."
  • "デバイス名 を使用してサインインするには、NFC をオンにしてください。""Turn on NFC to use device name to sign in."
  • "デバイス名 を使用してサインインするには、Wi-Fi ネットワークに接続してください。""Connect to a Wi-Fi network to use device name to sign in."
  • "デバイス名 をもう一度タップしてください。""Tap device name again."
  • "デバイス名 によるサインインは会社が無効にしています。"Your enterprise prevents sign in with device name. 別のサインイン オプションを使用してください。"Use another sign-in option."
  • "サインインするには、デバイス名 をタップしてください。""Tap device name to sign in."
  • "サインインするには、デバイス名 の上に指を置いてください。""Rest your finger on device name to sign in."
  • "サインインするには、デバイス名 を指でスワイプしてください。""Swipe your finger on device name to sign in."
  • "デバイス名 にサインインできませんでした。"Couldn’t sign in with device name. 別のサインイン オプションを使用してください。"Use another sign-in option."
  • "問題が発生しました。"Something went wrong. 別のサインイン オプションを使用し、その後にデバイス名をもう一度セットアップしてください。"Use another sign-in option, and then set up device name again."
  • "やり直してください。""Try again."
  • "デバイス名に向かって音声パスフレーズを言ってください。""Say your Spoken Passphrase into device name."
  • "デバイス名 にサインインする準備ができています。""Ready to sign in with device name."
  • "を使用することができますし、最初に、別のサインイン オプションを使用して デバイス名 にサインインします"。"Use another sign-in option first, then you can use device name to sign in."

登録されているデバイスの列挙Enumerating registered devices

Windows Hello コンパニオン デバイス アプリは、登録されているコンパニオン デバイスの一覧を、FindAllRegisteredDeviceInfoAsync 呼び出しで列挙できます。The Windows Hello companion device app can enumerate the list of registered companion devices via FindAllRegisteredDeviceInfoAsync call. この API は、SecondaryAuthenticationFactorDeviceFindScope 列挙型で定義される 2 種類のクエリをサポートします。This API supports two query types defined via enum SecondaryAuthenticationFactorDeviceFindScope:

{
    User = 0,
    AllUsers,
}

最初のスコープは、ログオン ユーザーのデバイスの一覧を返します。The first scope returns the list of devices for the logged on user. 2 番目は、その PC 上のすべてのユーザーの一覧を返します。The second one returns the list for all users on that PC. 最初のスコープは、他のユーザーの Windows Hello コンパニオン デバイスの登録が解除されないように、登録解除時に使用する必要があります。The first scope must be used at un-registration time to avoid un-registering another user's Windows Hello companion device. 2 番目は、認証時または登録時に使用する必要があります。登録時のこの列挙は、同じ Windows Hello コンパニオン デバイスが 2 回登録されることを防ぎます。The second one must be used at authentication or registration time: at registration time, this enumeration can help the app avoid trying to register the same Windows Hello companion device twice.

このチェックは、アプリが実行しなくても、PC により実行されるため、同じ Windows Hello コンパニオン デバイスが 2 回以上登録されることはありません。Note that even if the app does not perform this check, the PC does and will reject the same Windows Hello companion device from being registered more than once. 認証時の AllUsers スコープの使用は、Windows Hello コンパニオン デバイス アプリがユーザー切り替えフローをサポートするために役立ちます。このフローでは、ユーザー B がログインしているときにユーザー A をログオンします (両方のユーザーが Windows Hello コンパニオン デバイス アプリをインストール済みであり、ユーザー A が自分のコンパニオン デバイスを PC に登録済みであり、PC がロック画面 (またはログオン画面) を表示している必要があります)。At authentication time, using the AllUsers scope helps the Windows Hello companion device app support switch user flow: log on user A when user B is logged in (this requires that both users have installed the Windows Hello companion device app and user A has registered their companion devices with the PC and the PC is sitting on lock screen (or logon screen)).

セキュリティ要件Security requirements

Companion Authentication Service は、次のセキュリティ保護を提供します。The Companion Authentication Service provides the following security protections.

  • 中間ユーザーまたはアプリ コンテナーとして実行される Windows 10 デスクトップ デバイス上のマルウェアが、Windows Hello コンパニオン デバイスを使用して、PC 上の (Windows Hello の一部として保存されている) ユーザーの資格情報キーに無許可でアクセスすることはできません。Malware on a Windows 10 desktop device running as a medium user or app container cannot use the Windows Hello companion device to access user credential keys (stored as part of Windows Hello) on a PC silently.
  • Windows 10 デスクトップ デバイスの悪意のあるユーザーが、その Windows 10 デスクトップ デバイスの別のユーザーに属する Windows Hello コンパニオン デバイスを使用して、(同じ Windows 10 デスクトップ デバイス上の) 別のユーザーの資格情報キーに無許可でアクセスすることはできません。A malicious user on a Windows 10 desktop device cannot use the Windows Hello companion device that belongs to another user on that Windows 10 desktop device to get silent access to his user credential keys (on the same Windows 10 desktop device).
  • Windows Hello コンパニオン デバイス上のマルウェアが、Windows 10 デスクトップデバイス上のユーザー資格情報キーに無許可でアクセスすることはできません。Windows Hello コンパニオン デバイス フレームワーク専用に開発された機能やコードを利用することもできません。Malware on the Windows Hello companion device cannot silently get access to user credential keys on a Windows 10 desktop device, including leveraging functionality or code developed specifically for the Windows Hello companion device framework.
  • 悪意のあるユーザーが、Windows Hello コンパニオン デバイスと Windows 10 デスクトップ デバイス間のトラフィックをキャプチャし、後で再生リプレイすることで Windows 10 デスクトップ デバイスのロックを解除することはできません。A malicious user cannot unlock a Windows 10 desktop device by capturing traffic between the Windows Hello companion device and the Windows 10 desktop device and replaying it later. プロトコルでの nonce、認証キー、および HMAC の使用によって、リプレイ攻撃からの防御が保証されます。Usage of nonce, authkey, and HMAC in our protocol guarantees protection against a replay attack.
  • ルージュ PC 上のマルウェアまたは悪意のあるユーザーが、Windows Hello コンパニオン デバイスを使用して、正規ユーザーの PC にアクセスすることはできません。Malware or a malicious user on a rouge PC cannot use Windows Hello companion device to get access to honest user PC. これは、Companion Authentication Service と Windows Hello コンパニオン デバイスの間のプロトコルで認証キーと HMAC を使用することで、相互認証を通して実現されます。This is achieved through mutual authentication between Companion Authentication Service and Windows Hello companion device through usage of authkey and HMAC in our protocol.

上記に列挙したセキュリティ保護を実現するために重要なのは、HMAC キーを不正アクセスから保護するとともに、ユーザー プレゼンスを検証することです。The key to achieve the security protections enumerated above is to protect HMAC keys from unauthorized access and also verifying user presence. 具体的には、次の要件を満たす必要があります。More specifically, it must satisfy these requirements:

  • Windows Hello コンパニオン デバイスの複製に対する防御を提供するProvide protection against cloning the Windows Hello companion device
  • 登録時に PC に HMAC キーを送信するときに、傍受に対する防御を提供するProvide protection against eavesdropping when sending HMAC keys at registration time to the PC
  • ユーザー プレゼンス シグナルを入手できることを確認するMake sure that user presence signal is available