OAuth 2.0認可フレームワーク

Auth0によるOAuth 2.0認可フレームワークの実装について、サポートされているグラントタイプやAPIとアプリケーションを保護するための主要なエンドポイントを含めて学びます。

Overview

主要概念

• Auth0は、Internet Engineering Task Force (IETF) が策定したOAuth 2.0プロトコルをサポートしています。
• OAuth 2.0仕様の役割、グラントタイプ (またはワークフロー) 、エンドポイントについて説明します。

OAuth 2.0認可フレームワークは、ユーザーが長期的な資格情報やアイデンティティを明かすことなく、サードパーティのウェブサイトやアプリケーションに保護されたリソースへのアクセスを許可できるプロトコルです。

OAuth

は認可レイヤーを導入し、クライアントの役割を

リソース所有者

の役割から切り離します。OAuthでは、クライアントはリソース所有者が管理し

リソースサーバー

がホストするリソースへのアクセスを要求し、リソース所有者とは異なる資格情報が発行されます。保護されたリソースへのアクセスにリソース所有者の資格情報を使用する代わりに、クライアントは

アクセストークン

(特定のスコープ、有効期間、その他のアクセス属性を示す文字列) を取得します。アクセストークンは、リソース所有者の承認のもと、

認可サーバー

によってサードパーティのクライアントに発行されます。その後、クライアントはそのアクセストークンを使用して、リソースサーバーがホストする保護されたリソースにアクセスします。

Auth0は、APIの認可シナリオ向けにJSON Web Token (JWT) 形式でアクセストークンを生成します。アクセストークンが表すpermissionsは、OAuthの用語ではスコープと呼ばれます。アプリケーションがAuth0で認証する際に必要なスコープを指定し、ユーザーによってそれらのスコープが認可されると、アクセストークンはその認可済みスコープを表します。

​

役割

OAuth 2.0のフローには、次の役割があります。

• リソース所有者: 保護されたリソースへのアクセスを許可できる主体です。通常はエンドユーザーを指します。
• リソースサーバー: 保護されたリソースをホストするサーバーです。つまり、アクセスしたいAPIのことです。
• クライアント: リソース所有者に代わって、保護されたリソースへのアクセスを要求するアプリケーションです。
• 認可サーバー: リソース所有者を認証し、適切な認可を得たうえでアクセストークンを発行するサーバーです。この場合はAuth0です。

​

グラントタイプ

OAuth 2.0 では、アクセストークン を取得するための 4 つのフローが定義されています。これらのフローは、グラントタイプと呼ばれます。どのフローがユースケースに適しているかを判断する際には、主にアプリケーションの種類を考慮します。

• Authorization Code Flow: サーバー上で動作する Web アプリで使用されます。モバイルアプリでも、Proof Key for Code Exchange (PKCE) technique を使用して利用されます。
• Implicit Flow with Form Post: ユーザーのブラウザー上で動作する、JavaScript を中心としたアプリ (Single-Page Applications) で使用されます。
• Resource Owner Password Flow: 高い信頼性を前提とするアプリで使用されます。
• Client Credentials Flow: マシン間通信に使用されます。

この仕様では、追加のグラントタイプを定義するための拡張メカニズムも提供されています。各グラントタイプの仕組みや使用すべき場面について詳しくは、Authentication and Authorization Flows を参照してください。

​

エンドポイント

OAuth 2.0 では、/authorize エンドポイントと /oauth/token エンドポイントの 2 つのエンドポイントを使用します。

​

認可エンドポイント

/authorize エンドポイントは、リソース所有者とやり取りして、保護されたリソースにアクセスするための認可を取得するために使用されます。これを理解しやすくするために、Google アカウントを使ってサービスにログインする場面を想像してみてください。まず、サービスは認証のために Google にリダイレクトします (まだログインしていない場合) 。その後、同意画面が表示され、そのサービスに対して、メールアドレスや連絡先リストなど、あなたのデータ (保護されたリソース) の一部へのアクセスを許可するよう求められます。

/authorize エンドポイントのリクエストパラメータは次のとおりです。

Parameter	Description
response_type	認可サーバーに、どの grant を実行するかを伝えます。
response_mode	(任意) 認可リクエストの結果をどの形式で返すかを指定します。値: - query: Authorization Code grant 用。302 Found によってリダイレクトされます。 - fragment: Implicit grant 用。302 Found によってリダイレクトされます。 - form_post: レスポンスパラメータを hidden パラメータとして HTML form に埋め込んだ 200 OK。 - web_message: Silent Authentication 用。HTML5 web messaging を使用します。
client_id	認可を要求するアプリケーションの ID です。
redirect_uri	URL を指定します。このエンドポイントから正常なレスポンスが返されると、この URL にリダイレクトされます。
scope	アプリケーションが必要とする permissions をスペース区切りで並べた一覧です。
state	セキュリティ目的で使用される不透明な値です。このリクエストパラメータが設定されている場合、redirect_uri の一部としてアプリケーションに返されます。
connection	Passwordless connections の接続タイプを指定します

