> ## 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.

> SPA + API アーキテクチャのシナリオ向けソリューション概要

# ソリューション概要（SPAs + API）

ExampleCo は、Timesheets API へのアクセスを許可されたユーザーおよびアプリケーションのみに限定するため、[OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749) を採用することにしました。このフレームワークには複数のグラントが用意されており、Timesheets API と通信する必要があるさまざまな種類のアプリケーションを簡単に認可できるため、同社が求める柔軟性を備えています。

<div id="api-authentication-and-authorization">
  ## API の認証と認可
</div>

API は、アプリケーションの機能をほかのアプリケーションに公開するための仕組みです。アプリケーションは、API のエンドポイントにメッセージを送ってリクエストを行い、そのレスポンスとして情報を受け取ることができます。

API エンドポイントは、保護されている場合もあれば、されていない場合もあります。今回のケースでは、タイムシートはレビューや支払いに関わる機密情報であるため、許可されたユーザーとアプリケーションだけが API のエンドポイントを呼び出せるようにすることが重要です。クライアントアプリケーションが API の保護されたエンドポイントにアクセスするには、そのエンドポイントの呼び出しに必要な権限を持っていることの証明として、<Tooltip tip="Access Token: API へのアクセスに使用される認可資格情報で、不透明な文字列または JWT の形式を取ります。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=Access+Token">アクセストークン</Tooltip> を提示する必要があります。

アクセストークン は、<Tooltip tip="Authorization Server: ユーザーのアクセス範囲の境界を定義するのに寄与する集中管理サーバーです。たとえば、認可サーバーはユーザーが利用できるデータ、タスク、機能を制御できます。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=Authorization+Server">Authorization Server</Tooltip> でユーザーを認証することで取得され、その後ユーザーは、自分に代わって API にアクセスすることをアプリケーションに許可できます。

<Card title="アクセストークン とは何ですか？">
  アクセストークン (`access_token` とも呼ばれます) は、アプリケーションに発行された認可を表す不透明な文字列です。これは、認可情報を取得するために使われる識別子である場合もあれば、認可情報そのもの (たとえば、ユーザーの ID や権限など) を検証可能な形で内包している場合もあります。

  アクセストークン は、[JSON Web Tokens](/docs/ja-jp/secure/tokens/json-web-tokens) として実装されることがよくあります。

  Auth0 の アクセストークン の詳細については、[アクセストークン](/docs/ja-jp/secure/tokens/access-tokens) を参照してください。
</Card>

API では、公開しているさまざまなエンドポイントに誰がアクセスできるかを、きめ細かく制御できます。これらの権限はスコープとして表されます。

ユーザーがクライアントアプリケーションを認可する際、アプリケーションは必要な権限を示すこともできます。するとユーザーは、それらの権限を確認して付与できます。これらの権限は、その後 アクセストークン に `scope` クレームの一部として含まれます。

その後、クライアントが API へのリクエスト時に アクセストークン を渡すと、API は `scope` クレームを確認して、その特定の API エンドポイントを呼び出すために必要な権限が付与されていることを検証できます。

<Card title="スコープとは何ですか？">
  各 アクセストークン には、クライアントに付与された権限の一覧が含まれる場合があります。クライアントが Auth0 で認証する際には、要求するスコープ (または権限) の一覧を指定します。それらのスコープが認可されると、アクセストークン には認可済みのスコープ一覧が含まれます。

  たとえば、タイムシート API では、4 つの異なる認可レベルを受け付けることがあります。タイムシートの読み取り (スコープ `read:timesheets`) 、タイムシートの作成 (スコープ `create:timesheets`) 、タイムシートの削除 (スコープ `delete:timesheets`) 、タイムシートの承認 (スコープ `approve:timesheets`) です。

  クライアントが API に新しいタイムシート項目の作成を要求する場合、アクセストークン には `create:timesheets` スコープが含まれている必要があります。同様に、既存のタイムシートを削除するには、アクセストークン に `delete:timesheets` スコープが含まれている必要があります。

  スコープの詳細については、[Scopes](/docs/ja-jp/get-started/apis/scopes) を参照してください。
</Card>

<Tooltip tip="OAuth 2.0: 認可プロトコルとワークフローを定義する認可フレームワークです。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> 認可フレームワークを使用すると、自身のアプリケーションやサードパーティアプリケーションに対して、アプリケーション自体のために API への限定的なアクセス権を付与できます。Auth0 を使用すれば、OAuth 2.0/<Tooltip tip="OpenID: アプリケーションがログイン情報を収集・保存することなくユーザーの ID を検証できる認証のオープン標準です。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) 仕様や、API 認可に関するさまざまな技術的側面を気にすることなく、自身の API で異なるフローを簡単にサポートできます。

