ネイティブパスキー API

パスキーは、従来の認証方法 (username とパスワードなど) に代わるフィッシング耐性のある認証手段で、より簡単かつ安全なユーザーエクスペリエンスを提供します。実装の詳細については、モバイルアプリケーション向けネイティブパスキーを参照してください。ネイティブパスキーでは、Auth0 とネイティブの iOS または Android API を組み合わせて、チャレンジフローをモバイルアプリケーションに直接組み込みます。以下に示すエンドポイントは、Auth0 Authentication API の一部です。この API の使用方法の詳細については、Authentication API Introductionを参照してください。パスキーには、関連する 3 つのフローがあります。

Signup: パスキーを主な認証方法として使用する新しいユーザーアカウントを作成します。
Enrollment: 既存のユーザーアカウントに、認証方法としてパスキーを追加します。
Login: 既存のユーザーに対して、そのアカウントに関連付けられたパスキーを使用して認証するよう求めます。

POST /passkey/register 新しいユーザー向けのパスキーのサインアップフローを開始します。レスポンスとして、Auth0 は PublicKeyCredentialCreationOptions とセッション ID を返します。セッションのタイムアウトについては、レスポンス内の authn_params_public_key の timeout を確認してください。パスキーのサインアップフローは、組織のログインフローで説明されている動作に従って、organization パラメーターによる組織のサポートに対応しています。アプリケーションが Business Users 向けに設定されている場合は、organization パラメーターと、有効な組織名または識別子の値を指定する必要があります。ユーザーがパスキーを登録すると、Auth0 はそのユーザーを指定された組織に登録します。

リクエストパラメーター

パラメーター	説明
`client_id`	必須。アプリケーションの `client_id`。
`realm`	任意。このユーザーに関連付ける接続の名前。接続が指定されていない場合は、テナントのデフォルトディレクトリが使用されます。
`user_profile`	必須。ユーザーの識別情報を含むオブジェクト。デフォルトでは、有効な `email` と任意の表示用 `name` が含まれます。データベース接続で Flexible Identifiers を有効にしている場合は、`email`、`phone_number`、`username` を識別子として単独または組み合わせて使用できます。これらのオプションは必須にも任意にも設定でき、Flexible Identifier の設定と一致している必要があります。渡された識別子 (`email` など) がディレクトリ内にすでに存在する場合は、代わりにユーザーに Login フローを完了するよう求めてください。

コードサンプル

リクエスト

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

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "user_profile": {
	  "email": "{VALID_EMAIL_ADDRESS}",
	  "name": "{OPTIONAL_USER_DISPLAY_NAME}",
  }
}

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {MILLISECONDS},
    "rp": {
      "id": "{THE_CUSTOM_DOMAIN}",
      "name": "{THE_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-ENTERED_IDENTIFIER}",
      "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
    }
  },
  "auth_session": "{SESSION_ID}"
}

注記

チャレンジリクエストが完了したら、アプリケーションはネイティブのAndroidまたはiOS API を使用して、ユーザー登録プロセスを続行できます。
その後、フローを完了するには、ネイティブ API を通じて取得した情報を使用して新しいユーザーを認証する必要があります。

新規ユーザーの認証

サインアップ時に同じ接続で SMS/メールアドレス OTP の検証が必要な場合、現在、ネイティブパスキー登録はサポートされていません。

POST /oauth/token を使用して、指定した認証情報でユーザーを認証し、アカウントを作成して、要求されたトークンを返します。 authn_response パラメーターは、Web Authentication API の仕様に基づいています。ネイティブパスキーフローでは、このエンドポイントに渡す情報は、モバイルアプリケーションのネイティブ API を通じて取得できます。

リクエストパラメーター

パラメーター	説明
`grant_type`	必須。次の値を指定します: `urn:okta:params:oauth:grant-type:webauthn`
`client_id`	必須。アプリケーションの `client_id`
`realm`	任意。ユーザーに関連付ける接続の名前です。接続を指定しない場合は、テナントのデフォルトディレクトリが使用されます。
`scope`	任意。IDトークンを取得するには `openid` を使用します。IDトークンにユーザープロファイル情報を含めるには、`openid profile email` を使用します。
`audience`	任意。アクセストークンを取得する対象の API の識別子です。
`auth_session`	必須。最初のパスキーチャレンジリクエストで返されるセッション ID。
`authn_response`	必須。次の項目を含むオブジェクト: `id` `rawId` `type` `authenticatorAttachment` `response`
`authn_response.id`	必須。Base64URL 形式のクレデンシャル ID。
`authn_response.rawId`	必須。Base64URL 形式のクレデンシャル ID。
`authn_response.type`	必須。次の値を指定します: `public-key`
`authn_response.authenticatorAttachment`	必須。次のいずれかの値を指定します: `platform` `cross-platform`
`authn_response.response`	必須。次の項目を含むオブジェクト: `clientDataJSON`: クライアントデータの JSON 互換シリアル化が含まれます。AuthenticatorResponse から継承されます。 `attestationObject`: オーセンティケーターデータとアテステーションステートメントが含まれます。AuthenticatorResponse から継承されます。

