Authorizationヘッダーは、HTTPのリクエストに認証のための情報を添えるヘッダーです。APIの仕様にある「Bearerトークンを設定する」は、通常、このヘッダーへ指定された形式で値を入れることを指します。
ヘッダーの形式が正しいことと、アクセスが許可されることは別です。 方式、資格情報の値、送信先、利用できる操作を分けると、設定と調査を進めやすくなります。ここではBasicとBearerを例に、値の意味と扱い方を説明します。
Authorizationは要求、WWW-Authenticateはサーバーの応答
クライアントはAuthorizationを使って資格情報を提示します。認証を求めるサーバー側の応答には、WWW-Authenticateという別のヘッダーがあります。401応答では、対象に適用できる認証方式の提示が必要です。Authorizationを設定するたびに、必ず先に401を受けなければならないわけではありません。出典:RFC 9110 §11.3
BasicやBearerでよく見る形は、方式名、空白、資格情報です。次はHTTPS上で送るHTTP要求を読みやすく表した架空例で、実際のトークンは含みません。
GET /reports HTTP/1.1
Host: api.example.test
Authorization: Bearer EXAMPLE_TOKEN
この場合のヘッダー名はAuthorization、方式はBearer、値はEXAMPLE_TOKENです。「Bearer」という文字だけでは資格情報になりません。逆に、トークンを送る欄へ「Authorization:」まで含めると、クライアント側の設定方法によっては余分な文字列になります。ライブラリやAPIツールが方式名を補うか、自分でヘッダー全体を設定するかを確認します。
BasicとBearerは、後ろに置く値の意味が違う
| 方式 | 送る値の作り方・入手元 | 見落としやすい点 |
|---|---|---|
| Basic | 利用者名とパスワードをコロンでつなぎ、Base64で表す | Base64を暗号化と考えない |
| Bearer | APIの認証手順で取得したトークンを設定する | 方式名を付けても、無効な値が有効になるわけではない |
Basicの値は、利用者名とパスワードを表現形式に変えたものです。Base64の文字列を見て元の文字が読み取れなくても、秘密を暗号化して守っていることにはなりません。RFC 7617も、TLSなどの保護と組み合わせないBasic認証を安全な認証方法として扱っていません。出典:RFC 7617 §2・§4
Bearerは、トークンを保持する側がそれを利用できる性質を持つ方式です。トークンの形式を見ただけで、その権限や有効性まで判断しないでください。取得方法や対象APIの仕様に従って扱います。RFC 6750では、Bearerによる送信方法とTLSによる通信保護を定めています。出典:RFC 6750 §1・§2.1
API仕様がBasicを求めているのにBearerへ置き換えるなど、方式名だけを変更しても正しい要求にはなりません。まず、そのAPIが受け付ける方式と必要な値を一組で確認します。
設定を確かめるときは、実値を出さずに構造を見る
たとえば接続テストに失敗した場合、ログへトークン全文を出す前に次の順序で確認できます。
- 送信先は検証用か本番用か。認証情報を取得した環境と、呼び出す環境を取り違えていないか。
- 指定した方式がAPIの仕様に合っているか。BearerやBasicを二重に付けていないか。
- 値が未設定になっていないか。設定ファイルの引用符や改行を値の一部として渡していないか。
- 正規の管理画面や認証処理で、有効期限・失効・許可された操作を確認できるか。
- アプリケーションと通信の入口のどちらが応答したか。要求IDなど、秘密でない情報を使って対応を追えるか。
これは調査順の例であり、すべてのAPIに共通するエラー原因一覧ではありません。記録には「方式Bearer、値あり、送信先は検証環境」のような構造を残し、値そのものは残さない形を検討します。
401は有効な認証情報の不足、403はサーバーが要求を理解したうえで拒否したことを示します。ただし、403という結果だけで「パスワードは正しい」とは断定できません。Bearerの仕様では、無効なトークンと権限不足を区別するエラーも定められています。出典:RFC 9110 §15.5.2・§15.5.4、RFC 6750 §3.1
通信を暗号化しても、ログや共有資料の保護は別に必要
HTTPSで送信しても、アプリケーションが認証情報をログへ書けば、そのログには値が残ります。設定例、画面共有、障害報告、テストレポートへ同じ値を貼らない運用も必要です。
Bearerの仕様は、トークンを意図しない相手へ漏らさないこと、TLSを使うこと、URLにトークンを渡さないことを示しています。URLは履歴やログなどに残る可能性があるためです。出典:RFC 6750 §5.3
チーム内では、資格情報の値そのものではなく、保管場所、利用できる担当、更新方法、漏洩が疑われたときの連絡先を共有すると、調査と保護を両立しやすくなります。発行元に失効や再発行の手順がある場合は、その手順に従います。
Authorizationの設定後は、許可する要求だけでなく、未認証や権限のない要求を拒否できるかも確認します。確認項目の作り方はAPIテストの進め方で説明しています。要求の形式とサーバー側の判断を分け、秘密値を広げずに検証できる状態を整えましょう。