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 のサーバー |
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: ログイン後の画面
- ユーザーが「Google でログイン」を押す
- RP が、ブラウザを Google のログイン画面へリダイレクトする
- ユーザーが Google の画面で本人確認をする。パスワードは Google にだけ送られ、RP には渡らない
- Google が、ブラウザを RP のリダイレクト URI へ戻す。URL には 認可コード が付いている
- RP のサーバーが、認可コードとクライアントシークレットを Google に直接送る。ブラウザは通らない
- Google が両方を確かめ、合っていれば ID トークン と アクセストークン を返す
- ID トークンは「誰が、いつ、どこ向けにログインしたか」が記載されたデータ。ログインにはこちらを使う
- アクセストークンは、Google の API を呼ぶときに使う許可証。ログインには使わない
- 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. クレームを確かめる
- RP が、OP の設定の一覧を取得する。URL は
<iss の値>/.well-known/openid-configurationと決まっている。この仕組みを Discovery と呼ぶ - RP が、一覧の中の
jwks_uriに書かれた URL から公開鍵を取得する - RP が、公開鍵で署名を確かめる
- 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 | 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
- [official] OpenID Connect Core 1.0
- [official] OpenID Connect Discovery 1.0
- [official] RFC 6749 - The OAuth 2.0 Authorization Framework
- [official] RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients
- [official] RFC 7519 - JSON Web Token (JWT)
- [official] OpenID Connect | Sign in with Google | Google for Developers