認証情報マネージャーで認証情報の復元を実装する

このページでは、復元キーの作成、復元キーを使用したログイン、復元キーの削除を行う方法について説明します。

バージョンの互換性

Credential Manager の Restore Credentials は、Android 9 以降、Google Play 開発者サービス（GMS）コア バージョン 24220000 以降、および androidx.credentials ライブラリ バージョン 1.5.0 以降を搭載したデバイスで動作します。

前提条件

パスキーのサーバーと同様の証明書利用者サーバーをセットアップします。パスキーによる認証を処理するように サーバーがすでに設定されている場合は、復元キーにも同じサーバーサイド実装を使用します。

依存関係

アプリ モジュールの build.gradle ファイルに次の依存関係を追加します。

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

認証情報の復元は、androidx.credentials ライブラリのバージョン 1.5.0 以降で利用できます。ただし、可能な限り、依存関係の最新の安定版を使用することをおすすめします。

概要

  1. 復元キーを作成する: 復元キーを作成するには、次の手順を行います。
    1. 認証情報マネージャーをインスタンス化する: CredentialManager オブジェクトを作成します。
    2. アプリサーバーから認証情報作成オプションを取得する: アプリサーバーから復元キーを作成するために必要な詳細情報をクライアント アプリに送信します。
    3. 復元キーを作成する: ユーザーがアプリにログインしている場合は、ユーザーのアカウントの復元キーを作成します。
    4. 認証情報の作成レスポンスを処理する: クライアント アプリからアプリサーバーに認証情報を送信して処理し、例外を処理します。
  2. 復元キーでログインする: 復元キーでログインする手順は次のとおりです。
    1. アプリサーバーから認証情報取得オプションを取得する: アプリサーバーから復元キーを取得するために必要な詳細情報をクライアント アプリに送信します。
    2. 復元キーを取得する: ユーザーが新しいデバイスをセットアップするときに、認証情報マネージャーから復元キーをリクエストします。これにより、ユーザーは追加の入力をせずにログインできます。
    3. 認証情報の取得レスポンスを処理する: クライアント アプリからアプリサーバーに復元キーを送信して、ユーザーをログインさせます。
  3. 復元キーを削除します。

復元キーを作成する

復元鍵は、ユーザーがアプリで認証を行った後（ログイン直後、またはすでにログインしている場合はアプリの起動時）に作成します。

認証情報マネージャーをインスタンス化する

アプリのアクティビティ コンテキストを使用して CredentialManager オブジェクトをインスタンス化します。

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

アプリサーバーから認証情報作成オプションを取得する

アプリサーバーで FIDO 準拠のライブラリを使用して、復元認証情報の作成に必要な情報（ユーザー、アプリ、追加の構成プロパティに関する情報など）をクライアント アプリに送信します。サーバーサイドの実装について詳しくは、サーバーサイドのガイダンスをご覧ください。

復元キーを作成する

サーバーから送信された公開鍵作成オプションを解析した後、これらのオプションを CreateRestoreCredentialRequest オブジェクトでラップし、CredentialManager オブジェクトで createCredential() メソッドを呼び出して、復元鍵を作成します。

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

コードに関する主なポイント

  • CreateRestoreCredentialRequest オブジェクトには次のフィールドがあります。

    • requestJson: PublicKeyCredentialCreationOptionsJSON の Web Authentication API 形式でアプリサーバーから送信される認証情報の作成オプション。

    • isCloudBackupEnabled: 復元キーをクラウドにバックアップするかどうかを決定する Boolean フィールド。デフォルトでは、このフラグは true です。このフィールドには次の値があります。

      • true:（推奨）この値は、ユーザーが Google バックアップとエンドツーエンド暗号化（画面ロックなど）を有効にしている場合、復元キーのクラウドへのバックアップを有効にします。
      • false: この値は、鍵をクラウドではなくローカルに保存します。ユーザーがクラウドからの復元を選択した場合、新しいデバイスで鍵を使用することはできません。

認証情報の作成レスポンスを処理する

