OIDC の仕組み: ログインの流れと ID トークンの検証

公開

サービスのログイン画面にある「Google でログイン」のボタンの裏では、OIDC(OpenID Connect)という取り決めが動いている。

この記事では、OIDC の仕組みを追う。例は「あるサービス(app.example.com)に Google アカウントでログインする」の 1 つに固定する。

  • 登場人物と、事前の準備
  • ボタンを押してからログインが終わるまでの流れ
  • ログインの結果を運ぶ ID トークンの中身と、その確かめ方
  • OAuth 2.0、JWT、SAML との関係

ログインを別のサービスに任せるための取り決め

サービスごとに ID とパスワードを作る形は、使う人とサービスの運営者の両方に負担がある。

  • 使う人
    • サービスの数だけパスワードを覚える
    • 使い回すと、1 つ漏れたときに他のサービスにも入られる
  • サービスの運営者
    • パスワードを安全に保管する責任を負う
    • 多要素認証、パスワードの再発行、不正ログインの検知を自分で作る

OIDC は、ログインを別のサービスに任せ、その結果を受け取るための取り決め(プロトコル)。

  • 本人であることを確かめる作業は Google が行う
  • app.example.com は、Google から「ログインしたのはこの人」という結果だけを受け取る
  • app.example.com はパスワードを見ないし、保管もしない
flowchart LR
    U["ユーザー"]
    G["Google<br>パスワードを保管<br>本人を確かめる"]
    S1["app.example.com"]
    S2["別のサービス"]
    U -->|"ID とパスワード"| G
    G -->|"ログインした人の情報"| S1
    G -->|"ログインした人の情報"| S2

OIDC が決めているのは、app.example.com と Google の間のやり取りの手順。

  • app.example.com が Google にログインを頼む方法
  • Google がログインした人の情報を app.example.com に渡す方法
  • app.example.com が、受け取った情報が本物であることを確かめる方法

流れに出てくる 4 者と、事前に作る OAuth クライアント

OIDC での呼び名 この記事の例 何か どこにあるか
エンドユーザー ログインする人 人 画面の前
ブラウザ Chrome など プログラム ユーザーの PC
RP(Relying Party) app.example.com ログインの結果を受け取るサービス サービスの運営者のサーバー
OP(OpenID Provider) Google ログインを受け持つサービス Google のサーバー

RP は「OP の結果に頼る側」という意味。OP は IdP(Identity Provider)とも呼ばれる。

OIDC を使うには、RP の運営者が OP に OAuth クライアント を作成しておく必要がある。Google なら、Google Cloud のコンソールで作成する。

OAuth クライアントは、OP の中に置かれる RP の登録情報。作成すると次の 3 つが決まる。

名前 何か
クライアント ID OP が RP を見分けるための ID。公開してよい
クライアントシークレット RP が本物であることを OP に示すパスワード。RP のサーバーだけが持つ
リダイレクト URI ログインのあとに OP がブラウザを戻す先の URL。例は https://app.example.com/callback

クライアントシークレットは長く使う秘密なので、漏れたときに備えて RP の運営者が入れ替える。ユーザーのパスワードを預かる形と比べると、守るものは小さくなる。

  • 守る秘密は、ユーザーの数だけあるパスワードではなく、サービスに 1 つのクライアントシークレット
  • クライアントシークレットが漏れても、ユーザーのパスワードは漏れない

ログインの流れ: 認可コードを ID トークンに引き換える

「Google でログイン」を押してから、ログインが終わるまでに起きることは 7 つ。この流れを 認可コードフロー と呼ぶ。

図の実線の矢印は「頼む・送る」、破線の矢印は「それに対する返事」を表す。リダイレクトは、サーバーがブラウザに「次はこの URL を開いて」と返し、ブラウザが自動でその URL に移動すること。

sequenceDiagram
    actor U as ユーザー
    participant B as ブラウザ
    participant RP as RP<br>(app.example.com)
    participant OP as OP<br>(Google)

    U->>B: 1. 「Google でログイン」を押す
    B->>RP: ログインを始めたい
    RP-->>B: 2. Google のログイン画面へリダイレクト
    B->>OP: ログイン画面を開く
    U->>OP: 3. パスワードを入力して本人確認
    OP-->>B: 4. RP へリダイレクト(認可コード付き)
    B->>RP: 認可コードを届ける
    RP->>OP: 5. 認可コードとクライアントシークレットを送る
    OP-->>RP: 6. ID トークンとアクセストークンを返す
    RP->>RP: 7. ID トークンを確かめる
    RP-->>B: ログイン後の画面
  1. ユーザーが「Google でログイン」を押す
  2. RP が、ブラウザを Google のログイン画面へリダイレクトする
  3. ユーザーが Google の画面で本人確認をする。パスワードは Google にだけ送られ、RP には渡らない
  4. Google が、ブラウザを RP のリダイレクト URI へ戻す。URL には 認可コード が付いている
  5. RP のサーバーが、認可コードとクライアントシークレットを Google に直接送る。ブラウザは通らない
  6. Google が両方を確かめ、合っていれば ID トークン と アクセストークン を返す
    • ID トークンは「誰が、いつ、どこ向けにログインしたか」が記載されたデータ。ログインにはこちらを使う
    • アクセストークンは、Google の API を呼ぶときに使う許可証。ログインには使わない
  7. RP が ID トークンを確かめ、中に書かれたユーザーの ID を見て、ログイン済みとして扱う

