クライアントを作って理解するOAuth2(実装編)

はじめに

クライアントを作って理解するOAuth2(準備編) - oinume journalの続編。前の記事ではGoogle APIsのプロジェクトを作成してOAuth2 clientを登録した。この記事では発行されたClient idを使って実際にAccess tokenを取得する部分をGoで実装してみたいと思う。

ソースコードは GitHub - oinume/go-oauth2-client-sample: OAuth2 client sample in Go にあり、OAuthの実装はserver.goにまとまっている。main関数はcmd/oauth2-client-sample/main.goにあるが、これはサーバーの起動処理があるだけの薄いものである。サーバーの起動方法などについてはGitHubのREADMEを見てほしい。

前提

OAuth2のGrant typeはAuthorization code grantを使用する
Webブラウザを使用する

Webブラウザを使うことに関しては特に疑問はないと思うが、Authorization code grantって何？というのを説明しておく。

これはEnd userから認可を得て、Access tokenを取得するための手法の一つ。Authorization codeというトークンをAuthorization server(今回だとGoogleの認可サーバー)から取得して、そのAuthorization codeとAccess tokenを交換する。なお、Authorization code grantを使用すると、Access token以外にもRefresh tokenも取得ができる。このgrant typeはConfidential clientから実行されることを想定している。Confidential clientについては次に説明する。

Public clientとConfidential client

OAuth2.0の仕様にその定義が書いてあるが以下のようになっている。(RFCの日本語訳より抜粋)

コンフィデンシャル (confidential): クレデンシャルの機密性を維持することができるクライアント (例えば, クライアントクレデンシャルへのアクセスが制限されたセキュアサーバー上に実装されたクライアント), または他の手段を使用したセキュアなクライアント認証ができるクライアント.
パブリック (public): (例えば, インストールされたネイティブアプリケーションやブラウザベースのWebアプリケーションなど, リソースオーナーのデバイス上で実行されるクライアントのように) クライアントクレデンシャルの機密性を維持することができず, かつ他の手段を使用したセキュアなクライアント認証もできないクライアント.

今回はGoで実装されたサーバーからGoogleのAuthorization serverに対して通信するため、コンフィデンシャルクライアントになる。

Access tokenを取得するまでの流れ

End userがSign in with Googleボタンをクリックし、Clientのサーバーにリクエストが送信される
Clientが認可リクエストを認可サーバーに送信する
認可サーバーが認可画面のHTMLをレスポンスで返す
Webブラウザで認可画面を表示
End userが認可を行い、認可サーバにリクエストが送信される
認可サーバが認可コードを生成し、ClientのサーバーにRedirectする
Clientのサーバーがstateをチェックし、認可コードからトークンリクエストを認可サーバーに送信する
認可サーバーが認可コードをチェックしてAccess tokenを生成する
認可サーバーからClientのサーバーにリダイレクトしてAccess tokenをClientに返す
ClientはAccess tokenを取得する

ソースコードベースでの説明

ソースコードの詳細な説明に入る前に全体の構成を説明する。今回作るAuth2 Clientのサーバーは以下のendpointを持っている。これらのendpointはソースコード上ではserver.goに定義されている。今回は説明のしやすさのためGoのOAuth2ライブラリであるgolang.org/x/oauth2は使用せず独自で実装している。

/: Sign in with Googleボタンを表示するためのHTMLを返す
/oauth2/authorize: Sign in with GoogleボタンがクリックされるとこのURLが呼び出される。この処理の中でAuthorization serverへリダイレクトし、Authorization requestを送る。
/oauth2/callback: Authorization serverからリダイレクトで呼び出される。Authorization codeを受け取るので、それをもとにToken requestを送ってAccess tokenを取得する
/static: Sign in with Googleボタンのイメージの静的リソースを返す

それではendpointごとに詳細に説明していくとしよう。/ と /static は特に難しいところはないので省略する。

/oauth2/authorize

以下がこのendpointに対するメソッドで、おおまかに説明すると以下のような流れになっている。

まずgenerateStateでstateを生成する
createAuthorizationRequestURLでURLを生成する。このURLにはAuthorization requestに必要なquery stringなどが含まれている。
stateをCookieにセットする
- これはあとで検証に使用するため。stateの検証がなぜ必要かはOAuth 2.0のRFCを参照
- 日本語だとOAuth 2.0のstateとredirect_uriとOpenID ConnectのnonceとID Tokenについて - r-weblifeが詳しい
Authorization server(Google)にリダイレクトする