Credential Manager API は、CreateRestoreCredentialResponse 型のレスポンスを返します。このレスポンスには、JSON 形式の公開鍵認証情報の登録レスポンスが含まれます。

アプリから証明書利用者サーバーに公開鍵を送信します。この公開鍵は、パスキーの作成時に生成される公開鍵と似ています。サーバーでパスキーの作成を処理する同じコードで、復元キーの作成も処理できます。サーバーサイドの実装について詳しくは、パスキーのガイダンスをご覧ください。

復元キーの作成プロセス中に、次の例外を処理します。

  • CreateRestoreCredentialDomException: requestJson が無効で、PublicKeyCredentialCreationOptionsJSON の WebAuthn 形式に従っていない場合に発生します。
  • E2eeUnavailableException: isCloudBackupEnabled が true であるにもかかわらず、ユーザーのデバイスにデータ バックアップやエンドツーエンドの暗号化（画面ロックなど）がない場合、この例外が発生します。
  • IllegalArgumentException: createRestoreRequest が空または有効な JSON でない場合、または WebAuthn の仕様に準拠する有効な user.id がない場合に、この例外が発生します。

復元キーを使用してログインする

デバイスのセットアップ プロセス中に、Restore Credentials を使用してユーザーをサイレントでログインさせます。

アプリサーバーから認証情報取得オプションを取得する

サーバーから復元キーを取得するために必要なオプションをクライアント アプリに送信します。この手順に関する同様のパスキーのガイダンスについては、パスキーでログインするをご覧ください。サーバーサイドの実装について詳しくは、サーバーサイド認証ガイドをご覧ください。

復元キーを取得する

新しいデバイスで復元キーを取得するには、CredentialManager オブジェクトの getCredential() メソッドを呼び出します。

復元キーは、次のシナリオで取得できます。

  • （推奨）アプリデータの復元直後。BackupAgent を使用してアプリのバックアップを設定し、onRestore コールバック内で getCredential 機能を完了して、アプリのデータが復元された直後にアプリの認証情報が復元されるようにします。これにより、ユーザーが新しいデバイスを初めて開いたときに遅延が発生する可能性を回避し、ユーザーがアプリを開くのを待たずに操作できるようになります。
  • デバイスでアプリを初めて起動したとき。

ユーザーが新しいデバイスでアプリを初めて開く前に通知を送信するには、BackupAgent の onRestore コールバック内で復元キーを取得します。これは、メッセージ アプリやコミュニケーション アプリに特に当てはまります。

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

認証情報マネージャー API は、GetCredentialResponse 型のレスポンスを返します。このレスポンスには公開鍵が含まれています。

ログイン レスポンスを処理する

アプリから証明書利用者サーバーに公開鍵を送信します。この公開鍵は、ユーザーのログインに使用できます。サーバー側では、このアクションはパスキーを使用したログインに似ています。サーバーでパスキーによるログインを処理する同じコードで、復元キーによるログインも処理できます。パスキーのサーバーサイド実装について詳しくは、パスキーでログインするをご覧ください。

復元キーを削除する

Credential Manager はステートレスでユーザー アクティビティを認識しないため、使用後に復元キーを自動的に削除することはありません。復元キーを削除するには、clearCredentialState() メソッドを呼び出します。セキュリティのため、ユーザーがログアウトするたびにキーを削除します。これにより、ユーザーが同じデバイスで次回アプリを開いたときに、ユーザーはログアウトされ、再度ログインするよう求められます。

アプリのアンインストールは、ログアウト時のユーザーの意図と同様に、対応する復元キーをデバイスから削除する意図と解釈されます。

復元キーは、次の場合にのみ削除されます。

  • システムレベルのアクション: ユーザーがアプリをアンインストールするか、アプリのデータを消去します。
  • アプリレベルの呼び出し: アプリのコードでユーザーのログアウトを処理するときに、clearCredentialState() を呼び出してキーをプログラムで削除します。

ユーザーがアプリからログアウトしたら、CredentialManager オブジェクトの clearCredentialState() メソッドを呼び出します。

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)