Google のログイン画面へ移動するときの URL

RP がブラウザを Google のログイン画面へリダイレクトするとき(認可コードフロー 2)の URL は、RP が組み立てる。

Google のログイン画面が表示されているときに、ブラウザのアドレスバーに出ている URL がこれにあたる。

https://accounts.google.com/o/oauth2/v2/auth
  ?response_type=code
  &client_id=<クライアント ID>
  &redirect_uri=https://app.example.com/callback
  &scope=openid email
  &state=<ランダムな値>
  &nonce=<ランダムな値>
パラメータ 意味
response_type=code 認可コードを返してほしい
client_id どの OAuth クライアントからのログインか
scope=openid email OIDC でログインしたい。メールアドレスも知りたい
state RP が作るランダムな値。Google がブラウザを RP へ戻すときに、同じ値が URL に付いて戻る
nonce RP が作るランダムな値。ID トークンの中に同じ値が入って返る

state と nonce は、どちらも RP が「自分が始めたログインの続きであること」を確かめるための値。

認可コード: ID トークンをブラウザに通さないための引換券

認可コードは、Google が発行するランダムな短い文字列。それ自体に意味のある情報は入っていない。

Google がブラウザを RP へ戻すとき(認可コードフロー 4)の URL に付いている。

https://app.example.com/callback?code=<認可コード>&state=<ランダムな値>

認可コードには 3 つの特徴がある。

  • 1 回しか使えない
  • 有効期限が短い(OAuth 2.0 の仕様は最長 10 分を推奨している)
  • 発行された OAuth クライアントしか使えない

Google が ID トークンを直接返さず、認可コードを挟むのは、RP への戻りがブラウザを通るため。ブラウザの URL は、履歴やログに残りやすい。そこで通り道を 2 つに分けている。

  • ブラウザを通る道(ログイン画面へのリダイレクトから、RP への戻りまで)
    • 運ぶのは認可コードだけ
    • 認可コードだけを手に入れても、クライアントシークレットがないと ID トークンに引き換えられない
  • RP のサーバーと OP が直接つながる道(認可コードを ID トークンに引き換えるやり取り)
    • ID トークンはこちらで運ぶ
    • ブラウザからは見えない

引き換えのときに Google が確かめるのは 2 点。

  • 認可コードが、自分が発行した未使用のものか
  • クライアントシークレットが、その認可コードの発行先の OAuth クライアントのものか

認可コードは「ユーザーがログインを済ませたこと」を、クライアントシークレットは「引き換えに来たのが本物の RP であること」を示す。

ID トークンの中身: ログインの結果を JWT で受け取る

認可コードと引き換えに Google から返ってくる ID トークン(認可コードフロー 6)は、JWT(JSON Web Token)という形式の文字列。

ID トークンを JWT にすることは OIDC の仕様で決まっているので、OP が Google でなくても同じ形式になる。

JWT は . で区切られた 3 つの部分でできている。

flowchart LR
    H["ヘッダー<br>署名の方式と鍵の ID"]
    P["ペイロード<br>ログインした人の情報"]
    S["署名<br>OP が付けた印"]
    H --- P --- S

ヘッダーとペイロードは、JSON を Base64URL という方式で文字列に変えたもの。暗号化はされていないので、誰でも元の JSON に戻して読める。

ペイロードを JSON に戻した例。

{
  "iss": "https://accounts.google.com",
  "sub": "<Google の中でのユーザーの ID>",
  "aud": "<クライアント ID>",
  "exp": 1794900000,
  "iat": 1794896400,
  "nonce": "<RP がログイン画面への URL に付けた値>",
  "email": "user@example.com"
}

1 つ 1 つの項目を クレーム と呼ぶ。クレームの名前と意味も、OIDC の仕様で決まっている。