func (s *server) authorize(w http.ResponseWriter, r *http.Request) {
    state, err := generateState()
    if err != nil {
        s.writeError(w, http.StatusInternalServerError, err)
        return
    }
    u, err := s.createAuthorizationRequestURL(redirectURI, scopes, state)
    if err != nil {
        s.writeError(w, http.StatusInternalServerError, err)
        return
    }
    log.Printf("authorization request url = %v\n", u)

    // Set state to cookie
    cookie := &http.Cookie{
        Name:     stateCookieName,
        Value:    state,
        Path:     "/",
        Expires:  time.Now().Add(10 * time.Minute),
        HttpOnly: true,
    }
    http.SetCookie(w, cookie)

    // Send authorization request by redirection
    http.Redirect(w, r, u.String(), http.StatusFound)
}

createAuthorizationRequestURLが重要なので、次にこのメソッドを詳細に説明する。

func (s *server) createAuthorizationRequestURL(
    redirectURI string,
    scopes []string,
    state string,
) (*url.URL, error) {
    u, err := url.Parse(authorizationEndpoint)
    if err != nil {
        return nil, err
    }

    q := u.Query()
    q.Set("response_type", "code")
    q.Set("client_id", s.clientID)
    if redirectURI != "" {
        q.Set("redirect_uri", redirectURI)
    }
    if len(scopes) > 0 {
        q.Set("scope", strings.Join(scopes, " "))
    }
    q.Set("state", state)
    q.Set("prompt", "consent")
    u.RawQuery = q.Encode()

    return u, nil
}

このメソッドは引数にredirectURI, scopes, stateを受け取る。redirectURIおよびscopesは動的に生成されるものではないのでハードコードしてもよいが、再利用性を考慮してメソッド外部から渡せるようにしている。

このメソッドでは

authorizationEndpointからurl.URLを生成する
必要なパラメータをquery stringとしてセットする
uにquery stringをURL encodeしてセットする
生成したAuthorization requestのURLであるuを返す

という処理を行っている。必要なパラメータについてはOAuth2.0の仕様に定義されているが、簡単に説明すると以下である。

response_type: Authorization code grantのためcodeを指定
client_id: Googleから発行されたClient id
redirect_uri: Googleに登録したRedirect URI
scope
- email: Googleアカウントのメールアドレスを参照できる権限
- https://www.googleapis.com/auth/gmail.readonly: Gmailの情報を参照できる権限
state: 先に生成したランダム文字列
prompt: 今回は認可画面を必ず表示するためにconsentを指定しているが、なくても良い。

話をもとに戻して、createAuthorizationRequestURLで生成されたURLに対してHTTPリダイレクトを行い、GoogleのAuthorization serverにAuthorization requestを送るのがこのメソッドで行っている全てである。

認可画面の表示

Authorization requestが成功すると、Authorization serverから認可画面のHTMLがレスポンスとして返ってくるので、Webブラウザはそれを表示する。Googleの場合だと以下のような画面になる。(Googleにログインしていない場合は、認可画面の前にログイン画面が表示される)

認可画面で表示されている内容は、gmail-fetcherというClient(3rd party application)が、表示されているGoogleアカウントのメールメッセージと設定の表示(scope)を行うことを許可するかどうかを確認するというものだ。ここで許可するというボタンをクリックすると、gmail-fetcherというClientに対してアクセスする許可を与えたので、Access tokenが発行されることになる。

/oauth2/callback

End userが認可画面で許可するボタンをクリックすると、Authorization serverからこのendpointにリダイレクトでコールバックされる。メソッドのコードは以下。

