My Account API

My Account API を使用して、ユーザーが自分のアカウント情報を管理できるようにする方法を学びます。

Auth0 My Account API は、ユーザーが自分のアカウント情報を管理するための専用のエンドポイント群を提供します。お客様はこれらの API を使用して、アプリケーション内にセルフサービス機能を構築したり、ユーザーアカウントの詳細情報を段階的に追加したりできます。

My Account API は現在ログインしているユーザーのコンテキストで動作し、ユーザー向けアプリケーション内で直接使用できます。

Auth0 ドメインとカスタムドメインの使い分け

My Account API では、正規の Auth0 ドメインまたはカスタムドメインを使用できますが、次の項目を含め、プロセス全体を通じて同じドメインを使用する必要があります。

• アクセストークンを取得する
• audience の値を設定する
• My Account API エンドポイントを呼び出す

詳細については、Custom Domains をご覧ください。

​

My Account API を有効化する

Auth0 Dashboard で、テナントの My Account API を有効化できます。

1. Applications > APIs に移動します。
2. MyAccount API バナーを見つけます。
3. 有効化 を選択します。

デフォルトでは、Auth0 は My Account API を次のアプリケーション API アクセスポリシーで作成します。

• ユーザーフローには require_client_grant
• クライアント (machine-to-machine) フローには deny_all

アプリケーションがユーザーに代わって My Account API にアクセスするには、そのアプリケーション用のクライアントグラントを明示的に作成する必要があります。これにより、アプリケーションが要求できる最大のスコープを定義できます。あるいは、ユーザーアクセ スフローのポリシーを allow_all に変更することもできます。これにより、テナント内の任意のアプリケーションが My Account API の任意のスコープを要求できるようになります。

My Account API では機密情報や重要な操作が公開されるため、Auth0 はユーザーアクセスフローで allow_all を使用することを推奨していません。潜在的なセキュリティリスクを最小限に抑え、アプリケーションが本当に必要なものにのみアクセスできるようにするため、My Account API では最小権限の原則に従う必要があります。

Auth0 は、アプリケーション API アクセスポリシーで許可されたスコープ、エンドユーザーに割り当てられたロールベースのアクセス制御 (RBAC) の permissions、およびユーザーの同意 (該当する場合) の積集合によって、アプリケーションに最終的に付与される permissions を決定します。

My Account API へのクライアントアクセス用のアプリケーション API ポリシーは更新できません。つまり、クライアント認証情報フローを使用して My Account API にアクセスすることはできません。

アプリケーション API アクセスポリシーとそれに関連付けられたクライアントグラントの管理方法の詳細については、Application Access to APIs: Client Grants を参照してください。

​

デフォルトポリシー

デフォルトポリシー は、Step-up Authentication を必須にすることで、My Account API に組み込みの認証保証を提供します。有効にすると、Auth0 はユーザーが直近で認証されており、かつ第 2 認証要素を使用していることを自動的に適用します。

このポリシーでは、15 分以内の 2FA が必須になります。Auth0 はこのルールをログイン時と、すべてのリフレッシュトークン交換時に適用します。

• ユーザーに登録済みの MFA 認証要素がある場合、2FA はログイン時に完了している必要があり、トークンの発行から 15 分を超えた場合は再度完了する必要があります。
• ユーザーに登録可能な認証要素がない場合、Auth0 は初回アクセスを許可しますが、15 分経過後のリフレッシュトークン交換では unmet_authentication_requirements エラーを返します。

デフォルトポリシー はクラシックログインと互換性がありません。テナントで Universal Login またはサポート対象の埋め込みフロー (Resource Owner Password Flow または Native パスキー) を使用している場合に、この機能を有効にしてください。

​

デフォルトポリシーを有効にする

My Account API のデフォルトポリシーを有効にするには、次の手順を実行します。

1. アプリケーション > APIs に移動し、My Account API を選択します。
2. 設定 タブを選択します。
3. デフォルトポリシー で、Require 2FA をオンにします。
4. 保存 を選択します。

