OAuth 2.0 を使うべき場面

PART 02 の APIキーは手軽だが、「キーを持っている人なら誰でも、発行したユーザーとして操作できる」という性質がある。OAuth 2.0 では、利用者がブラウザで「このアプリに自分のアカウントでのアクセスを許可する」と同意し、アプリはその利用者専用の アクセストークン を受け取る。

場面おすすめ理由
自分用・チーム内の集計スクリプトAPIキー設定が簡単で、トークンの更新も不要
サーバーで動く夜間バッチAPIキー(集計専用ユーザー)ブラウザでの同意操作ができない
社内の Web ツールで、各自が自分の課題を見るOAuth 2.0利用者ごとの権限で動き、キーを預かる必要がない
社外に配布するアプリ・サービスOAuth 2.0利用者にキーの発行と入力をさせずに済む

この回は、OAuth 2.0 の仕組みを理解するために、手元の PC で動く Python スクリプトで一連の流れを実装する。実際の Web アプリに組み込むときも、やり取りの内容は同じだ。

認可コードフローの流れ

Backlog が対応しているのは、OAuth 2.0 の中でも 認可コードによる認可(Authorization Code Grant) だ。

  1. アプリが利用者のブラウザを Backlog の 認可画面(/OAuth2AccessRequest.action)に送る
  2. 利用者が Backlog にログインし、アプリへのアクセスを 許可 する
  3. Backlog が、アプリ登録時に決めた リダイレクト URI に、認可コード(code)を付けて利用者を戻す
  4. アプリが認可コードと client_secret を トークンエンドポイント(/api/v2/oauth2/token)に送り、アクセストークンとリフレッシュトークンを受け取る
  5. アプリは Authorization: Bearer {アクセストークン} を付けて API を呼ぶ
  6. アクセストークンが切れたら(1時間)、リフレッシュトークンで新しいトークンを受け取る

ポイントは、利用者のパスワードもAPIキーもアプリには渡らない ことと、認可コードをトークンに交換するときに client_secret が必要なため、コードだけ盗まれてもトークンは取れないことだ。

アプリケーションを登録する

OAuth 2.0 を使うには、まず Backlog Developer サイトでアプリケーションを登録し、client_id と client_secret を受け取る。

  1. ブラウザで Backlog Developer のアプリケーション登録ページ を開く
  2. Nulab アカウント でログインする(Backlog のスペースにログインするアカウントとは別に管理されている)
  3. アプリケーションの登録画面で、アプリケーション名・説明・リダイレクト URI を入力して登録する
  4. 表示された Client ID と Client Secret を控える

この回の Python スクリプトでは、手元の PC で受け口を立てるため、リダイレクト URI に http://localhost:8080/callback を登録する前提で書く。登録画面で受け付けられない形式だった場合は、登録できた URI に合わせてスクリプトの値を変える。

登録したアプリケーションは、backlog.com・backlog.jp・backlogtool.com のどのスペースからも使える。

⚠️ リダイレクト URI は1文字でも違うとエラーになる

認可リクエストとトークンリクエストの redirect_uri は、登録した値と完全に一致している必要がある。末尾の / の有無、localhost と 127.0.0.1 の違い、ポート番号の違いでも失敗する。

認可リクエストを送る

利用者のブラウザで次の URL を開く。{host} は利用者のスペース(例:example.backlog.com)だ。

認可リクエスト(GET)
https://{host}/OAuth2AccessRequest.action
    ?response_type=code
    &client_id={Client ID}
    &redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback
    &state={推測できないランダムな文字列}
パラメータ必須内容
response_type必須code 固定
client_id必須アプリ登録で受け取った Client ID
redirect_uri必須登録したリダイレクト URI(URL エンコードする)
state任意リダイレクトでそのまま戻ってくる値。CSRF 対策として必ず付け、戻ってきた値と照合する

利用者が許可すると、ブラウザは次のような URL に戻される。

リダイレクト先
http://localhost:8080/callback?code=xxxxxxxxxxxx&state={送った state}

アクセストークンを取得する

受け取った code を、トークンエンドポイントに POST する。本文は JSON ではなく フォーム形式(application/x-www-form-urlencoded) で送る。

