埋め込みアプリケーション向けパスキー API

Auth0 Passkey API を使用して、iOS、Android、Web アプリケーション向けの埋め込み型パスキーのサインアップ、ログイン、登録フローを構築します。

パスキーは、ユーザー名とパスワードなどの従来の認証方法に代わる、フィッシング耐性を備えた認証方式です。より簡単で安全なユーザー体験を提供します。FIDO® W3C Web Authentication (WebAuthn) および Client to Authenticator Protocol (CTAP) の仕様に基づいています。

Auth0 では現在、データベース接続の認証方法として、以下の 2 つの方法でパスキーを実装できます。

• Web アプリケーション向けの Universal Login パスキー。
• Nativeモバイルアプリケーション (iOS、Android) および Web アプリケーション向けの Passkey API。
• Web および Nativeアプリケーション向けの埋め込みログイン

開始する前に

カスタムドメインを設定する

Nativeパスキーを使用するには、カスタムドメインが必要です。続行する前に、テナント用のカスタムドメインを設定済みであることを確認してください。詳細については、カスタムドメインを参照してください。

パスキーポリシーを設定する

Android または iOS アプリケーションに Nativeパスキーを実装するには、Auth0 テナントでパスキーポリシーを設定する必要があります。テナントを準備するには、パスキーポリシーの設定の手順に従ってください。

アプリケーションを準備する

Passkey API を使用するすべてのアプリケーションでは、Passkey グラントを追加し、Relying Party ID (RP ID) を設定する必要があります。プラットフォームによっては、Auth0 DashboardまたはManagement APIで追加設定が必要になる場合もあります。

​

仕組み

パスキー API では、Auth0 Authentication API とプラットフォーム固有の認証情報 API を組み合わせて、チャレンジフローをアプリケーションに直接組み込みます。Native モバイルアプリでは iOS または Android のプラットフォーム API を、Web アプリケーションでは WebAuthn ブラウザー API を使用します。これにより、認証を完了するためにユーザーをブラウザーへリダイレクトすることなく、サインアップからログインまでをシームレスに統合できます。

以下の例は、新規ユーザーがパスキーのサインアップフローで体験する流れを示しています。

1. 新規ユーザーがモバイルアプリケーションを起動し、ログイン画面を開きます。新規ユーザーのため、Sign Up を選択します。
2. 次の画面で、ユーザーはメールアドレスを入力し、Create Account を選択します。
3. 次に、アプリケーション用のパスキーを作成するかどうかをユーザーに尋ねます。続行するには、Continue を選択します。
4. パスキーを生成するには、ユーザーは生体認証や PIN の入力などの認証方法で、デバイス上でローカル認証を行う必要があります。
5. ローカル認証が完了すると、新しいパスキーがユーザーのデバイスに保存され、iCloud Keychain や Google Password Manager などのパスキープロバイダーと同期されます。
6. パスキーが保存されると、ユーザーは新規ユーザー登録プロセスを続行してアカウントを確定します。

このプロセスが完了すると、ユーザーは次回アプリケーションにログインする際、保存したパスキーで認証できます。

​

デバイス設定を構成する

iOS

Auth0 Dashboard でデバイス設定を構成する:

1. アプリケーション > アプリケーション に移動し、アプリケーションを選択します。
2. Settings タブの下部にある Advanced Settings を選択します。
3. Device Settings タブを選択します。
4. iOS セクションで、Apple の以下の ID を入力します。
   • Team ID
   • App ID
5. 変更を保存 を選択します。

• Auth0 は、設定した Team ID と App ID に基づき、テナントのカスタムドメインの https://YOUR_CUSTOM_DOMAIN/.well-known/apple-app-site-association で apple-app-site-association ファイルを自動的にホストします。このファイルを自分でホストする必要はありません。

• Xcode で Associated Domains エンタイトルメントを有効にし、webcredentials:YOUR_CUSTOM_DOMAIN のような形式でカスタムドメインのエントリを追加します。

Android

Auth0 Dashboard でデバイス設定を構成する:

1. アプリケーション > アプリケーション に移動し、アプリケーションを選択します。
2. Settings タブの下部にある Advanced Settings を選択し、次に Device Settings タブを選択します。
3. Android セクションで、以下を入力します。
   • App Package Name
   • Key Hashes。アプリケーションの SHA-256 signing certificate を入力します。
4. 変更を保存 を選択します。