テナントでデフォルトポリシーが有効になっている場合、Auth0 は新しい My Account API を作成するたびに、そのポリシーを自動的に適用します。

​

認証要件の階層

デフォルトポリシー は、テナントレベルの MFA ポリシーと、Actions で定義する MFA ロジックの中間に位置します。

1. テナント MFA ポリシー: テナント内のすべての認証に適用される基本のデフォルト設定
2. デフォルトポリシー: My Account API に限り、テナントレベルの設定を上書きします
3. Actions: Actions 内の MFA コマンドは、常にこの両方より優先されます

​

デフォルトポリシーの動作

この動作は、ユーザーが登録可能な第2認証要素を持っているかどうかによって異なります。

MFA認証要素を登録済みのユーザー

TOTP、メール、またはその他のサポート対象の認証要素を登録しているユーザーの場合:

1. ログイン時に、Auth0 はトークンを発行する前に、登録済みの認証要素でユーザーにチャレンジを行います。
2. リフレッシュトークンには、認証方法とタイムスタンプ (AMR) が記録されます。
3. 最後のチャレンジから 15 分以内にリフレッシュトークン交換が行われた場合、Auth0 は再度チャレンジすることなく新しいアクセストークンを発行します。
4. 15 分経過後にリフレッシュトークン交換が行われた場合、Auth0 はトークンを発行する前に、再度ユーザーにチャレンジを行います。

MFA認証要素を登録していないユーザー

確認済みのメールアドレスがなく、登録済みの認証要素もないユーザーの場合:

1. ログイン時に、Auth0 は第2認証要素なしでアクセスを許可します。
2. 15 分以内のリフレッシュトークン交換では、Auth0 はチャレンジなしで新しいアクセストークンを発行します。
3. 15 分経過後のリフレッシュトークン交換では、Auth0 は unmet_authentication_requirements エラーを返します。

Auth0 がリフレッシュトークン交換で unmet_authentication_requirements を返した場合、トークンを更新できません。新しいトークンを取得するには、アプリケーションで認証フロー全体を最初からやり直す必要があります。

ユーザーが 15 分経過後にポリシーを満たせない場合、サイレントログイン (prompt=none) は同じエラーを返します。

​

access token を取得する

My Account API のaccess tokenは、独自の API 向けの access token を取得する場合と同じ方法で取得できます。

デフォルトポリシー を超える認証保証が必要な場合 (たとえば、特定の認証要素を必須にしたり、特定の操作にのみ要件を適用したりする場合) は、step-up authentication と Actions を使用して、カスタム MFA ロジックを定義できます。なお、Actions は常に デフォルトポリシー より優先されます。

Universal Login を使用している場合は、以下の記事を参照してください。

• 認可コードフローを使用して API を呼び出す
• PKCE を使用した Authorization Code フローを使用して API を呼び出す

組み込みログインを使用している場合は、以下の記事を参照してください。

• Resource Owner Password Flow を使用して API を呼び出す
• Native Passkeys API を使用したログインフロー

​

Audience

My Account API の audience は https://{yourDomain}/me/ です。

​

スコープ

My Account API では、次のスコープがサポートされています。

スコープ	説明
create:me:authentication_methods	ユーザーが新しい認証方法を登録できるようにします。
read:me:authentication_methods	ユーザーが既存の認証方法を表示できるようにします。
update:me:authentication_methods	ユーザーが既存の認証方法を変更できるようにします。
delete:me:authentication_methods	ユーザーが既存の認証方法を削除できるようにします。
read:me:factors	ユーザーが登録可能な認証要素を表示できるようにします。

Connected Accounts with Token Vault では、My Account API で次のスコープがサポートされています。

スコープ	説明
create:me:connected_accounts	ユーザーが自身のユーザープロファイルに新しいアカウントを接続できるようにします。
read:me:connected_accounts	ユーザーが自身のユーザープロファイルにリンクされた既存の接続済みアカウントを表示できるようにします。
delete:me:connected_accounts	ユーザーが自身のユーザープロファイルから接続済みアカウントを削除できるようにします。

