> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> ネイティブ パスキー向けの Auth0 Authentication API 仕様
# ネイティブ パスキー API
export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
const stageTextMap = {
"beta": "ベータ",
"ea": "早期アクセス"
};
const stageText = stageTextMap[stage] || "製品リリース段階";
const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
const linkify = (text, url) => {
return {text};
};
const includeDetails = (plans, contact, terms) => {
const hasDetails = terms || plans || contact;
if (!hasDetails) return null;
return
{plans && <>この機能は、{linkify(`${plans}プラン`, "https://auth0.com/pricing")}で利用できます。 }
{contact && "参加するには、" + contact + " までお問い合わせください。 "}
{terms && <>この機能を使用すると、Okta の{linkify("Master Subscription Agreement", "https://www.okta.com/legal")}に定める該当する無料トライアル条件に同意したものとみなされます。}
;
};
return
{feature} 機能は現在、{linkify(stageText, prsLink)}です。
{includeDetails(plans, contact, terms)}
;
};
パスキーは、従来の認証方法 (username とパスワードなど) に代わるフィッシング耐性のある認証手段で、より簡単かつ安全なユーザーエクスペリエンスを提供します。実装の詳細については、[モバイルアプリケーション向けネイティブ パスキー](/ja/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications)を参照してください。
ネイティブ パスキーでは、Auth0 とネイティブの iOS または Android API を組み合わせて、チャレンジフローをモバイルアプリケーションに直接組み込みます。以下に示すエンドポイントは、Auth0 Authentication API の一部です。この API の使用方法の詳細については、[Authentication API Introduction](https://auth0.com/docs/api/authentication#introduction)を参照してください。
パスキーには、関連する 3 つのフローがあります。
* **Signup**: パスキーを主な認証方法として使用する新しいユーザーアカウントを作成します。
* **Enrollment**: 既存のユーザーアカウントに、認証方法としてパスキーを追加します。
* **Login**: 既存のユーザーに対して、そのアカウントに関連付けられたパスキーを使用して認証するよう求めます。
## サインアップフロー
### サインアップチャレンジをリクエスト
`POST /passkey/register`
新しいユーザー向けのパスキーのサインアップフローを開始します。
レスポンスとして、Auth0 は [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) とセッション ID を返します。セッションのタイムアウトについては、レスポンス内の `authn_params_public_key` の `timeout` を確認してください。
パスキーのサインアップフローは、[組織のログインフロー](/ja/docs/manage-users/organizations/login-flows-for-organizations) で説明されている動作に従って、`organization` パラメーターによる組織のサポートに対応しています。アプリケーションが **Business Users** 向けに設定されている場合は、`organization` パラメーターと、有効な組織名または識別子の値を指定する必要があります。ユーザーがパスキーを登録すると、Auth0 はそのユーザーを指定された組織に登録します。
#### リクエストパラメーター
| パラメーター | 説明 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | **必須**。アプリケーションの `client_id`。 |
| `realm` | **任意**。このユーザーに関連付ける接続の名前。
接続が指定されていない場合は、テナントのデフォルトディレクトリが使用されます。 |
| `user_profile` | **必須**。ユーザーの識別情報を含むオブジェクト。デフォルトでは、有効な `email` と任意の表示用 `name` が含まれます。
データベース接続で [Flexible Identifiers](/ja/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) を有効にしている場合は、`email`、`phone_number`、`username` を識別子として単独または組み合わせて使用できます。これらのオプションは必須にも任意にも設定でき、Flexible Identifier の設定と一致している必要があります。
渡された識別子 (`email` など) がディレクトリ内にすでに存在する場合は、代わりにユーザーに Login フローを完了するよう求めてください。 |
#### コードサンプル
##### リクエスト
```text lines theme={null}
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}",
}
}
```
##### レスポンス
```json lines expandable theme={null}
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](https://developer.android.com/identity/passkeys/create-passkeys)または[iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) API を使用して、ユーザー登録プロセスを続行できます。
* その後、フローを完了するには、ネイティブ API を通じて取得した情報を使用して[新しいユーザーを認証する](#authenticate-new-user)必要があります。
### 新規ユーザーの認証
サインアップ時に同じ接続で SMS/メールアドレス OTP の検証が必要な場合、現在、ネイティブ パスキー登録はサポートされていません。
`POST /oauth/token`
トークンエンドポイント を使用して、指定した認証情報でユーザーを認証し、アカウントを作成して、要求されたトークンを返します。
`authn_response` パラメーターは、[Web Authentication API の仕様](https://www.w3.org/TR/webauthn-3/) に基づいています。ネイティブ パスキーフローでは、このエンドポイントに渡す情報は、モバイルアプリケーションのネイティブ API を通じて取得できます。
* [Android の登録ドキュメント](https://developer.android.com/identity/passkeys/create-passkeys)
* [iOS の登録ドキュメント](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)
#### リクエストパラメーター
| パラメーター | 説明 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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](https://www.w3.org/TR/webauthn-3/#authenticatorresponse) から継承されます。
- `attestationObject`: オーセンティケーターデータと アテステーションステートメント が含まれます。[AuthenticatorResponse](https://www.w3.org/TR/webauthn-3/#authenticatorresponse) から継承されます。
|
#### コード例
##### リクエスト
```text lines theme={null}
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}
},
}
}
```
##### レスポンス
```json lines theme={null}
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` | **任意**。ユーザーのアイデンティティです。リンク済みアカウントで使用します。 |
#### コード例
##### リクエスト
```json lines theme={null}
{
"type": "passkey",
"connection": "CONNECTION_NAME",
"identity": "IDENTITY_USER_ID"
}
```
##### レスポンス
```json lines theme={null}
{
"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](https://developer.android.com/identity/passkeys/create-passkeys) または [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) API を使用して、ユーザーの登録プロセスを続行できます。これにより、ユーザーは認証器 (指紋スキャナー、セキュリティキー、スマートフォンなど) を使ってパスキーを作成するよう求められます。
### パスキー登録の確認
`POST /me/v1/authentication-methods/passkey|new/verify`
新規登録の場合、パス内の ID は常に `passkey|new` です。
ユーザーが認証器でパスキーの作成に成功すると、クライアントアプリケーションは WebAuthn API から `AuthenticatorAttestationResponse` を受け取ります。登録を完了して確認するには、このレスポンスを Auth0 サービスに送り返す必要があります。
* [Android の登録に関するドキュメント](https://developer.android.com/identity/passkeys/create-passkeys)
* [iOS の登録に関するドキュメント](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)
#### リクエストパラメーター
| パラメーター | 説明 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` から継承されます。
|
#### コードサンプル
##### リクエスト
```json lines theme={null}
{
"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](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions)、セッション ID、および Relying Party 識別子 `rpId` を返します。セッションのタイムアウトは、レスポンス内の `authn_params_public_key` の `timeout` を確認してください。レスポンスで返される `rpId` は、ネイティブデバイス (iOS/Android) がドメインに紐付けられた保存済み認証情報を検索する際に使用する識別子です。Web アプリケーション (例: `example.com`) で作成されたパスキーをネイティブフローで利用できるようにするには、返される `rpId` が Web 側の `rpId` と一致している必要があります。テナントの RP ID をカスタマイズする方法については、[Configure Passkey Policy](/ja/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rp-id) を参照してください。
パスキーのログインフローは、[組織のログインフロー](/ja/docs/manage-users/organizations/login-flows-for-organizations) で説明されている動作に従い、`organization` パラメーターを通じて組織をサポートします。アプリケーションが **Business Users** 向けに設定されている場合は、`organization` パラメーターと、有効な組織名または識別子の値を指定する必要があります。
発行されるすべてのトークンは、指定された組織のコンテキストで発行されます。組織で [Auto-Membership](/ja/docs/manage-users/organizations/login-flows-for-organizations#auto-membership) を有効にしている場合、ユーザーは認証に成功した後、その組織に自動的に登録されます.
#### リクエストパラメーター
| パラメーター | 説明 |
| ----------- | ---------------------------------------------------------------------------- |
| `client_id` | **必須**。アプリケーションの `client_id` です。 |
| `realm` | **任意**。ユーザーに関連付ける接続の名前です。
接続が指定されていない場合は、テナントのデフォルトディレクトリが使用されます。 |
#### コード例
##### リクエスト
```text lines theme={null}
POST /passkey/challenge
Content-Type: application/json
{
"client_id": "{YOUR_CLIENT_ID}",
"realm": "{OPTIONAL_CONNECTION}"
}
```
##### レスポンス
```json lines theme={null}
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](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) または [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) API を使用してログインプロセスを続行できます。
* その後、フローを完了するには、ネイティブ API から取得した情報を使用して [既存のユーザーを認証](#authenticate-existing-user) する必要があります。
### 既存ユーザーを認証する
`POST /oauth/token`
トークンエンドポイントを使用して、指定された認証情報でユーザーを認証し、要求されたトークンを返します。
`authn_response` パラメーターは、[Web Authentication API 仕様](https://www.w3.org/TR/webauthn-3/) に基づいています。ネイティブのパスキーフローでは、このエンドポイントに渡す情報を、モバイルアプリケーションのネイティブ API から取得できます。
* [Android ログインに関するドキュメント](https://developer.android.com/identity/passkeys/sign-in-with-passkeys)
* [iOS ログインに関するドキュメント](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account)
#### リクエストパラメーター
| 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`: 認証器から返される[認証器データ](https://www.w3.org/TR/webauthn-3/#authenticator-data)を含みます。
- `clientDataJSON`: クライアントデータの JSON 互換シリアル化を含みます。[AuthenticatorResponse](https://www.w3.org/TR/webauthn-3/#authenticatorresponse) から継承されます。
- `signature`: 認証器から返される Base64URL 署名。
- `userHandle`: ユーザーアカウントの Base64URL 識別子。登録ステップでは `user.id` として返されます。
|
| `authn_response.clientExtensionResults` | **任意**。Relying Party が要求したクライアント拡張機能の処理結果を含みます。 |
#### コード例
##### リクエスト
```text lines theme={null}
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}
},
}
```
##### レスポンス
```json lines theme={null}
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}
}
```