LINE WORKS API 2.0 の認証を通すまで

LINE WORKS API を使うとき、最初の関門が認証。ドキュメントが API 1.0 と 2.0 で分かれており、検索で出てくる情報も混在している。ここでは 2.0 の Service Account 認証に絞って、アクセストークンを取得するまでを整理する。

サーバー側の処理から Bot を動かしたり、メンバー情報を取得したりする用途はこの方式になる。画面上でユーザーに許可を求める必要がない。

用意する4つの情報

すべて Developer Console のアプリ設定から取得する。

情報	取得場所	補足
Client ID	アプリ作成時に自動発行
Client Secret	同上	再表示できる
Service Account	「発行」ボタンから作成	仮想の管理者アカウント
Private Key	Service Account 発行後に生成	ダウンロードは一度きり。紛失したら再発行

Private Key は再ダウンロードできない。取得した時点で、パスワードマネージャや Secret Manager に保管しておく。

JWT を組み立てる

Service Account 認証では、まず JWT を自前で作り、それをアクセストークンと交換する。

クレーム	入れる値
`iss`	Client ID
`sub`	Service Account ID
`iat`	現在時刻（UNIX 秒）
`exp`	現在時刻から1時間以内

署名アルゴリズムは RS256。Private Key で署名する。

import jwt
import time

now = int(time.time())
assertion = jwt.encode(
    {
        "iss": CLIENT_ID,
        "sub": SERVICE_ACCOUNT,
        "iat": now,
        "exp": now + 3600,
    },
    PRIVATE_KEY,
    algorithm="RS256",
)

exp を長く取りすぎると弾かれる。1時間以内に収める。

アクセストークンと交換する

作った JWT をトークンエンドポイントに POST する。

import requests

res = requests.post(
    "https://auth.worksmobile.com/oauth2/v2.0/token",
    data={
        "assertion": assertion,
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "bot",
    },
)
access_token = res.json()["access_token"]

scope には使う機能を指定する。Bot からメッセージを送るだけなら bot。メンバー情報を読むなら user.read を追加するなど、必要な分だけを指定する。Developer Console 側のアプリにも同じ権限を付与しておかないと、トークンは取れてもAPI呼び出しで弾かれる。

トークンの寿命を前提に設計する

トークン	有効期限
アクセストークン	24時間
リフレッシュトークン	90日

毎回 JWT から取り直しても動くが、呼び出し回数が増えるとレート制限に当たる。取得したトークンをキャッシュし、期限切れが近づいたらリフレッシュトークンで更新する構成にしておく。

定期実行のバッチであれば、Secret Manager などにトークンを保存し、有効期限を一緒に持たせるのが扱いやすい。

つまずきやすい箇所

invalid_client が返る：Client Secret の前後に空白が混ざっているケースが多い
invalid_grant が返る：iss と sub の取り違え。iss が Client ID、sub が Service Account
トークンは取れるが 403：Developer Console 側でアプリに権限を付けていない
Private Key の改行：環境変数に入れるときに改行が \n の文字列になっていると署名できない