Auth0 は、設定したパッケージ名と SHA-256 フィンガープリントに基づき、テナントのカスタムドメインの https://YOUR_CUSTOM_DOMAIN/.well-known/assetlinks.json で assetlinks.json ファイルをホストします。このファイルを自分でホストする必要はありません。

Web

許可する Web オリジンを構成する:

1. アプリケーション > アプリケーション に移動し、アプリケーションを選択します。
2. Settings タブで、Application URIs を見つけます。
3. Allowed Web Origins に、Web アプリケーションのオリジン (例: https://YOUR_CUSTOM_DOMAIN) を追加します。
4. 変更を保存 を選択します。

• Web アプリは WebAuthn ブラウザー API を使用するため、オリジンのバリデーションは自動的に処理されます。Web アプリケーションにアプリケーション関連付けファイルは必要ありません。
• WebAuthn フローを正常に完了するには、Relying Party ID である rpId が Web アプリのオリジンと一致していることを確認してください。

​

Passkey グラントを有効にする

すべてのプラットフォームで Passkey グラントを有効にするには、次の手順を実行します。

1. アプリケーション > アプリケーションに移動し、対象のアプリケーションを選択します。
2. Advanced Settingsセクションで、Grant Types タブを選択します。
3. Passkey グラントを有効にして、変更を保存 を選択します。

または、Management APIを使用します。 Update a Clientエンドポイントを呼び出し、次の操作を行います。

• grant_types に urn:okta:params:oauth:grant-type:webauthn を追加します。
• Nativeアプリでは、必要に応じて mobile オブジェクトを使用し、iOSおよびAndroidのデバイス設定を指定します。

​

Relying party ID (rpId)

エンドユーザーが異なるアプリケーションの種類や異なるサブドメインを持つアプリケーションの種類で同じパスキーを使用して認証できるようにするには、Auth0 Dashboard > Tenant Settings でrelying party ID を設定し、ルートドメインまたは親ドメインを指定します。

​

パスキーフローを実装する

アプリケーションでは、次のパスキーフローを定義できます。

• Signup flow：新規ユーザーがユーザー登録時にパスキーを生成して保存できるようにします。
• ログインフロー：すでにパスキーを登録している既存ユーザーが、ログインプロセス中に保存済みのパスキーで認証できるようにします。
• 登録フロー：既存ユーザーが認証後にアカウントにパスキーを追加できるようにします。

​

サインアップフロー

ユーザーは、アプリケーションへの初回ログイン時にパスキーのサインアップフローを開始します。ユーザーがすでに存在する識別子を入力した場合は、代わりにログインフローを完了するよう促すことをお勧めします。そうしないと、処理は失敗します。

同じ接続でSMS/Email OTPによる検証が必要な場合、サインアップ時のNative Passkey登録はサポートされていません。

1. アプリケーションは、POST /passkey/registerエンドポイントを呼び出してサインアップチャレンジを開始します。

POST /passkey/register
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "user_profile": {
    "email": "[e-mail]",
    "name": "John Doe"
  }
},

• realmを指定しない場合は、テナントのデフォルトディレクトリが使用されます。
• デフォルトでは、emailが必須の識別子です。データベース接続でFlexible Identifiersを有効化している場合は、email、phone_number、usernameを組み合わせて使用できます。

2. Auth0は、パスキーの作成に必要なPublicKeyCredentialCreationOptionsとauth_session IDを返します。

{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rp": {
      "id": "YOUR_CUSTOM_DOMAIN",
      "name": "YOUR_CUSTOM_DOMAIN"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -8 },
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "GENERATED_ID",
      "name": "USER_EMAIL",
      "displayName": "USER_EMAIL_OR_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}

3. アプリケーションは、返された PublicKeyCredentialCreationOptions を使用して、ユーザーのデバイスにパスキーを作成します。作成方法はプラットフォームによって異なります。

iOS

ASAuthorizationPlatformPublicKeyCredentialProvider を使用して、Face ID、Touch ID、またはデバイスの PIN で資格情報を作成します。詳細については、iOS の登録に関するドキュメントを参照してください。

Android

CredentialManager を使用して、生体認証またはデバイスの PIN 認証で資格情報を作成します。詳細については、Android の登録に関するドキュメントを参照してください。

Web

Auth0 から返された PublicKeyCredentialCreationOptions を使用して、navigator.credentials.create() を呼び出します。詳細については、MDN Web Authentication APIを参照してください。

4. アプリケーションは、登録プロセスで取得した資格情報を使用して POST /oauth/token エンドポイントを呼び出し、資格情報をトークンと交換します。

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "scope": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}

