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) だ。
- アプリが利用者のブラウザを Backlog の 認可画面(
/OAuth2AccessRequest.action)に送る - 利用者が Backlog にログインし、アプリへのアクセスを 許可 する
- Backlog が、アプリ登録時に決めた リダイレクト URI に、認可コード(
code)を付けて利用者を戻す - アプリが認可コードと client_secret を トークンエンドポイント(
/api/v2/oauth2/token)に送り、アクセストークンとリフレッシュトークンを受け取る - アプリは
Authorization: Bearer {アクセストークン}を付けて API を呼ぶ - アクセストークンが切れたら(1時間)、リフレッシュトークンで新しいトークンを受け取る
ポイントは、利用者のパスワードもAPIキーもアプリには渡らない ことと、認可コードをトークンに交換するときに client_secret が必要なため、コードだけ盗まれてもトークンは取れないことだ。
アプリケーションを登録する
OAuth 2.0 を使うには、まず Backlog Developer サイトでアプリケーションを登録し、client_id と client_secret を受け取る。
- ブラウザで Backlog Developer のアプリケーション登録ページ を開く
- Nulab アカウント でログインする(Backlog のスペースにログインするアカウントとは別に管理されている)
- アプリケーションの登録画面で、アプリケーション名・説明・リダイレクト URI を入力して登録する
- 表示された 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)だ。
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) で送る。
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 ヘッダーを付けるだけだ。
curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://$BACKLOG_HOST/api/v2/users/myself"認可コードは短時間しか使えず、1回使うと再利用できない。手で curl を打っている間に期限が切れることもあるので、実際には次のようにスクリプトで自動化する。
Python で一連の流れを実装する
標準ライブラリの http.server で localhost:8080 に受け口を立て、ブラウザを開いて認可コードを受け取り、トークンに交換してファイルに保存する。必要なのは requests だけだ。
pip install requests"""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']}")$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_type | refresh_token 固定 |
client_id | Client ID |
client_secret | Client 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 の解決」「レート制限」「エラー処理」の考え方をまとめる。