> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ユニバーサルポータルのアーキテクチャ

> ユニバーサルポータルでユーザーをサインインさせる方法、リソースサーバー向けのアクセストークンを取得する方法、ステップアップ認証やFormを処理する方法、セッションを管理する方法について説明します。

> [!WARNING]
>
> **Auth0 Universal Portals機能は現在、です。**

Portalは、Auth0がホストするサーバー側のアプリケーションです。Portalサーバーはユーザーのサインインを処理し、ユーザーのトークンを保持して、ユーザーに代わってリソースサーバーを呼び出します。アクセストークンやリフレッシュトークンがブラウザーに渡ることはなく、ブラウザーが保持するのは安全なセッションクッキーのみです。

以下のセクションでは、Portalに関わるアクター、ユーザーのサインイン方法、コンポーネントによるリソースサーバーの呼び出し方法、およびステップアップ認証、Form、セッションの仕組みについて説明します。

最初のPortalを作成するには、[Universal Portalsクイックスタート](https://auth0.com/docs/ja-jp/customize/portals/quickstart.md)を参照してください。アプリケーションからPortalを開くには、[Portalにアクセスする](https://auth0.com/docs/ja-jp/customize/portals/access-portals.md)を参照してください。Portalアプリケーションを構成するには、[Universal Portals用にアプリケーションを構成する](https://auth0.com/docs/ja-jp/customize/portals/configure-portal-application.md)を参照してください。

## アクター

* **ブラウザー**：Portalとコンポーネントを表示します。
* **Portalサーバー**：ユーザーのサインインを処理してトークンを保存し、コンポーネントからの呼び出しをリソースサーバーへプロキシします。
* **Auth0**：ユーザーのサインインを処理し、トークンを発行する認可サーバーです。
* **[My Account API](https://auth0.com/docs/ja-jp/manage-users/my-account-api.md)と[My Organization API](https://auth0.com/docs/ja-jp/manage-users/my-organization-api.md)**：コンポーネントの呼び出し先となるリソースサーバーです。
* **Formsバックエンド**：[Auth0 Forms](https://auth0.com/docs/ja-jp/customize/forms.md)とそのフローを実行します。

```mermaid theme={null}
flowchart LR
    browser["ブラウザー"] -- "Session cookie" --> portal["ポータルサーバー"]
    portal -- "Sign-in, token requests" --> auth0["Auth0"]
    portal -- "Access token per call" --> apis["My Account API<br/>My Organization API"]
    browser -- "Form submissions" --> forms["Formのバックエンド"]
```

## シングルサインオンでのアクセス

ユーザーがポータルのURLを開くと、ポータルサーバーは[Proof Key for Code Exchange (PKCE) ](https://auth0.com/docs/ja-jp/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce.md)を使った認可コードフローを開始します。ユーザーがすでにAuth0のセッションを持っている場合、Auth0はログインプロンプトを表示せずに認可コードを返します。ポータルサーバーはこのコードをIDトークン、アクセストークン、リフレッシュトークンと交換して保存し、続いてセッションクッキーを設定します。

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant P as Portal server
    participant A as Auth0

    B->>P: Open portal URL
    P-->>B: Redirect to /authorize
    B->>A: GET /authorize
    Note over A: User has an Auth0 session
    A-->>B: Redirect to /portals/auth/callback with code
    B->>P: GET /portals/auth/callback
    P->>A: Exchange code for tokens
    A-->>P: ID token, access token, refresh token
    Note over P: Tokens stay on the server
    P-->>B: Session cookie and portal page
```

ユーザーにAuth0のセッションがない場合、Auth0はコードを返す前にログインページを表示します。

## セッション転送トークンを使用したアクセス

[ネイティブアプリケーション](https://auth0.com/docs/ja-jp/get-started/auth0-overview/create-applications/native-apps.md)は、ポータルのURLにセッション転送トークンを含めて渡すことができます。ポータルサーバーはこのトークンを`/authorize`に転送します。Auth0はトークンを検証すると、シングルサインオン (シングルサインオン（SSO）：ユーザーが1つのアプリケーションにログインすると、他のアプリケーションにも自動的にログインさせるサービスです。シングルログアウトはこれと逆の流れで同様に機能します。)と同様に、プロンプトを表示せずにユーザーをサインインさせ、コードを返します。セッション転送トークンは1回限り有効で、60秒で期限切れになります。Auth0がトークンを拒否した場合は、ユーザーにログインページが表示されます。

```mermaid theme={null}
sequenceDiagram
    participant N as Native application
    participant B as In-app browser
    participant P as Portal server
    participant A as Auth0

    N->>A: Exchange refresh token for session transfer token
    A-->>N: Session transfer token
    N->>B: Open portal URL with the token
    B->>P: GET portal URL
    P-->>B: Redirect to /authorize with the token
    B->>A: GET /authorize
    A-->>B: Redirect to callback with code
    B->>P: GET callback
    P->>A: Exchange code for tokens
    P-->>B: Session cookie and portal page
```

このシナリオを実装するには、[ネイティブアプリケーションからPortalを開く](https://auth0.com/docs/ja-jp/customize/portals/access-portals.md#open-a-portal-from-a-native-application)を参照してください。

## コンポーネントからリソースサーバーへの呼び出し

コンポーネントがブラウザーからリソースサーバーを直接呼び出すことはありません。代わりに、必要なオーディエンスとスコープを指定して、ポータルサーバーの `/portals/{slug}/proxy/...` にリクエストを送信します。ポータルサーバーはアクセストークンを付与したうえで、リクエストを API に転送します。

### アクセストークンの発行

ポータルでは常にリフレッシュトークン (リフレッシュトークン：新しいアクセストークンの取得に使用できる特殊なトークンです。ユーザーに再ログインを求めることなく、期限切れが近いアクセストークンを更新するのに役立ちます。)が必要です。ポータルサーバーは、コンポーネントが呼び出す各リソースサーバー向けのアクセストークンを発行する主な仕組みとして、このリフレッシュトークンを使用します。オーディエンス間の切り替えにはMulti-Resource Refresh Token (MRRT) を利用するため、ユーザーは1回サインインするだけで済みます。ポータルはアクセストークンを有効期限が切れるまで再利用し、期限が切れると新しいトークンを発行します。

ポータルアプリケーションには、リソースサーバーごとに2つの設定が必要です。スコープを許可するクライアントへの認可と、トークン交換を許可するリフレッシュトークンポリシーです。詳細については、「[Multi-Resource Refresh Token](https://auth0.com/docs/ja-jp/secure/tokens/refresh-tokens/multi-resource-refresh-token.md)」をお読みください。

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant P as Portal server
    participant A as Auth0
    participant R as Resource server

    B->>P: Request to /portals/{slug}/proxy/...
    alt The portal has a valid access token for the audience and scope
        Note over P: Reuse the access token
    else No valid access token
        P->>A: Refresh token grant for the audience and scope
        A-->>P: Access token
    end
    P->>R: Request with the access token
    R-->>P: Response
    P-->>B: Response
```

### 許可されるリソースサーバー

コンポーネントからの呼び出し先は、テナントの My Account API と My Organization API に限られます。さらに、そのうちポータルアプリケーションがクライアントへの認可を持つ API のみが対象となります。推奨される設定では、両方の API に認可を付与します。それ以外のオーディエンスに対するリクエストは、ポータルサーバーによって `403` で拒否されます。

### レート制限

[多要素認証 (MFA) ](https://auth0.com/docs/ja-jp/secure/multi-factor-authentication.md)またはパスキーのコンポーネントがデータを読み込む際にMy Account APIから`429 Too Many Requests`が返された場合、Portalはそのコンポーネントの代わりに「Too many requests」というメッセージと再試行ボタンを表示します。

## ステップアップ認証

オペレーションに MFA が必要かどうかは、テナントのポリシーとアクションによって決まります。たとえば、テナントに次の post-login アクションが設定されているとします。このアクションは、リフレッシュトークン交換で、認証方法を削除するスコープを含む My Account API へのアクセスが要求された場合に、MFA チャレンジを求めます。ドメインはリクエストのホスト名から取得されるため、このアクションは Auth0 ドメインとカスタムドメインのどちらでも動作します。

```javascript wrap lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
    const { protocol } = event.transaction ?? {};
    const { hostname, body } = event.request ?? {};

    const isRefreshTokenExchange = protocol === "oauth2-refresh-token";
    const isMyAccountApi = body?.audience === `https://${hostname}/me/`;
    const deletesAuthenticator = body?.scope?.includes("delete:me:authentication_methods");

    if (isRefreshTokenExchange && isMyAccountApi && deletesAuthenticator) {
        api.authentication.challengeWithAny([{ type: "email" }, { type: "otp" }]);
    }
};
```

Portal がそのオーディエンスとスコープのアクセストークンをリクエストすると、Auth0 はアクションを実行してユーザーに認証要素の選択を求め、`mfa_required` を返します。Portal はポップアップで MFA チャレンジを開始し、ユーザーがチャレンジを完了すると元のリクエストを再試行します。詳しくは、「[Action Triggers: post-login - API object](https://auth0.com/docs/ja-jp/actions/reference/post-login/post-login-api-object.md)」をお読みください。

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant P as Portal server
    participant A as Auth0
    participant R as My Account API

    B->>P: Delete an authenticator
    P->>A: Request an access token with the delete scope
    A-->>P: mfa_required
    P-->>B: Start the MFA challenge
    B->>A: Complete the MFA challenge
    A-->>P: Access token with the delete scope
    P->>R: Retry the request with the access token
    R-->>P: Response
    P-->>B: Response
```

## Formsの送信

[Auth0 Form](https://auth0.com/docs/ja-jp/customize/forms.md)はポータルページ内に表示されますが、そのリクエストはポータルサーバーを経由せず、ブラウザーからFormsのバックエンドへ直接送信されます。フローを実行するのはFormsのバックエンドです。フローがAPIを呼び出す際は、Forms vault接続の認証情報が使用されます。このAPIはリソースサーバーで、通常はManagement APIですが、任意のAPIを指定することもできます。

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant F as Forms backend
    participant R as Resource server

    B->>F: Submit the Form
    F->>F: Run the Flow
    F->>F: Read credentials from the vault
    F->>R: Call the API with the credentials
    R-->>F: Response
    F-->>B: Form response and completion message
```

Formは、Portalの読み込み時にユーザーのIDトークンからコンテキストを受け取ります。詳しくは、「[Formsコンテキスト変数](https://auth0.com/docs/ja-jp/customize/portals/portal-components.md#forms-context-variables)」を参照してください。

## セッションとトークンの有効期間

Portal には 2 つのセッションと 2 種類のトークンがあります。

* Auth0 セッション：ユーザーがサインインすると Auth0 によって設定されます。テナントのセッション設定で制御されます。
* Portal セッション：Portal のセッションクッキーです。無操作状態が 1 時間続くか、サインインから 1 日が経過するかのいずれか早い時点で終了します。
* リフレッシュトークン：Portal サーバーがアクセストークンを発行するための認証情報です。すべての API 呼び出しがこれに依存するため、有効期間は Portal セッションに合わせて設定してください。
* アクセストークン：コンポーネントが必要とする時点で発行され、有効期限が切れるまで再利用されます。有効期間は、セキュリティポリシーに従ってリソースサーバーで設定してください。

Portal セッションが終了すると、Portal はユーザーを Auth0 にリダイレクトし、再度サインインを求めます。

```mermaid theme={null}
flowchart LR
    ended["ポータルのセッションが終了"] --> check{"Auth0のセッションは<br/>まだ有効ですか？"}
    check -- "Yes" --> silent["プロンプトは表示されず<br/>ユーザーはそのまま続行する"]
    check -- "No" --> login["ユーザーに<br/>ログインページが表示される"]
```

リフレッシュトークンの有効期限がポータルのセッションより先に切れると、ユーザーが再度サインインするまでAPI呼び出しは失敗します。これを防ぐには、[Universal Portals用にアプリケーションを設定する](https://auth0.com/docs/ja-jp/customize/portals/configure-portal-application.md#recommended-configuration)に記載されている有効期間を設定してください。

## 次のステップ

> [card] [Universal Portalsのクイックスタート](https://auth0.com/docs/ja-jp/customize/portals/quickstart.md)
>
> 数分で最初のPortalを作成できます。

> [card] [Universal Portals用にアプリケーションを構成する](https://auth0.com/docs/ja-jp/customize/portals/configure-portal-application.md)
>
> アクセストークンの発行に必要なクライアントグラントとリフレッシュトークンのポリシーを設定します。

> [card] [Portalsにアクセスする](https://auth0.com/docs/ja-jp/customize/portals/access-portals.md)
>
> アプリケーションからユーザーをPortalへ誘導します。

> [card] [Universal Portalsのトラブルシューティング](https://auth0.com/docs/ja-jp/customize/portals/troubleshoot-portals.md)
>
> サインイン、セッション、APIに関するエラーを解決します。