5. Auth0 は新しいユーザーアカウントを作成し、以下の戻り値の例に示すように、要求されたトークンを返します。

{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}

サインアップフローの呼び出しとパラメータについては、Authentication API Explorerを参照してください。

​

ログインフロー

既存のユーザーがアプリケーションにログインしようとすると、パスキーによるログインフローが開始されます。このフローは、初回のサインアップ時にアカウントにパスキーを保存した既存ユーザーにのみ適用されます。

1. アプリケーションは、ログインチャレンジを開始するために POST /passkey/challenge エンドポイントを呼び出します。

POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION"
}

realmを指定しない場合は、テナントのデフォルトディレクトリが使用されます。

2. Auth0 は PublicKeyCredentialRequestOptions と auth_session を返します。

{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rpId": "YOUR_CUSTOM_DOMAIN",
    "userVerification": "preferred"
  },
  "auth_session": "SESSION_ID"
}

3. アプリケーションは、返された PublicKeyCredentialRequestOptions を使用して、ユーザーのデバイスからパスキーを取得します。方法はプラットフォームによって異なります。

iOS

ASAuthorizationPlatformPublicKeyCredentialProvider を使用して、Face ID、Touch ID、またはデバイスの PIN で資格情報を取得します。詳細については、iOS のログインに関するドキュメントを参照してください。

Android

CredentialManager を使用して、生体認証またはデバイスの PIN による認証で資格情報を取得します。詳細については、Android のログインに関するドキュメントを参照してください。

Web

Auth0 から返された PublicKeyCredentialRequestOptions を指定して、navigator.credentials.get() を使用します。詳細については、MDN Web Authentication APIを参照してください。

4. アプリケーションは、ログインプロセスで取得した資格情報を使用して POST /oauth/token エンドポイントを呼び出し、資格情報をトークンと交換します。

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "scope": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "authenticatorData": "BASE64URL_AUTHENTICATORDATA",
      "clientDataJSON": "BASE64URL_CLIENTDATAJSON",
      "signature": "BASE64URL_SIGNATURE",
      "userHandle": "BASE64URL_USERHANDLE"
    },
    "clientExtensionResults": {}
  }
}

5. Auth0 は資格情報を認証し、要求されたトークンを返します。

{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}

ログインフローの呼び出しとパラメータについて詳しくは、Authentication API Explorerを参照してください。

​

登録フロー

登録フローでは、ユーザー名とパスワードなどの別の方法で認証済みのユーザーが、アカウントにパスキーを追加できます。認証済みの既存ユーザーが新しいパスキーを登録する場合は、My Account API を使用します。

開始する前に

登録フローを開始する前に、次のことを確認してください。

1. テナントの My Account API を有効化します。
2. /me エンドポイント用の create:me:authentication_methods スコープを持つアクセストークンを取得します。

詳しい設定手順については、My Account API を参照してください。

1. 認証済みのアプリケーションから、アクセストークンを使用して POST /me/v1/authentication-methods エンドポイントを呼び出します。

POST /me/v1/authentication-methods
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "type": "passkey",
  "connection": "CONNECTION_NAME"
}

2. Auth0 はチャレンジとセッション ID を返します。

{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE",
    "timeout": 60000,
    "rp": {
      "id": "YOUR_CUSTOM_DOMAIN",
      "name": "YOUR_CUSTOM_DOMAIN"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -8 },
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "GENERATED_ID",
      "name": "USER_IDENTIFIER",
      "displayName": "USER_DISPLAY_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}

3. アプリケーションは、サインアップフローと同じプラットフォーム固有の手順に従って、返された PublicKeyCredentialCreationOptions を使用し、ユーザーのデバイスにパスキーを作成します。

iOS

ASAuthorizationPlatformPublicKeyCredentialProvider を使用して、Face ID、Touch ID、またはデバイスの PIN で資格情報を作成します。詳細については、iOS の登録に関するドキュメントを参照してください。

Android

CredentialManager を使用して、生体認証またはデバイスの PIN 認証で資格情報を作成します。詳細については、Android の登録に関するドキュメントを参照してください。

Web

Auth0 から返された PublicKeyCredentialCreationOptions を使用して、navigator.credentials.create() を呼び出します。詳細については、MDN Web Authentication APIを参照してください。

4. ユーザーが認証器を使用してパスキーを作成した後、POST /me/v1/authentication-methods/passkey|new/verify エンドポイントを呼び出して登録を完了します。

POST /me/v1/authentication-methods/passkey|new/verify
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}