<Card title="OAuthの役割">
  OAuth 2.0 のあらゆるフローには、次の役割があります。

  * **Resource Owner**: 保護されたリソースへのアクセスを許可できる主体です。通常はエンドユーザーがこれに当たります。
  * **Resource Server**: 保護されたリソースをホストするサーバーです。つまり、アクセスしたい API のことです。
  * **Client**: Resource Owner に代わって、保護されたリソースへのアクセスを要求するアプリケーションです。
  * **Authorization Server**: Resource Owner を認証し、適切な認可を得た後にアクセストークンを発行するサーバーです。ここでは Auth0 の Authentication API を指します。

  [Grant タイプ (またはフロー) ](/docs/ja-jp/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) によって、これらの参加者がどのように連携し、構築中の API への限定的なアクセス権をアプリケーションに付与するかが決まります。その結果、アプリはユーザーに代わって API を呼び出すために使用できるアクセストークンを取得します。
</Card>

<div id="implicit-grant">
  ## Implicit Grant
</div>

OAuth 2.0 では、さまざまなユースケースに対応するために複数の**グラント types**が用意されています。このユースケースでは、[client-side app](/docs/ja-jp/quickstart/spa) から API にアクセスする必要があります。

そのため、SPA は [Implicit Flow (Implicit Grant)](/docs/ja-jp/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) を使用します。

Implicit Grant ([RFC 6749, section 4.1](https://tools.ietf.org/html/rfc6749#section-4.2) で定義) は、[Authorization Code Flow](/docs/ja-jp/get-started/authentication-and-authorization-flow/authorization-code-flow) で使われる グラント と似ていますが、大きな違いは、アプリケーションが `authorization_code` を必要とせず、アクセストークンを直接受け取る点です。これは、通常ブラウザー内で動作する JavaScript アプリであるこのアプリケーションが、サーバー上で動作するウェブアプリよりも信頼性が低く、`client_secret` (Authorization Code グラント で必要) を安全に扱えるとは見なされないためです。

ユーザーが認証されると、アプリケーションは URI のハッシュフラグメントで <Tooltip tip="ID Token: リソースへのアクセスではなく、クライアント自身のための認証情報。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=ID+Token">ID Token</Tooltip> とアクセストークンを受け取ります。これでアプリケーションは、ID Token を使ってユーザー情報を取得し、アクセストークンを使ってユーザーに代わって API を呼び出せるようになります。

1. アプリがフローを開始し、ユーザーが認証できるように、ブラウザーを Auth0 (具体的には [/\authorize endpoint](https://auth0.com/docs/api/authentication#implicit-grant)) にリダイレクトします。
2. Auth0 がユーザーを認証します。ユーザーが初めてこのフローを利用し、かつアプリケーションがサードパーティ製アプリケーションである場合は、クライアントに付与される権限 (たとえば、メッセージの投稿や連絡先の一覧表示など) が記載された同意画面が表示されます。
3. Auth0 は、URI のハッシュフラグメントにアクセストークン (必要に応じて ID Token も) を付けて、ユーザーをアプリにリダイレクトします。これでアプリは、ハッシュフラグメントからトークンを取り出せます。
4. アプリは、アクセストークンを使用してユーザーに代わって API を呼び出せます。

<div id="authorization-extension">
  ## Authorization Extension
</div>

[Auth0 Authorization Extension](/docs/ja-jp/customize/extensions/authorization-extension)を使用すると、ロール、グループ、権限を設定し、それらをユーザーに割り当てることができます。

* 権限とは、ユーザーが実行できる操作のことです。ExampleCoの業務要件では、timesheetに対して read、create、delete、approve の4つの権限を設定します。
* ロールとは、複数の権限をまとめたものです。ExampleCoのtimesheetsアプリは、異なる権限を持つ2種類のユーザー (従業員とマネージャー) が利用するため、employee と manager の2つのロールを設定します。

このユースケースにはこれで十分なため、グループは作成しません。

Authorization Extensionは、ユーザーに割り当てられたロール、グループ、権限を読み取り、その情報を認証フロー中に[User profile](/docs/ja-jp/customize/rules#rule-syntax)へ追加する[Rule](/docs/ja-jp/customize/rules)を作成します。この情報を使うことで、ユーザーに発行されるアクセストークンには、許可されたスコープだけが含まれるようにできます。さらに、ユーザーに必要な権限がない場合は Approve Timesheets 機能を無効にするといった形で、アプリをカスタマイズすることもできます。