​

アクセストークンの例

​

認可コードフローでのUniversal Login

Auth0’s Universal Login でアクセストークンを取得するには、まず認可コードをリクエストし、次にそのコードをアクセストークンと交換するという2つの手順が必要です。このグラントタイプの詳細については、認可コードフローを参照してください。

まず、/authorize エンドポイントにAPI呼び出しを行って、認可コードをリクエストします。

次に、コードをアクセストークンと交換します：

​

Native パスキーを使用する埋め込みログイン

埋め込みアプリケーションのログインフローにパスキーを組み込むには、まずログインチャレンジをリクエストします。

次に、既存のユーザーを認証します。

​

認証方法を管理する

My Account API を使用すると、認証方法を設定し、エンドユーザーが自分の認証方法を登録・管理できるようにします。ほとんどの認証方法では、登録を開始してから確認する 2 段階のフローを使用します。

サポート対象の認証方法については、次の表を確認してください。

種類	登録時の動作	API 経由で登録可能
email セカンダリ (MFA)	POST { "type": "email" } POST リクエストに email を含めます。Auth0 はそのメールアドレスにワンタイムコードを送信します。検証リクエストで、そのコードを otp_code として送信します。	はい
phone セカンダリ (MFA)	POST { "type": "sms" } Auth0 は電話番号にワンタイムコードを送信します。検証リクエストで、そのコードを otp_code として送信します。	はい
totp セカンダリ (MFA)	POST { "type": "totp" } レスポンスには次の項目が含まれます。 barcode_uri: ユーザーが認証器アプリでスキャンする QR コードとしてレンダリングされます。 manual_input_code: QR コードをスキャンできないユーザー向けの TOTP シークレット。	はい
push-notification セカンダリ (MFA)	POST { "type": "push-notification" } レスポンスには、ユーザーがスキャンして認証器アプリをリンクするための barcode_uri が含まれます。検証リクエストに必要なのは auth_session のみで、otp_code は不要です。ユーザーがアプリでプッシュ通知を承認すると、Auth0 が登録を完了します。	はい
recovery-code セカンダリ (MFA)	POST { "type": "recovery-code" } レスポンスには recovery_code が含まれます。この値は再取得できないため、すぐにユーザーに表示してください。検証リクエストに必要なのは auth_session のみです。	はい
password プライマリ	POST { "type": "password" } レスポンスには、テナントのパスワード要件 (最小文字数、使用可能な文字種、履歴、辞書設定など) を示す policy オブジェクトが含まれます。検証リクエストで、auth_session とともに new_password を送信します。Auth0 は登録を確認する前に、パスワードがポリシーに準拠しているか検証します。	はい
passkey プライマリ	POST { "type": "passkey" }。レスポンスには ID は含まれません。代わりに、次の項目が返されます。 auth_session: POST /authentication-methods から返される、登録用の一意のセッション識別子。 authn_params_public_key: WebAuthn の PublicKeyCredentialCreationOptions を navigator.credentials.create() に渡すために使用します。検証リクエストでは、完全な WebAuthn AuthenticatorAttestationResponse を authn_response として送信します。認証方法の ID は検証レスポンスで返されます。	はい
webauthn-platform セカンダリ (MFA)	現在、登録はサポートされていません。	いいえ — 読み取り専用
webauthn-roaming セカンダリ (MFA)	現在、登録はサポートされていません。	いいえ — 読み取り専用

​

登録フロー

認証方法の登録は、次の 2 段階で行います。

1. 登録を開始するには、メソッドの種類と必要なフィールドを指定して、/me/authentication-methods に POST リクエストを送信します。Auth0 は auth_session トークンと、種類固有の登録情報を返します。
2. 登録を確定するには、auth_session とそのメソッドの種類に対応する検証用認証情報 (OTP コード、新しいパスワード、または WebAuthn レスポンス) を指定して、/me/authentication-methods/{id}/verify に POST リクエストを送信します。

