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

​
API の認証と認可

API は、アプリケーションの機能をほかのアプリケーションに公開するための仕組みです。アプリケーションは、API のエンドポイントにメッセージを送ってリクエストを行い、そのレスポンスとして情報を受け取ることができます。 API エンドポイントは、保護されている場合もあれば、されていない場合もあります。今回のケースでは、タイムシートはレビューや支払いに関わる機密情報であるため、許可されたユーザーとアプリケーションだけが API のエンドポイントを呼び出せるようにすることが重要です。クライアントアプリケーションが API の保護されたエンドポイントにアクセスするには、そのエンドポイントの呼び出しに必要な権限を持っていることの証明として、 を提示する必要があります。 アクセストークン は、 でユーザーを認証することで取得され、その後ユーザーは、自分に代わって API にアクセスすることをアプリケーションに許可できます。

アクセストークン とは何ですか？

アクセストークン (access_token とも呼ばれます) は、アプリケーションに発行された認可を表す不透明な文字列です。これは、認可情報を取得するために使われる識別子である場合もあれば、認可情報そのもの (たとえば、ユーザーの ID や権限など) を検証可能な形で内包している場合もあります。アクセストークン は、JSON Web Tokens として実装されることがよくあります。Auth0 の アクセストークン の詳細については、アクセストークン を参照してください。
API では、公開しているさまざまなエンドポイントに誰がアクセスできるかを、きめ細かく制御できます。これらの権限はスコープとして表されます。 ユーザーがクライアントアプリケーションを認可する際、アプリケーションは必要な権限を示すこともできます。するとユーザーは、それらの権限を確認して付与できます。これらの権限は、その後 アクセストークン に scope クレームの一部として含まれます。 その後、クライアントが API へのリクエスト時に アクセストークン を渡すと、API は scope クレームを確認して、その特定の API エンドポイントを呼び出すために必要な権限が付与されていることを検証できます。

スコープとは何ですか？

各 アクセストークン には、クライアントに付与された権限の一覧が含まれる場合があります。クライアントが Auth0 で認証する際には、要求するスコープ (または権限) の一覧を指定します。それらのスコープが認可されると、アクセストークン には認可済みのスコープ一覧が含まれます。たとえば、タイムシート API では、4 つの異なる認可レベルを受け付けることがあります。タイムシートの読み取り (スコープ read:timesheets) 、タイムシートの作成 (スコープ create:timesheets) 、タイムシートの削除 (スコープ delete:timesheets) 、タイムシートの承認 (スコープ approve:timesheets) です。クライアントが API に新しいタイムシート項目の作成を要求する場合、アクセストークン には create:timesheets スコープが含まれている必要があります。同様に、既存のタイムシートを削除するには、アクセストークン に delete:timesheets スコープが含まれている必要があります。スコープの詳細については、Scopes を参照してください。
認可フレームワークを使用すると、自身のアプリケーションやサードパーティアプリケーションに対して、アプリケーション自体のために API への限定的なアクセス権を付与できます。Auth0 を使用すれば、OAuth 2.0/ Connect (OIDC) 仕様や、API 認可に関するさまざまな技術的側面を気にすることなく、自身の API で異なるフローを簡単にサポートできます。

OAuthの役割

OAuth 2.0 のあらゆるフローには、次の役割があります。
  • Resource Owner: 保護されたリソースへのアクセスを許可できる主体です。通常はエンドユーザーがこれに当たります。
  • Resource Server: 保護されたリソースをホストするサーバーです。つまり、アクセスしたい API のことです。
  • Client: Resource Owner に代わって、保護されたリソースへのアクセスを要求するアプリケーションです。
  • Authorization Server: Resource Owner を認証し、適切な認可を得た後にアクセストークンを発行するサーバーです。ここでは Auth0 の Authentication API を指します。
Grant タイプ (またはフロー) によって、これらの参加者がどのように連携し、構築中の API への限定的なアクセス権をアプリケーションに付与するかが決まります。その結果、アプリはユーザーに代わって API を呼び出すために使用できるアクセストークンを取得します。

​
Implicit Grant

OAuth 2.0 では、さまざまなユースケースに対応するために複数のグラント typesが用意されています。このユースケースでは、client-side app から API にアクセスする必要があります。 そのため、SPA は Implicit Flow (Implicit Grant) を使用します。 Implicit Grant (RFC 6749, section 4.1 で定義) は、Authorization Code Flow で使われる グラント と似ていますが、大きな違いは、アプリケーションが authorization_code を必要とせず、アクセストークンを直接受け取る点です。これは、通常ブラウザー内で動作する JavaScript アプリであるこのアプリケーションが、サーバー上で動作するウェブアプリよりも信頼性が低く、client_secret (Authorization Code グラント で必要) を安全に扱えるとは見なされないためです。 ユーザーが認証されると、アプリケーションは URI のハッシュフラグメントで とアクセストークンを受け取ります。これでアプリケーションは、ID Token を使ってユーザー情報を取得し、アクセストークンを使ってユーザーに代わって API を呼び出せるようになります。
  1. アプリがフローを開始し、ユーザーが認証できるように、ブラウザーを Auth0 (具体的には /\authorize endpoint) にリダイレクトします。
  2. Auth0 がユーザーを認証します。ユーザーが初めてこのフローを利用し、かつアプリケーションがサードパーティ製アプリケーションである場合は、クライアントに付与される権限 (たとえば、メッセージの投稿や連絡先の一覧表示など) が記載された同意画面が表示されます。
  3. Auth0 は、URI のハッシュフラグメントにアクセストークン (必要に応じて ID Token も) を付けて、ユーザーをアプリにリダイレクトします。これでアプリは、ハッシュフラグメントからトークンを取り出せます。
  4. アプリは、アクセストークンを使用してユーザーに代わって API を呼び出せます。

​
Authorization Extension

Auth0 Authorization Extensionを使用すると、ロール、グループ、権限を設定し、それらをユーザーに割り当てることができます。
  • 権限とは、ユーザーが実行できる操作のことです。ExampleCoの業務要件では、timesheetに対して read、create、delete、approve の4つの権限を設定します。
  • ロールとは、複数の権限をまとめたものです。ExampleCoのtimesheetsアプリは、異なる権限を持つ2種類のユーザー (従業員とマネージャー) が利用するため、employee と manager の2つのロールを設定します。
このユースケースにはこれで十分なため、グループは作成しません。 Authorization Extensionは、ユーザーに割り当てられたロール、グループ、権限を読み取り、その情報を認証フロー中にUser profileへ追加するRuleを作成します。この情報を使うことで、ユーザーに発行されるアクセストークンには、許可されたスコープだけが含まれるようにできます。さらに、ユーザーに必要な権限がない場合は Approve Timesheets 機能を無効にするといった形で、アプリをカスタマイズすることもできます。