bash(確認用)
curl -sS -X POST "https://$BACKLOG_HOST/api/v2/oauth2/token" \
  -d grant_type=authorization_code \
  -d code=xxxxxxxxxxxx \
  --data-urlencode redirect_uri=http://localhost:8080/callback \
  -d client_id="$BACKLOG_CLIENT_ID" \
  -d client_secret="$BACKLOG_CLIENT_SECRET"
レスポンス例
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

あとは APIキーの代わりに Authorization ヘッダーを付けるだけだ。

bash
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$BACKLOG_HOST/api/v2/users/myself"

認可コードは短時間しか使えず、1回使うと再利用できない。手で curl を打っている間に期限が切れることもあるので、実際には次のようにスクリプトで自動化する。

Python で一連の流れを実装する

標準ライブラリの http.server で localhost:8080 に受け口を立て、ブラウザを開いて認可コードを受け取り、トークンに交換してファイルに保存する。必要なのは requests だけだ。

PowerShell / bash
pip install requests
Python(backlog_oauth.py)
"""Backlog API の OAuth 2.0(認可コードフロー)を手元の PC で実行する"""
import json
import os
import secrets
import time
import webbrowser
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
from urllib.parse import parse_qs, urlencode, urlparse

import requests

HOST = os.environ["BACKLOG_HOST"]                    # 例: example.backlog.com
CLIENT_ID = os.environ["BACKLOG_CLIENT_ID"]
CLIENT_SECRET = os.environ["BACKLOG_CLIENT_SECRET"]
REDIRECT_URI = "http://localhost:8080/callback"      # アプリ登録の値と完全一致させる
TOKEN_FILE = Path.home() / ".backlog_token.json"     # トークンの保存先


def _save(token: dict) -> dict:
    token["obtained_at"] = int(time.time())
    TOKEN_FILE.write_text(json.dumps(token), encoding="utf-8")
    return token