このステップが正常に完了すると、ユーザーのパスキーが登録され、以降の認証で使用できるようになります。

登録フローの呼び出しとパラメータの詳細については、My Account API explorerを参照してください。

​

Relying party ID

いずれかのアプリケーションで作成したパスキーは、同じ relying party ID (rpId) を共有する他のアプリケーション (Native または Web アプリケーション) へのサインインにも使用できます。これは、パスキープロバイダー (iCloud Keychain、Google Password Manager、1Password、Dashlane など) が、同一プロバイダー内でユーザーのデバイス間の資格情報を同期するためです。

​

プラットフォーム間でユーザーを移行する

ほとんどの場合、ユーザーが QR コードをスキャンしたり、2 台目のデバイスを使用したりする必要はありません。フローは、使用中のデバイスでパスキーをすでに利用できるかどうかによって異なります。

• 同じプロバイダーで異なるデバイス (最も一般的) ：ユーザーが iOS アプリでパスキーを登録すると、iCloud Keychain によってそのパスキーが Mac に同期され、すぐにウェブアプリにサインインできます。同様に、同じ Google アカウントにログインしている Chromebook または Windows PC の Chrome では、Google Password Manager 経由で同期された Android のパスキーを使用できます。
• 異なるエコシステム間または共有デバイスの場合 (比較的まれ) ：使用中のデバイスでパスキーを利用できない場合 (たとえば、Windows PC で iPhone のパスキーを使用する場合や、公共のコンピューターを使用する場合) 、ブラウザーはハイブリッドトランスポート (CTAP 2.2) を使用してユーザーの電話で認証するための QR コードを表示します。パスキーはユーザーの電話に保持され、QR コードはその 1 回のサインイン時に限り、2 台のデバイスをつなぐ役割を果たします。

​

Relying Party IDを選択する

rpId は、どのオリジンでパスキーを使用できるかを決定します。Auth0 はデフォルトで rpId をカスタムドメインに設定します。パスキーを利用可能にしたい範囲に最も適し、それ以上に広くならない rpId を選択してください。

推奨: auth.example.com や accounts.example.com のように、認証およびプロダクトの画面に範囲を限定する親ドメインを使用します。rpId=auth.example.com で作成されたパスキーは、auth.example.com とそのすべてのサブドメイン (例: app.auth.example.com、m.auth.example.com) で使用できます。

eTLD+1 (登録可能な最上位ドメイン) を rpId として使用しないでください — たとえば、example.com です。このレベルで rpId を設定すると、マーケティングサイト、サードパーティがホストするサービス、他のチームが運用するドメインを含め、example.com のすべてのサブドメインがこれらのパスキーをリクエストして使用できるようになります。これにより、信頼境界が認証画面をはるかに超えて広がります。

Relying Party IDの詳細については、RP ID Deep Diveを参照してください。

​

複数ドメインおよびブランドのシナリオ

複数のブランドドメイン (例: login.brand1.com と login.brand2.com) を使用している場合、パスキーはドメイン間で自動的に機能するわけではありません。各ドメインにはそれぞれ固有の rpId があります。ドメインごとの登録、ユーザーへの案内、移行パターンについては、複数のカスタムドメインでのパスキーを参照してください。

​

設定チェックリスト

rpId を選択したら、すべてのアプリケーションで同じものを使用していることを確認してください。

1. パスキーを共有するすべての Native および Web アプリケーションで、1 つのカスタムドメインを rpId として使用します。
2. Nativeアプリケーションでは、Auth0 Dashboard の デバイス設定 で iOS Team ID/App ID と Android パッケージ名/SHA-256 フィンガープリントを設定します。Auth0 は、カスタムドメインで apple-app-site-association ファイルと assetlinks.json ファイルを自動的にホストします。
3. Web アプリケーションでは、Web オリジンを rpId またはそのサブドメインから提供し、CORS 用に Allowed Web Origins に追加します。

​

詳細情報

アプリケーションにパスキー認証を実装する際には、以下のリソースを参照してください。

• Auth0 API

  • Authentication API: パスキー認証のエンドポイントを確認します。
  • My Account API: パスキー登録のエンドポイントについて確認します。
  • My Account API ドキュメント: 有効化、スコープ、CORS について確認します。

• プラットフォームドキュメント

  • Apple Developer: パスキーのサポート
  • Android Developers: パスキーを作成する
  • Android Developers: パスキーでログインする
  • MDN Web Authentication API
  • WebAuthn 仕様

• 追加リソース

  • passkeys.dev: パスキー実装に関する包括的なガイド。