ネイティブ パスキー API

ネイティブ パスキー向けの Auth0 Authentication 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 を通じて取得できます。

• Android の登録ドキュメント
• iOS の登録ドキュメント

​

リクエストパラメーター

パラメーター	説明
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 サービスに送り返す必要があります。

• Android の登録に関するドキュメント
• iOS の登録に関するドキュメント

​

リクエストパラメーター

パラメーター	説明
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 から取得できます。

• Android ログインに関するドキュメント
• iOS ログインに関するドキュメント

​

リクエストパラメーター

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}
}