コード例

リクエスト

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": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
      "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
      {OTHER_PROPERTIES}
    },
  }
}

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}

登録フロー

ユーザーの新しいパスキーを登録するには、My Account API を使用する 2 段階のプロセスを実行します。このフローにより、パスキー登録が安全に開始され、その後に検証されます。登録フローを開始する前に、/me エンドポイントの create:me:authentication_methods スコープを持つがあることを確認してください。

パスキーの登録を開始する

POST /me/v1/authentication-methods 最初のステップでは、登録プロセスを開始します。これを行うには、/me/v1/authentication-methods エンドポイントに POST リクエストを送信します。

リクエストパラメーター

パラメーター	説明
`type`	必須。値 `public-key` を指定します。
`connection`	任意。パスキーを作成する接続の名前です。
`identity`	任意。ユーザーのアイデンティティです。リンク済みアカウントで使用します。

コード例

リクエスト

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

レスポンス

{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": MILLISECONDS,
    "rp": {
      "id": "CUSTOM_DOMAIN",
      "name": "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_ENTERED_IDENTIFIER",
      "displayName": "USER_ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING"
    }
  },
  "auth_session": "SESSION_ID"
}

注記

レスポンス本文内の auth_session プロパティは、現在の認証セッションの識別子です。これを /verify エンドポイントに渡す必要があります。
チャレンジリクエストの完了後、アプリケーションはネイティブの Android または iOS API を使用して、ユーザーの登録プロセスを続行できます。これにより、ユーザーは認証器 (指紋スキャナー、セキュリティキー、スマートフォンなど) を使ってパスキーを作成するよう求められます。

パスキー登録の確認

POST /me/v1/authentication-methods/passkey|new/verify

新規登録の場合、パス内の ID は常に passkey|new です。

ユーザーが認証器でパスキーの作成に成功すると、クライアントアプリケーションは WebAuthn API から AuthenticatorAttestationResponse を受け取ります。登録を完了して確認するには、このレスポンスを Auth0 サービスに送り返す必要があります。

リクエストパラメーター

パラメーター	説明
`auth_session`	必須。`/me/v1/authentication-methods` への最初の POST リクエストのレスポンスで受け取るセッション識別子。
`authn_response`	必須。`authn_response` パラメーターは Web Authentication API の仕様に基づいています。ネイティブのパスキーフローでは、このエンドポイントに渡す情報はモバイルアプリケーションのネイティブ API から取得できます。
`authn_response.id`	必須。Base64URL 形式のクレデンシャル ID。
`authn_response.rawId`	必須。Base64URL 形式のクレデンシャル ID。
`authn_response.type`	必須。値 `public-key` を指定します。
`authn_response.authenticatorAttachment`	必須。値 `platform` または `cross-platform` を指定します。
`authn_response.response`	必須。次の項目を含むオブジェクトです: `clientDataJson`: クライアントデータの JSON 互換シリアル化を含みます。`AuthenticatorResponse` から継承されます。 `attestationObject`: 認証器データとアテステーションステートメントを含みます。`AuthenticatorResponse` から継承されます。

コードサンプル

リクエスト

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

備考

この手順が正常に完了すると、ユーザーのパスキーが登録され、以後の認証で使用できるようになります。 POST /passkey/challenge 初回のサインアップ時にアカウントにパスキーを保存した既存のユーザーに対して、パスキーのログインフローを開始します。レスポンスとして、Auth0 は PublicKeyCredentialRequestOptions、セッション ID、および Relying Party 識別子 rpId を返します。セッションのタイムアウトは、レスポンス内の authn_params_public_key の timeout を確認してください。レスポンスで返される rpId は、ネイティブデバイス (iOS/Android) がドメインに紐付けられた保存済み認証情報を検索する際に使用する識別子です。Web アプリケーション (例: example.com) で作成されたパスキーをネイティブフローで利用できるようにするには、返される rpId が Web 側の rpId と一致している必要があります。テナントの RP ID をカスタマイズする方法については、Configure Passkey Policy を参照してください。パスキーのログインフローは、組織のログインフローで説明されている動作に従い、organization パラメーターを通じて組織をサポートします。アプリケーションが Business Users 向けに設定されている場合は、organization パラメーターと、有効な組織名または識別子の値を指定する必要があります。発行されるすべてのトークンは、指定された組織のコンテキストで発行されます。組織で Auto-Membership を有効にしている場合、ユーザーは認証に成功した後、その組織に自動的に登録されます.