クレーム 意味
iss 発行した OP(issuer)
sub OP の中での、ログインした人の ID(subject)。メールアドレスを変えても変わらない
aud 誰に向けて発行したか(audience)。RP のクライアント ID が入る
exp この ID トークンの有効期限。Google の場合は発行の 1 時間後
iat この ID トークンを発行した時刻
nonce RP がログイン画面への URL に付けた値
email メールアドレス。scope に email を付けたので入っている

文章にすると、次の内容になる。

Google(iss)から、あなたのサービス(aud)に向けて発行した。 ログインしたユーザーの識別子(sub)と email を伝える。 この ID トークンは iat の時刻に発行し、exp の時刻まで有効。 あなたが送ってきた値(nonce)も入れておく。

sub は OP の中でだけ一意な値なので、RP は iss と sub の組でユーザーを見分ける。

ID トークンを信用するために署名とクレームを確かめる

ペイロードは誰でも読めるし、同じ形の JSON は誰でも作れる。RP は、受け取った ID トークンを確かめてから使う(認可コードフロー 7)。

OP は ID トークンに 署名 を付けている。署名には、2 つで 1 組の鍵を使う。

  • 秘密鍵
    • OP だけが持つ
    • 署名を作るのに使う
  • 公開鍵
    • OP が誰にでも公開している
    • 署名が秘密鍵で作られたことを確かめるのに使う。公開鍵では署名を作れない

RP が署名を確かめると、2 つのことが分かる。

  • この ID トークンは OP が作ったものである
  • 作られたあとに、中身が書き換えられていない

署名は ID トークンの中身から計算して作る。途中で sub や email が 1 文字でも書き換えられると、署名と合わなくなる。

sequenceDiagram
    participant RP as RP<br>(app.example.com)
    participant OP as OP<br>(Google)

    Note over OP: 秘密鍵で署名した ID トークンを発行済み
    RP->>OP: 1. 設定の一覧を要求する
    OP-->>RP: 各エンドポイントの URL と、公開鍵の置き場所
    RP->>OP: 2. 公開鍵を要求する
    OP-->>RP: 公開鍵の一覧
    RP->>RP: 3. 公開鍵で署名を確かめる
    RP->>RP: 4. クレームを確かめる
  1. RP が、OP の設定の一覧を取得する。URL は <iss の値>/.well-known/openid-configuration と決まっている。この仕組みを Discovery と呼ぶ
  2. RP が、一覧の中の jwks_uri に書かれた URL から公開鍵を取得する
  3. RP が、公開鍵で署名を確かめる
  4. RP が、クレームを確かめる

署名のあとに確かめるクレームは 4 つ。

クレーム 確かめること 防げること
iss 自分が頼んだ OP の値か 別の発行元のトークンを受け取ること
aud 自分のクライアント ID か 別のサービス向けに発行されたトークンを使い回されること
exp 期限が切れていないか 古いトークンを使われること
nonce 自分がログイン画面への URL に付けた値と同じか 別のログインのトークンを差し込まれること

OIDC は、OAuth 2.0 をログインに使うためのルール

ここまでの認可コードフローは、もともと OAuth 2.0 の流れ。

OAuth 2.0 は、サービスに「ユーザーの代わりに API を呼ぶ許可」を渡すための取り決め。OAuth 2.0 だけを使う場合、認可コードと引き換えに返るのはアクセストークンだけになる。

OIDC は、この OAuth 2.0 をログインに使うためのルールとして、次のことを決めた。

  • scope に openid を付けると、アクセストークンと一緒に ID トークンを返す
  • ID トークンは JWT の形式にする
  • ID トークンのクレームの名前と意味

3 つの関係は次のとおり。

名前 受け持つもの
OAuth 2.0 流れ(認可コードをもらって、トークンに引き換える手順)
JWT データの形式(ID トークンの入れ物)
OIDC 全体のルール(OAuth 2.0 の流れで、JWT の形の ID トークンを返す)

OIDC を使うときは、必ず OAuth 2.0 と JWT も使っている。

OAuth 2.0 は、OIDC なしで単独でも使える。たとえば、家計簿アプリが銀行の API から明細を読む場合、アプリに必要なのは「明細を読む許可」だけなので、ID トークンは要らない。

ID トークンとアクセストークンの使い道の違い

2 つのトークンは、どちらも OP から RP に渡される。違うのは、RP が受け取ったあとの使い道。

ID トークン アクセストークン
表すもの 「この人がログインした」という結果 「この範囲の API を呼んでよい」という許可
RP の使い道 自分で中身を確かめて、ログイン済みとして扱う 自分では中身を読まず、API を呼ぶときに付けて送る
形式 JWT と決まっている 決まっていない

