OAuth 2.0 の仕様を読むために

OAuth 2.0に関しては、いろんな解説や実装がありますが、結局、http://tools.ietf.org/html/rfc6749 にあるRFCの仕様を読むのが一番なのではないかと思い、それを読む際に必要な部分、詰まりやすい部分をまとめてみました。

OAuth 2.0 の公式サイト (http://oauth.net/2/) もRFCは1行で軽くリンクがあるだけで、どうせ皆各言語で実装したライブラリが知りたいんでしょみたいな構成になっていますが、自社もAPIを公開しようとか、マイクロサービスアーキテクチャをしっかり構築しようなどという時に、Resource Server側になることも最近はすごい珍しい訳でも無いのかなと思います。

意外とちゃんと訳しておいたほうが良い英単語

例えば、Authorization=認証みたいに思っていると意味を誤解しやすいので、きちんと日本語訳の対応付けをしておいたほうがいい英単語はまとめておきました。

英語	日本語訳
Authorization	権限付与、権限
Grant	許可証、承認
Credential	権威の証明証、資格

特にAuthorizationは第1義が「権限付与=権限を与える行為」なことに注意しましょう。

1. the act of authorizing
2. permission or power granted by an authority; sanction.

http://www.dictionary.com/browse/authorization

これに対し、Grantは、名詞としての第1義が「許可証=承認されたもの」で、第2義が「承認=承認する行為」となっています。

1. something granted, as a privilege or right, a sum of money, or a tract of land
2. the act of granting.

http://www.dictionary.com/browse/grant

4つの役割

Section 1.1 Rolesの内容

名前	役割	例
Resource Owner	リソースへのアクセス権限を与えられる人またはエンティティ	ユーザー
Resource Server	Access Tokenを使ったリソースへのリクエストに応えられるサーバー	FacebookのAPIサーバー
Client	権限に基づき、Resource Ownerの代理としてリソースを要求するアプリケーション（Webアプリでも、PC/モバイルアプリでも）	ユーザーが使っているアプリやサービス
Authorization Server	Resource Ownerが認可し権限付与した後、Clientに対し、Access Tokenを発行するサーバー	Facebookの認証サーバー

認証フロー大枠 - 4つの役割の関係性

Section 1.2 Protocol Flowの内容。

OAuth2における流れの大枠は以下のようになる。

Abstract_Protocol_Flow

     +--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+

                     Figure 1: Abstract Protocol Flow

• A: Clientは、Resource Ownerにリクエストを送る。

• リクエストは直接行われるか、Authorization Serverを介して行われる

• B: Clientは、Authorization GrantというResource Ownerからの証明証を得る。

• Clientの種類により、4種類の承認フローのどれにするかを使い分ける必要がある
• 4つ以外にも、新しい承認フローを仕様に則って作成する事もできる

• C: Clientは、Authorization Serverに、Authorization Grantを見せることで、Access Tokenを要求する。
• D: Authorization Serverは、ClientとAuthorization Grantが正しいことを確認し、正しい場合、Access Tokenを返す。
• E: Clientは、Resource Serverに、Access Tokenとともにリソースを要求する。
• F: Resource Serverは、Access Tokenを検証し、正しかった場合、リクエストの結果を返す。

4つの承認フロー

Section 1.3 Authorization Grant と Section 4 Obtaining Authorizationの内容

名前	どんな時に使うか
Authorization Code Grant	RailsなどバックエンドのサーバーサイドでOAuthする時
Implicit Grant	JavascriptなどWebブラウザのクライアントサイドでOAuthする時
Resource Owner Password Credentials Grant	PCやモバイルアプリなどで、他の方法が使えない環境でOAuthする時
Client Credentials Grant	社内のAPIサーバー等信頼できるクライアントからOAuthする時

Authorization Code Grant

Authorization_Code_Flow

     +----------+
     | Resource |
     |   Owner  |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |          & Redirection URI                  |
     |         |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)

   Note: The lines illustrating steps (A), (B), and (C) are broken into
   two parts as they pass through the user-agent.

                     Figure 3: Authorization Code Flow


 The flow illustrated in Figure 3 includes the following steps:

   (A)  The client initiates the flow by directing the resource owner's
        user-agent to the authorization endpoint.  The client includes
        its client identifier, requested scope, local state, and a
        redirection URI to which the authorization server will send the
        user-agent back once access is granted (or denied).

   (B)  The authorization server authenticates the resource owner (via
        the user-agent) and establishes whether the resource owner
        grants or denies the client's access request.

   (C)  Assuming the resource owner grants access, the authorization
        server redirects the user-agent back to the client using the
        redirection URI provided earlier (in the request or during
        client registration).  The redirection URI includes an
        authorization code and any local state provided by the client
        earlier.

   (D)  The client requests an access token from the authorization
        server's token endpoint by including the authorization code
        received in the previous step.  When making the request, the
        client authenticates with the authorization server.  The client
        includes the redirection URI used to obtain the authorization
        code for verification.

   (E)  The authorization server authenticates the client, validates the
        authorization code, and ensures that the redirection URI
        received matches the URI used to redirect the client in
        step (C).  If valid, the authorization server responds back with
        an access token and, optionally, a refresh token.