リクエストパラメーター

パラメーター	説明
`client_id`	必須。アプリケーションの `client_id` です。
`realm`	任意。ユーザーに関連付ける接続の名前です。接続が指定されていない場合は、テナントのデフォルトディレクトリが使用されます。

コード例

リクエスト

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

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

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
    "rpId": "{CUSTOM_DOMAIN}",
    "userVerification": "preferred"
  },
  "auth_session": "{SESSION_ID}"
}

補足

チャレンジリクエストが完了したら、アプリケーションはネイティブの Android または iOS API を使用してログインプロセスを続行できます。
その後、フローを完了するには、ネイティブ API から取得した情報を使用して既存のユーザーを認証する必要があります。

既存ユーザーを認証する

POST /oauth/token トークンエンドポイントを使用して、指定された認証情報でユーザーを認証し、要求されたトークンを返します。 authn_response パラメーターは、Web Authentication API 仕様に基づいています。ネイティブのパスキーフローでは、このエンドポイントに渡す情報を、モバイルアプリケーションのネイティブ API から取得できます。

リクエストパラメーター

Parameter	Description
`grant_type`	必須。次の値を指定します: `urn:okta:params:oauth:grant-type:webauthn`
`client_id`	必須。アプリケーションの `client_id`
`realm`	任意。ユーザーに関連付ける接続の名前。接続を指定しない場合は、テナントのデフォルトディレクトリが使用されます。
`scope`	任意。IDトークンを取得するには `openid` を使用します。IDトークンにユーザープロファイル情報を含めるには `openid profile email` を使用します。
`audience`	任意。アクセストークンを取得する対象 API の API 識別子。
`auth_session`	必須。最初のパスキーチャレンジリクエストで返されるセッション ID。
`authn_response`	必須。次の項目を含むオブジェクト: `id` `rawId` `type` `authenticatorAttachment` `response` `clientExtensionResults`
`authn_response.id`	必須。Base64URL のクレデンシャル ID。
`authn_response.rawId`	必須。Base64URL のクレデンシャル ID。
`authn_response.type`	必須。次の値を指定します: `public-key`
`authn_response.authenticatorAttachment`	任意。次の値を指定します: `platform` `cross-platform`
`authn_response.response`	必須。次の項目を含むオブジェクト: `authenticatorData`: 認証器から返される認証器データを含みます。 `clientDataJSON`: クライアントデータの JSON 互換シリアル化を含みます。AuthenticatorResponse から継承されます。 `signature`: 認証器から返される Base64URL 署名。 `userHandle`: ユーザーアカウントの Base64URL 識別子。登録ステップでは `user.id` として返されます。
`authn_response.clientExtensionResults`	任意。Relying Party が要求したクライアント拡張機能の処理結果を含みます。

コード例

リクエスト

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": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
      "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
      "signature": "{BASE64URL_SIGNATURE}",
      "userHandle": "{BASE64URL_USERHANDLE}"
    },
    "clientExtensionResults": {OPTIONAL_OBJECT}
  },
}

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}

​サインアップフロー

​サインアップチャレンジをリクエスト

​リクエストパラメーター

​コードサンプル

リクエスト

レスポンス

​注記

​新規ユーザーの認証

​リクエストパラメーター

​コード例

リクエスト

レスポンス

​登録フロー

​パスキーの登録を開始する

​リクエストパラメーター

​コード例

リクエスト

レスポンス

​注記

​パスキー登録の確認

​リクエストパラメーター

​コードサンプル

リクエスト

​備考

​ログインフロー

​ログインチャレンジをリクエスト

​リクエストパラメーター

​コード例

リクエスト

レスポンス

​補足

​既存ユーザーを認証する

​リクエストパラメーター

​コード例

リクエスト

レスポンス

サインアップフロー

サインアップチャレンジをリクエスト

リクエストパラメーター

コードサンプル

注記

新規ユーザーの認証

リクエストパラメーター

コード例

登録フロー

パスキーの登録を開始する

リクエストパラメーター

コード例

注記

パスキー登録の確認

リクエストパラメーター

コードサンプル

備考

ログインフロー

ログインチャレンジをリクエスト

リクエストパラメーター

コード例

補足

既存ユーザーを認証する

リクエストパラメーター

コード例