確認が完了すると、Auth0 は以降の GET レスポンスで、メソッドの confirmed フィールドを true に設定します。

パスキーの登録では、POST レスポンスに ID は含まれません。Auth0 が ID を返すのは、検証ステップが正常に完了した後のみです。

​

認証方法の管理例

​

TOTP 認証器を登録する

TOTP の登録は、TOTP 登録の開始と確認の 2 段階で行います。

まず、登録を開始して、ユーザーが認証器アプリに追加するための QR コードと手動入力用シークレットを取得します。

リクエスト

curl --request POST \
  --url 'https://{yourDomain}/me/authentication-methods' \
  --header 'Authorization: Bearer {yourAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{"type": "totp"}'

レスポンス

{
  "id": "amr_abc123",
  "auth_session": "eyJhbGci...",
  "barcode_uri": "otpauth://totp/YourApp:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp",
  "manual_input_code": "JBSWY3DPEHPK3PXP"
}

次に、前のレスポンスの auth_session と id に、ユーザーの認証器アプリで生成されたワンタイムコードを添えて送信し、登録を確認します。

リクエスト

curl --request POST \
  --url 'https://{yourDomain}/me/authentication-methods/{id}/verify' \
  --header 'Authorization: Bearer {yourAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{"auth_session": "{yourAuthSession}", "otp_code": "{yourOtpCode}"}'

レスポンス

{
  "id": "amr_abc123",
  "type": "totp",
  "confirmed": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:35:00.000Z"
}

​

認証方法を一覧表示

現在のユーザーが登録しているすべての認証方法を取得します。confirmed フィールドは、登録が完了しているかどうかを示します。

リクエスト

curl --request GET \
  --url 'https://{yourDomain}/me/authentication-methods' \
  --header 'Authorization: Bearer {yourAccessToken}'

レスポンス

[
  {
    "id": "amr_abc123",
    "type": "totp",
    "confirmed": true,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z"
  },
  {
    "id": "amr_def456",
    "type": "email",
    "email": "[e-mail]",
    "confirmed": true,
    "created_at": "2024-01-10T08:00:00.000Z",
    "updated_at": "2024-01-10T08:05:00.000Z"
  }
]

​

認証方法をDelete

登録済みの認証方法を削除します。{id} は、一覧レスポンスに含まれる対象の認証方法の id に置き換えます。

リクエスト

curl --request DELETE \
  --url 'https://{yourDomain}/me/authentication-methods/{id}' \
  --header 'Authorization: Bearer {yourAccessToken}'

レスポンス

HTTP 204 No Content

​

クロスオリジン リクエスト

Auth0 テナントとは異なるドメインで実行されるブラウザベースのアプリケーション (Single Page Application など) から My Account API を直接呼び出す場合、クロスオリジン リソース共有 (CORS) と呼ばれるブラウザのセキュリティポリシーにより制限を受ける可能性があります。ブラウザはデフォルトで、こうしたクロスオリジン リクエストをブロックします。

アプリケーションから API に正常にリクエストを送信できるようにするには、アプリケーションのドメイン (「origin」) をクライアントの設定に追加する必要があります。

1. Auth0 Dashboard > アプリケーション に移動し、表示するアプリケーションを選択します。
2. Cross-Origin Authentication で、Allow Cross-Origin Authentication をオンにします。
3. Allowed Origins (CORS) を見つけて、アプリケーションの origin URL を入力します。
4. 保存 を選択します。

詳しくは、Configure Cross-Origin Resource Sharing を参照してください。

アプリケーションで CORS を使用する必要がない場合は、Allow Cross-Origin Authentication がオフになっていることを確認してください。アプリケーションの URL をこのリストに追加すると、Auth0 はその origin からのリクエストを信頼し、クライアントサイドのアプリケーションから API へアクセスできるようになります。