def _post_token(data: dict) -> dict:
    data |= {"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}
    resp = requests.post(f"https://{HOST}/api/v2/oauth2/token", data=data, timeout=30)
    resp.raise_for_status()
    return _save(resp.json())


def authorize() -> dict:
    """ブラウザで許可を得て、アクセストークンを取得する"""
    state = secrets.token_urlsafe(24)
    result = {}

    class Handler(BaseHTTPRequestHandler):
        def do_GET(self):
            q = parse_qs(urlparse(self.path).query)
            result["code"] = q.get("code", [None])[0]
            result["state"] = q.get("state", [None])[0]
            result["error"] = q.get("error", [None])[0]
            self.send_response(200)
            self.send_header("Content-Type", "text/html; charset=utf-8")
            self.end_headers()
            self.wfile.write("認可が完了しました。このタブは閉じてかまいません。".encode("utf-8"))

        def log_message(self, *args):   # アクセスログを出さない
            pass

    url = f"https://{HOST}/OAuth2AccessRequest.action?" + urlencode({
        "response_type": "code",
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "state": state,
    })
    server = HTTPServer(("localhost", 8080), Handler)
    print("ブラウザで Backlog の認可画面を開きます…")
    webbrowser.open(url)
    server.handle_request()          # リダイレクトを1回だけ受け取る
    server.server_close()

    if result.get("error"):
        raise RuntimeError(f"認可が拒否されました: {result['error']}")
    if result.get("state") != state:
        raise RuntimeError("state が一致しません(不正なリダイレクトの可能性)")
    return _post_token({
        "grant_type": "authorization_code",
        "code": result["code"],
        "redirect_uri": REDIRECT_URI,
    })


def refresh(token: dict) -> dict:
    """リフレッシュトークンで新しいアクセストークンを取得する"""
    return _post_token({"grant_type": "refresh_token", "refresh_token": token["refresh_token"]})


def get_access_token() -> str:
    """有効なアクセストークンを返す。期限が近ければ更新し、なければ認可からやり直す"""
    if not TOKEN_FILE.exists():
        return authorize()["access_token"]
    token = json.loads(TOKEN_FILE.read_text(encoding="utf-8"))
    if time.time() > token["obtained_at"] + token["expires_in"] - 300:   # 残り5分を切ったら更新
        try:
            token = refresh(token)
        except requests.HTTPError:
            token = authorize()       # リフレッシュトークンも無効なら、認可からやり直す
    return token["access_token"]


if __name__ == "__main__":
    access_token = get_access_token()
    me = requests.get(f"https://{HOST}/api/v2/users/myself",
                      headers={"Authorization": f"Bearer {access_token}"}, timeout=30)
    me.raise_for_status()
    print(f"認証ユーザー: {me.json()['name']}")
PowerShell
$env:BACKLOG_HOST = 'example.backlog.com'
$env:BACKLOG_CLIENT_ID = '登録で受け取った Client ID'
$env:BACKLOG_CLIENT_SECRET = '登録で受け取った Client Secret'
python backlog_oauth.py

初回はブラウザが開き、Backlog の許可画面が表示される。許可すると「認可が完了しました」と表示され、ターミナルに自分の名前が出る。2回目以降は保存したトークンを使い、期限が近ければ自動で更新する。

data |= {...} は Python 3.9 以降の書き方だ。それより古い Python では data.update({...}) に置き換える。

トークンを更新する

アクセストークンの有効期限は 発行から3600秒(1時間) だ。期限が切れたら、リフレッシュトークンを使って新しいトークンを受け取る。

パラメータ値
grant_typerefresh_token 固定
client_idClient ID
client_secretClient Secret
refresh_token前回受け取ったリフレッシュトークン

更新のタイミングは2通りある。

  • 期限の前に更新する:上のスクリプトのように、取得時刻と expires_in から残り時間を計算する。長いバッチの途中で切れにくい
  • 401 が返ったら更新する:API が 401 を返したら一度だけ更新して再実行する。時刻のずれに強い

実運用では両方を組み合わせると安定する。更新のレスポンスで新しいリフレッシュトークンが返ってきたら、必ずそれで保存し直す(上の _save() は毎回まるごと上書きしている)。

ライブラリを使う場合

公式ライブラリは OAuth 2.0 にも対応している。

ライブラリOAuth 2.0 の扱い
backlog-js(JavaScript)OAuth2 クラスに getAuthorizationURL()・getAccessToken()・refreshAccessToken() がある。クライアントは createClient({ host, accessToken }) で作る(PART 08)
Backlog4j(Java)設定に accessToken(...) を渡してクライアントを作る(PART 09)

PART 05 以降の言語別の回は APIキーで書いているが、ヘッダーを Backlog-API-Key から Authorization: Bearer ... に替えれば、そのまま OAuth 2.0 で動く。

安全に運用するために

  • client_secret はサーバー側にだけ置き、ブラウザで動く JavaScript や配布する実行ファイルに埋め込まない
  • state を毎回ランダムに作り、戻ってきた値と照合する
  • トークンのファイルは本人しか読めない場所に置く(上の例ではホームフォルダ)
  • Web アプリでは、トークンを利用者ごとに暗号化して保存する
  • 本番のリダイレクト URI は HTTPS にする

💡 配布するデスクトップアプリの場合

利用者の PC に配るアプリに client_secret を入れると、取り出されるおそれがある。配布アプリを作るなら、トークンの交換だけを自前のサーバーで行う構成を検討する。社内の限られたメンバーだけで使うなら、各自に APIキーを発行してもらう方が現実的なこともある。

つまずきやすい点

症状原因と対処
認可画面でエラーになるredirect_uri が登録した値と一致していない。エンコード前の文字列を見比べる
トークン取得で 400認可コードの期限切れ・使用済み、または本文を JSON で送っている。フォーム形式で送り直す
API が 401 を返し、本文が空OAuth 2.0 の認証エラーは JSON の本文ではなく WWW-Authenticate ヘッダーに詳細が入る。多くはトークンの期限切れなので更新する
ポート 8080 が使えない他のソフトが使っている。別のポートで登録し直し、スクリプトの REDIRECT_URI と受け口のポートを合わせる
別のスペースで使えないBACKLOG_HOST が許可したスペースと違う。トークンは許可したスペースでのみ有効

✅ 次の記事では…

PART 04 では、言語に関係なく必ず必要になる「ページネーション」「ID の解決」「レート制限」「エラー処理」の考え方をまとめる。

→ PART 04 — 情報取得の基本パターンへ