func (s *server) callback(w http.ResponseWriter, r *http.Request) {
    log.Printf("callback: state=%v, code=%v", r.FormValue("state"), r.FormValue("code"))

    if e := r.FormValue("error"); e != "" {
        // Should handler error correctly as described in https://tools.ietf.org/html/rfc6749#section-4.2.2.1
        s.writeError(w, http.StatusBadRequest, fmt.Errorf("error returned in authorization: %v", e))
        return
    }
    if err := validateState(r); err != nil {
        s.writeError(w, http.StatusBadRequest, err)
        return
    }
    code := r.FormValue("code")
    if code == "" {
        s.writeError(w, http.StatusBadRequest, fmt.Errorf("code is required"))
        return
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    token, err := s.exchange(ctx, code)
    if err != nil {
        s.writeError(w, http.StatusInternalServerError, err)
        return
    }

    w.WriteHeader(http.StatusOK)
    fmt.Fprintf(w, "accessToken = %v", token.AccessToken)
    // save token to database or do something
}

やっていることとしては以下になる。OAuth2.0の仕様としてはAuthorization Responseに記載されている。

errorが渡って来ているかどうかをチェック
- 今回の実装では、errorがある場合は400エラーを返すようにしているが、本来であればこれはエラーの種類に応じて適切なエラー画面を表示するのが正しい実装だと思う。エラーの種類に関してもOAuth2.0の仕様に定義されている。
checkStateを呼び出して、Cookieに保存したstateとcallbackのパラメータで来たstateが一致しているかをチェック
- なぜこのようなチェックをしているかは長くなるので別の記事で説明する予定
codeが渡って来ているかをチェック
exchangeを呼び出してcodeからAccess tokenを取得
Access tokenをレスポンスとして返す
- Webブラウザに取得したAccess tokenが表示される
- ちゃんと実装するなら、Access tokenをDBに保存したりするはず

exchangeメソッドについては長くなるので次で詳細に説明する。

exchangeメソッド

これはAuthorization codeからAccess tokenを取得するメソッドである。Access Token Requestに仕様が書かれている。

リクエストに必要なquery stringをセットする
Authorization serverがクライアント認証を行うため、Client idとClient secretをセットする
Token endpointにHTTPリクエストを送る
返ってきたHTTPレスポンスを受け取って内容をパースし、Access tokenなどを得る
Webブラウザで表示するためにAccess tokenをレスポンスにセット

ということがやっていることだ。query stringにセットしているパラメータはそれぞれ以下になる。

grant_type: Authorization code grantなのでauthorization_codeをセット
code: Authorization codeをセット
redirect_uri: Authorization requestで使ったredirect_uriと同じものをセット
client_id: Client idをセット

また、仕様には以下のように書かれているので、Client credentialsとしてreq.SetBasicAuthでClient idとClient secretをセットしている。

The authorization server MUST:

o require client authentication for confidential clients or for any client that was issued client credentials (or with other authentication requirements),

o authenticate the client if client authentication is included,

func (s *server) exchange(ctx context.Context, code string) (*tokenEntity, error) {
    v := url.Values{
        "grant_type":   {"authorization_code"},
        "code":         {code},
        "redirect_uri": {redirectURI},
        "client_id":    {s.clientID},
    }
    req, err := http.NewRequest("POST", tokenEndpoint, strings.NewReader(v.Encode()))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    // Client authentication: https://tools.ietf.org/html/rfc6749#section-4.1.3
    req.SetBasicAuth(url.QueryEscape(s.clientID), url.QueryEscape(s.clientSecret))

    // Send token request
    resp, err := http.DefaultClient.Do(req.WithContext(ctx))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("oauth2: cannot fetch token: %v", err)
    }
    if code := resp.StatusCode; code < 200 || code > 299 {
        // Should handler error correctly as described in https://tools.ietf.org/html/rfc6749#section-5.2
        log.Printf("token request failed: statusCode=%v, body=%v\n", code, string(body))
        return nil, fmt.Errorf("oauth2: token request failed: statusCode=%v", code)
    }

    // Create tokenEntity from response
    var token *tokenEntity
    contentType, _, err := mime.ParseMediaType(resp.Header.Get("Content-Type"))
    if err != nil {
        return nil, fmt.Errorf("oauth2: failed to parse Content-Type header: %v", err)
    }
    if contentType != "application/json" {
        return nil, fmt.Errorf("oauth2: invalid Content-Type in response: %v", contentType)
    }
    token = &tokenEntity{}
    if err = json.Unmarshal(body, token); err != nil {
        return nil, err
    }
    if token.ExpiresIn != 0 {
        token.expiry = time.Now().Add(time.Duration(token.ExpiresIn) * time.Second)
    }

    return token, nil
}

なお、Access tokenには有効期限があり、あとどのぐらいで有効期限が切れるのか？がレスポンスのexpires_inというフィールドにセットされている。通常であればAccess tokenをDBに保存すると同時にこの有効期限も保存しておき、有効期限が切れたらRefresh tokenを使ってAccess tokenをリフレッシュするという処理が必要になる。

まとめ

細かいところは飛ばしつつも、Authorization code grantによるAccess tokenの発行まで、ライブラリを使わずに一通り実装してみた。ところどころにOAuth2.0のRFCへのリンクを入れたので、適宜参照してもらうと仕様の理解が深まるのではないかと思う。自分で実装していて思ったのは、「エラーハンドリングとか細かいところは面倒なポイントがあるけど、全体的にOAuth2.0のClientの実装って簡単じゃん！」ということ。OAuthって聞くとなんか大変そうなイメージがあったけど自分的には攻略できた感じ。この記事が仕事で外部サービスとの連携でクライアントとか認可サーバーの実装しなくてはいけない人たちの役にたてば嬉しいです。

OAuth徹底入門

作者: Justin Richer,Antonio Sanso
出版社/メーカー: 翔泳社
発売日: 2019/02/16
メディア: Kindle版
この商品を含むブログを見る