アクセストークンで何をしてよいかは、ログイン画面への URL の scope と、ユーザーの同意で決まる。その範囲に収まる呼び出しかどうかは、アクセストークンを受け取った API が判断する。

flowchart LR
    OP["OP(Google)"]
    RP["RP(app.example.com)"]
    API["Google の API"]
    OP -->|"ID トークン"| RP
    OP -->|"アクセストークン"| RP
    RP -->|"アクセストークンを付けて呼ぶ"| API

フロントエンドと API に分かれた構成では、API がトークンを確かめる

ブラウザで動くフロントエンド(React など)とバックエンドの API に分かれた構成でも、流れは同じ。RP の置き場所が、サーバーからブラウザの中に変わる。

OP には、Auth0 のような、ログインを受け持つことを専門にしたサービスも使える。

ここまでの例 フロントエンドと API の構成
OP Google Auth0 など
RP app.example.com のサーバー ブラウザで動くフロントエンド
アクセストークンを送る先 Google の API 自分たちの API

ブラウザで動くプログラムは、クライアントシークレットを隠して持つことができない。この構成では、クライアントシークレットの代わりに PKCE という仕組みで、認可コードを引き換えに来た相手を確かめる。

sequenceDiagram
    participant F as フロントエンド
    participant A as API
    participant O as OP<br>(Auth0 など)
    participant D as DB

    F->>A: アクセストークンを付けてリクエスト
    A->>O: 公開鍵を要求する
    O-->>A: 公開鍵
    A->>A: 署名とクレームを確かめる
    A->>D: トークンの中の ID でユーザーを照会
    D-->>A: ユーザー情報
    A-->>F: 応答

API に届くアクセストークンが JWT の形式なら、API は ID トークンのときと同じ方法でそれを確かめる。OP の公開鍵で署名を確かめ、iss、aud、exp を確かめる。

確かめるのがフロントエンドではなく API なのは、フロントエンドがユーザーのブラウザの中で動くため。ブラウザの中のプログラムは、ユーザーが書き換えられる。

API は、フロントエンドの申告ではなく、OP の署名を自分で確かめる。

  • API が信用しているのは、OP の署名
  • フロントエンドは、トークンを運ぶだけ
  • 途中でトークンが書き換えられていれば、署名が合わなくなるので分かる

SAML では、流れもデータの形式も SAML が決めている

OIDC と同じ役割を持つ取り決めに SAML がある。1 つのサービスと IdP の間では、OIDC か SAML のどちらか片方を使う。

OIDC は OAuth 2.0 と JWT を組み合わせているが、SAML は流れもデータの形式も SAML の仕様の中で決めている。

受け持つもの OIDC SAML
流れ OAuth 2.0 の認可コードフロー SAML が決めた流れ
ログインの結果を運ぶデータ ID トークン SAML アサーション
データの形式 JWT(JSON) XML
本物であることの確かめ方 JWT の署名 XML の署名
ログインを受け持つサービスの呼び名 OP IdP
ログインの結果を受け取るサービスの呼び名 RP SP(Service Provider)

OIDC が決めていないこと

  • 本人の確かめ方
    • パスワード、多要素認証、パスキーのどれを使うかは OP が決める
  • ログインしたあとの状態
    • RP は ID トークンを確かめたあと、自分の Cookie などで「ログイン中」を保つ
    • ID トークンの期限が切れても、RP のログイン状態が切れるとは限らない
  • RP の中での権限
    • 管理者か一般ユーザーか、のような区別は RP が自分のデータベースで持つ

用語メモ

用語 読み方 意味
OIDC オーアイディーシー OpenID Connect の略
Relying Party リライング・パーティ ログインの結果を受け取るサービス。RP
OpenID Provider オープンアイディー・プロバイダー ログインを受け持つサービス。OP
JWT ジョット 署名付きの JSON の形式
claim クレーム JWT のペイロードの 1 つ 1 つの項目
nonce ノンス 1 回だけ使うランダムな値。number used once から

まとめ

  • OIDC は、ログインを OP に任せ、結果を ID トークンで受け取るための取り決め
  • OIDC を使うには、OP に OAuth クライアントを作成する。クライアント ID、クライアントシークレット、リダイレクト URI が決まる
  • ブラウザを通る道では認可コードだけを運ぶ。ID トークンは、RP のサーバーが認可コードとクライアントシークレットを OP に送って受け取る
  • ID トークンは JWT。iss、sub、aud、exp などのクレームが入っている
  • RP は、OP の公開鍵で署名を確かめ、クレームを確かめてから ID トークンを使う
  • OIDC は、OAuth 2.0 をログインに使うためのルール。OIDC を使うときは OAuth 2.0 と JWT も使っている

参考 URL

Ritolabo

100%