Implecit Grant

Implicit_Grant_Flow

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |  User-   |                                | Authorization |
     |  Agent  -|----(B)-- User authenticates -->|     Server    |
     |          |                                |               |
     |          |<---(C)--- Redirection URI ----<|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |     Client    |
     |          |                                |    Resource   |
     |     (F)  |<---(E)------- Script ---------<|               |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Client |
     |         |
     +---------+

   Note: The lines illustrating steps (A) and (B) are broken into two
   parts as they pass through the user-agent.

                       Figure 4: Implicit Grant Flow


   The flow illustrated in Figure 4 includes the following steps:

   (A)  The client initiates the flow by directing the resource owner's
        user-agent to the authorization endpoint.  The client includes
        its client identifier, requested scope, local state, and a
        redirection URI to which the authorization server will send the
        user-agent back once access is granted (or denied).

   (B)  The authorization server authenticates the resource owner (via
        the user-agent) and establishes whether the resource owner
        grants or denies the client's access request.

   (C)  Assuming the resource owner grants access, the authorization
        server redirects the user-agent back to the client using the
        redirection URI provided earlier.  The redirection URI includes
        the access token in the URI fragment.

   (D)  The user-agent follows the redirection instructions by making a
        request to the web-hosted client resource (which does not
        include the fragment per [RFC2616]).  The user-agent retains the
        fragment information locally.

   (E)  The web-hosted client resource returns a web page (typically an
        HTML document with an embedded script) capable of accessing the
        full redirection URI including the fragment retained by the
        user-agent, and extracting the access token (and other
        parameters) contained in the fragment.

   (F)  The user-agent executes the script provided by the web-hosted
        client resource locally, which extracts the access token.

   (G)  The user-agent passes the access token to the client.

Resource Owner Password Credentials Grant

Resource_Owner_Password_Credentials_Flow

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          v
          |    Resource Owner
         (A) Password Credentials
          |
          v
     +---------+                                  +---------------+
     |         |>--(B)---- Resource Owner ------->|               |
     |         |         Password Credentials     | Authorization |
     | Client  |                                  |     Server    |
     |         |<--(C)---- Access Token ---------<|               |
     |         |    (w/ Optional Refresh Token)   |               |
     +---------+                                  +---------------+

            Figure 5: Resource Owner Password Credentials Flow


   The flow illustrated in Figure 5 includes the following steps:

   (A)  The resource owner provides the client with its username and
        password.

   (B)  The client requests an access token from the authorization
        server's token endpoint by including the credentials received
        from the resource owner.  When making the request, the client
        authenticates with the authorization server.

   (C)  The authorization server authenticates the client and validates
        the resource owner credentials, and if valid, issues an access
        token.

Client Credentials Grant

Client_Credentials_Flow

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

                     Figure 6: Client Credentials Flow


   The flow illustrated in Figure 6 includes the following steps:

   (A)  The client authenticates with the authorization server and
        requests an access token from the token endpoint.

   (B)  The authorization server authenticates the client, and if valid,
        issues an access token.

Refresh Token

Refreshing_an_Expired_Access_Token

  +--------+                                           +---------------+
  |        |--(A)------- Authorization Grant --------->|               |
  |        |                                           |               |
  |        |<-(B)----------- Access Token -------------|               |
  |        |               & Refresh Token             |               |
  |        |                                           |               |
  |        |                            +----------+   |               |
  |        |--(C)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(D)- Protected Resource --| Resource |   | Authorization |
  | Client |                            |  Server  |   |     Server    |
  |        |--(E)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(F)- Invalid Token Error -|          |   |               |
  |        |                            +----------+   |               |
  |        |                                           |               |
  |        |--(G)----------- Refresh Token ----------->|               |
  |        |                                           |               |
  |        |<-(H)----------- Access Token -------------|               |
  +--------+           & Optional Refresh Token        +---------------+

               Figure 2: Refreshing an Expired Access Token