アプリケーションがユーザーを認証するために /authorize エンドポイントへ最初のリクエストを送る際に、カスタムクエリパラメータを設定できます。カスタムクエリパラメータを使用すると、Universal Login のページテンプレートに追加のコンテキストを渡せます。

connection パラメータを使用するには、ID First を有効にする必要があります。connection パラメータと Universal Login の詳細については、Passwordless for Universal Login を参照してください。

ext- で始まるクエリパラメータは、自動的に page template context に表示されます。

このエンドポイントは、Authorization Code グラントタイプ と Implicit グラントタイプ で使用されます。認可サーバーは、アプリケーションがどの グラントタイプ を使いたいかを把握する必要があります。これは、発行する credential の種類に影響するためです。

• Authorization Code grant の場合は、認可コードを発行します (これは後で /oauth/token エンドポイントでアクセストークンと交換できます) 。
• Implicit grant の場合は、アクセストークンを発行します。これは、誰がどのアプリケーションに対してどの permissions (scopes) を認可したかを示す不透明な文字列 (または Auth0 の実装では JWT) です。

どの グラントタイプ を使用するかを認可サーバーに伝えるために、response_type リクエストパラメータを次のように使用します。

• Authorization Code grant の場合は、認可コードを含めるために response_type=code を使用します。
• Implicit grant の場合は、アクセストークンを含めるために response_type=token を使用します。代わりに response_type=id_token token を使用して、アクセストークンと ID token の両方を含めることもできます。

ID token は、ログインしているユーザーに関する情報を含む JWT です。これは OpenID Connect (OIDC) で導入されました。

OAuth 2.0 Multiple Response Type Encoding Practices specification では、認可リクエストの結果をどのような形式で返すかを指定するパラメータが追加されました。このパラメータは response_mode と呼ばれます。これは任意で、次の値を取ることができます:

Value	Description
query	これは Authorization Code grant のデフォルトです。成功したレスポンスは 302 Found で、redirect_uri へのリダイレクトが発生します。レスポンスパラメーターは、Location ヘッダー内の redirect_uri の query コンポーネント (? の後の部分) に埋め込まれます。 例: HTTP/1.1 302 Found Location: https://my-redirect-uri.callback?code=js89p2x1 この場合、authorization code は js89p21 です。
fragment	これは Implicit Grant のデフォルトです。成功したレスポンスは 302 Found で、redirect_uri (リクエストパラメーター) へのリダイレクトが発生します。レスポンスパラメーターは、Location ヘッダー内の redirect_uri の fragment コンポーネント (# の後の部分) に埋め込まれます。 例: HTTP/1.1 302 Found Location: https://my-redirect-uri/callback#access_token=eyB...78f&token_type=Bearer&expires_in=3600.
form_post	この response mode は OAuth 2.0 Form Post Response Mode specification で定義されています。成功したレスポンスは 200 OK で、パラメーターは hidden params として HTML form に埋め込まれます。form の action は redirect_uri で、onload 属性は form を送信するように設定されます。HTML がブラウザーに読み込まれた後、redirect_uri へのリダイレクトが行われます。
web_message	この response mode は OAuth 2.0 Web Message Response Mode specification で定義されています。/authorization endpoint からの authorization response では、リダイレクトの代わりに HTML5 Web Messaging を使用します。これは Silent Authentication を使用する場合に特に便利です。この response mode を使用するには、Auth0 の アプリケーション設定 にある Allowed Web Origins フィールドにアプリの URL を登録する必要があります。

​

トークンエンドポイント

/oauth/token エンドポイントは、アプリケーションがアクセストークンまたは リフレッシュトークン を取得するために使用されます。アクセストークンは直接発行されるため、Implicit Flow を除くすべてのフローで使用されます。

• Authorization Code Flow では、アプリケーションは認可エンドポイントから取得した認可コードをアクセストークンと交換します。
• Client Credentials Flow および Resource Owner Password Credentials Grant Exchange では、アプリケーションは一連の認証情報を使って認証を行い、その後アクセストークンを取得します。

​

State parameters

認可プロトコルでは、アプリケーションの前の状態を復元できるようにする state パラメーターが用意されています。state パラメーターは、クライアントが 認可リクエスト で設定した状態オブジェクトの一部を保持し、それをレスポンスでクライアントが利用できるようにします。state パラメーターを使用する主な目的は、CSRF 攻撃を軽減することです。詳細については、Use OAuth 2.0 State Parameters を参照してください。

​

詳細はこちら

• OAuth 2.0のState parametersを使って攻撃を防ぎ、ユーザーをリダイレクトする
• どのOAuth 2.0フローを使うべきですか？