🆔 OAuth 2.1 + OIDC
OAuth は、利用者がパスワードを渡さずに、アプリが利用者の代わりに API を呼べるようにする仕組みです。
OAuth は「何をしてよいか」(認可)、OIDC は「誰か」(認証) を扱います。利用者の代わりに API を呼びたいなら OAuth、アプリにログインさせたいなら OIDC を使います。OIDC は OAuth の上に作られているので、OAuth から読んでください。
OAuth には場面ごとにいくつかのフローがありますが、利用者がブラウザでアプリに許可を出す場面では、OAuth 2.1 で残っているのは認可コードフロー (+ PKCE) だけです。ほかのフロー (インプリシット・パスワード) は、トークンやパスワードが漏れやすいため削除されました。
認可コードフローは、まず「認可コード」を受け取り、それを「アクセストークン」に交換するフローです。
このアプリでの使い方と、実装で気をつけることは identity の README にまとめています。下の OIDC のシーケンスを Next.js で 1 つずつ書いた例 (コードとシーケンス図) は NEXTJS.md にあります。
🔑 OAuth 2.1
Section titled “🔑 OAuth 2.1”「別のアプリが、ログイン済みのユーザーの代わりに API にリクエストする」ことを認可 (Authorization) するための仕組み
ex) Google
パスワードを入れるのは Google の画面だけで、クライアントには渡らない。許可は Google アカウントからいつでも取り消せる
クライアントは、client_secret を安全に持てるかで 2 種類に分かれます。
| 🔒 機密クライアント | 🌐 公開クライアント | |
|---|---|---|
| 例 | Web アプリのサーバー (BFF) | SPA・スマホのアプリ・CLI |
| client_secret | 持てる | 持てない (アプリを解析すれば取り出せる) |
| トークンリクエスト (⑪) | client_secret で認証する | client_id だけを送る |
sequenceDiagram
autonumber
actor User as 🥸 リソースオーナー
participant Client as 📺 クライアント
participant AS as 🛡️ 認可サーバー
rect rgb(150, 150, 150)
Note over User,Client: 1. フロー開始
User->>+Client: リソースにアクセスしてほしい
Client->>Client: 🎲 state と 🧩 code_verifier (どちらもランダムな値) を作って覚えておく<br/>🧩 code_challenge = code_verifier を SHA-256 でハッシュした値
Client->>-User: まずは認可コードを取ってきてください
Note right of User: HTTP 302<br/>https://auth.example.com/oauth2/authorize<br/>?response_type=code<br/>&client_id=<🪪 クライアントID><br/>&redirect_uri=<🔗 認可コードを受け取るリダイレクト先(⑧ の宛先)><br/>&scope=<📦 スペース区切りのスコープ一覧><br/>&state=<🎲 state><br/>&code_challenge=<🧩 code_challenge><br/>&code_challenge_method=S256
end
rect rgb(150, 150, 150)
Note over User,AS: 2. 🎫 認可コード取得
User->>+AS: 認可してください
Note right of User: GET /oauth2/authorize?response_type=code&...
AS->>AS: 🪪 リソースオーナーを認証<br/>(未ログインの場合)
AS->>AS: ✔️ 認可同意を得る<br/>(「このアプリケーションに以下の権限を許可しますか?」を表示)
AS->>AS: 🎫 認可コードを発行<br/>(🧩 code_challenge と結び付けて覚えておく)
AS-->>-User: 認可しました ( 🎫 認可コードを渡す )
Note left of AS: HTTP 302<br/>https://client.example.com/callback?code=<🎫 認可コード>&state=<🎲 state>
end
rect rgb(150, 100, 100)
Note over User,AS: 3. 🔑 アクセストークン取得
User->>+Client: 🎫 認可コードを渡す
Note over User,Client: GET https://client.example.com/callback?code=<🎫 認可コード>&state=<🎲 state>
Client->>Client: 🎲 state が ② で覚えた値と同じか確かめる
Client->>+AS: 認可コードを持っているのでアクセストークンをください
Note over Client,AS: POST https://auth.example.com/oauth2/token<br/>-H "Authorization: <🪪 クライアント認証情報>"<br/>-H "Content-Type: application/x-www-form-urlencoded"<br/>-d "grant_type=authorization_code&code=<🎫 認可コード>&redirect_uri=https://client.example.com/callback&code_verifier=<🧩 code_verifier>"
AS->>AS: 🪪 クライアント認証 (機密クライアントのみ)
AS->>AS: 🔍 認可コードを検証
AS->>AS: 🧩 code_verifier を SHA-256 でハッシュした値が<br/>認可コードと結び付けた code_challenge と同じか確かめる (PKCE)
AS->>AS: 🔑 アクセストークンと 🔄 リフレッシュトークンを発行
AS-->>-Client: 🔑 アクセストークン・🔄 リフレッシュトークン
Note over Client,AS: HTTP 200<br/>{"access_token": "<🔑 アクセストークン>", "token_type": "Bearer", "expires_in": 3600,<br/>"refresh_token": "<🔄 リフレッシュトークン>"}<br/>(expires_in = 有効期限の秒数。refresh_token は返らないこともある)
end
アクセストークンを受け取った後の流れ (API の呼び方・トークンの更新) は、下の折りたたみにあります。
🗄️ 4. API を呼ぶ: アクセストークンを付けて、リソースサーバーにリクエストする
sequenceDiagram
autonumber 17
actor User as 🥸 リソースオーナー
participant Client as 📺 クライアント
participant RS as 🗄️ リソースサーバー
rect rgb(150, 150, 150)
Note over Client,RS: 4. 🗄️ API を呼ぶ
Client->>+RS: 🔑 アクセストークンを付けて、リソースをください
Note over Client,RS: GET https://api.example.com/v1/files<br/>-H "Authorization: Bearer <🔑 アクセストークン>"
RS->>RS: 🔍 アクセストークンを検証<br/>(期限・この API 宛てか・スコープ)
RS-->>-Client: 📄 リソース
Note over Client,RS: HTTP 200<br/>(期限切れなら 401、スコープが足りなければ 403)
Client-->>User: 📄 リソースを使った結果を見せる
end
🔄 5. トークンの更新: アクセストークンが切れたら、リフレッシュトークンで取り直す
sequenceDiagram
autonumber 21
participant Client as 📺 クライアント
participant AS as 🛡️ 認可サーバー
rect rgb(150, 150, 150)
Note over Client,AS: 5. 🔄 トークンの更新
Client->>Client: ⏰ アクセストークンの期限 (expires_in) が切れた、または ⑲ が 401 を返した
Client->>AS: リフレッシュトークンを持っているので、新しいアクセストークンをください
Note over Client,AS: POST https://auth.example.com/oauth2/token<br/>-H "Authorization: <🪪 クライアント認証情報>"<br/>-H "Content-Type: application/x-www-form-urlencoded"<br/>-d "grant_type=refresh_token&refresh_token=<🔄 リフレッシュトークン>"
AS->>AS: 🪪 クライアント認証 (機密クライアントのみ)
AS->>AS: 🔍 リフレッシュトークンを検証
alt 有効
AS->>AS: 🔑 新しいアクセストークンを発行<br/>(🔄 リフレッシュトークンも新しくすることがある = ローテーション)
AS-->>Client: 🔑 新しいアクセストークン (・🔄 新しいリフレッシュトークン)
Note over Client,AS: HTTP 200<br/>{"access_token": "<🔑 新しいアクセストークン>", "token_type": "Bearer", "expires_in": 3600,<br/>"refresh_token": "<🔄 新しいリフレッシュトークン>"}<br/>(refresh_token が入るのは、ローテーションするときだけ)
Client->>Client: 🔄 リフレッシュトークンが返ってきたら上書きして覚え、<br/>🔑 新しいアクセストークンで ⑰ からやり直す
else 失効・期限切れ
AS-->>Client: ❌ 更新できない
Note over Client,AS: HTTP 400<br/>{"error": "invalid_grant"}
Client->>Client: ① からやり直す (許可をもらい直す)
end
end
🎲 state: 攻撃者の認可コードを、送り込まれないようにする
🧩 PKCE: 盗まれた認可コードを、使わせないようにする
🪪 OIDC
Section titled “🪪 OIDC”外部サービス (Google, Facebook, 独自IdPなど) のユーザー情報を用いて認証 (Authentication) を行うための仕組み
ex) 「Google でログイン」
OIDC (OpenID Connect) は、OAuth 2.0 の上に「誰か」を確かめる仕組みを足したものです。scope に openid を入れると、認可サーバーはアクセストークンと一緒に ID トークンを返します。
ID トークンは「誰が (sub)・どのアプリ宛てに (aud)・いつまで (exp)」を書いて認可サーバーが署名した JWT で、クライアントは署名と中身を確かめて、ログインした人を知ります。
OIDC では、リソースオーナーをエンドユーザー、クライアントを RP (Relying Party)、認可サーバーを OP (OpenID Provider) と呼びます。エンドポイントと公開鍵の URL は、OP が /.well-known/openid-configuration で公開しています (例: https://accounts.google.com/.well-known/openid-configuration)。
OAuth 2.1 の認可コードフローに、✨ の付いたところが増えます。
sequenceDiagram
autonumber
actor User as 🥸 エンドユーザー
participant Client as 📺 クライアント (RP)
participant AS as 🛡️ 認可サーバー (OP)
rect rgb(150, 150, 150)
Note over User,Client: 1. フロー開始
User->>+Client: ログインしたい
Client->>Client: 🎲 state・🧩 code_verifier・✨ 🧷 nonce (どれもランダムな値) を作って覚えておく<br/>🧩 code_challenge = code_verifier を SHA-256 でハッシュした値
Client->>-User: まずは認可コードを取ってきてください
Note right of User: HTTP 302<br/>https://auth.example.com/oauth2/authorize<br/>?response_type=code<br/>&client_id=<🪪 クライアントID><br/>&redirect_uri=<🔗 認可コードを受け取るリダイレクト先(⑧ の宛先)><br/>&scope=openid email profile ✨<br/>&state=<🎲 state><br/>&nonce=<🧷 nonce> ✨<br/>&code_challenge=<🧩 code_challenge><br/>&code_challenge_method=S256
end
rect rgb(150, 150, 150)
Note over User,AS: 2. 🎫 認可コード取得
User->>+AS: 認可してください
Note right of User: GET /oauth2/authorize?response_type=code&scope=openid...
AS->>AS: 🪪 エンドユーザーを認証<br/>(未ログインの場合)
AS->>AS: ✔️ 認可同意を得る<br/>(「このアプリケーションに、名前とメールアドレスを共有しますか?」を表示)
AS->>AS: 🎫 認可コードを発行<br/>(🧩 code_challenge と ✨ 🧷 nonce を結び付けて覚えておく)
AS-->>-User: 認可しました ( 🎫 認可コードを渡す )
Note left of AS: HTTP 302<br/>https://client.example.com/callback?code=<🎫 認可コード>&state=<🎲 state>
end
rect rgb(150, 100, 100)
Note over User,AS: 3. 🔑 アクセストークン・✨ 🆔 ID トークン取得
User->>+Client: 🎫 認可コードを渡す
Note over User,Client: GET https://client.example.com/callback?code=<🎫 認可コード>&state=<🎲 state>
Client->>Client: 🎲 state が ② で覚えた値と同じか確かめる
Client->>+AS: 認可コードを持っているので、アクセストークンと ID トークンをください
Note over Client,AS: POST https://auth.example.com/oauth2/token<br/>-H "Authorization: <🪪 クライアント認証情報>"<br/>-H "Content-Type: application/x-www-form-urlencoded"<br/>-d "grant_type=authorization_code&code=<🎫 認可コード>&redirect_uri=https://client.example.com/callback&code_verifier=<🧩 code_verifier>"
AS->>AS: 🪪 クライアント認証 (機密クライアントのみ)
AS->>AS: 🔍 認可コードを検証
AS->>AS: 🧩 code_verifier を SHA-256 でハッシュした値が<br/>認可コードと結び付けた code_challenge と同じか確かめる (PKCE)
AS->>AS: 🔑 アクセストークン・🔄 リフレッシュトークンと<br/>✨ 🆔 ID トークン (🧷 nonce を入れて署名した JWT) を発行
AS-->>-Client: 🔑 アクセストークン・🔄 リフレッシュトークン・🆔 ID トークン
Note over Client,AS: HTTP 200<br/>{"access_token": "<🔑 アクセストークン>", "token_type": "Bearer", "expires_in": 3600,<br/>"refresh_token": "<🔄 リフレッシュトークン>", "id_token": "<🆔 ID トークン>" ✨}<br/>(refresh_token は返らないこともある。<br/>ID トークンは「ヘッダー.中身.署名」を Base64URL で繋いだ JWT)
end
rect rgb(100, 120, 150)
Note over Client,AS: 4. ✨ 🆔 ID トークンの検証
Client->>+AS: 🔐 署名を確かめる公開鍵をください
Note over Client,AS: GET https://auth.example.com/oauth2/jwks<br/>(URL は openid-configuration の jwks_uri)
AS-->>-Client: 🔐 公開鍵の一覧 (JWKS)
Note over Client,AS: HTTP 200<br/>{"keys": [{"kid": "<鍵の ID>", "kty": "RSA", "alg": "RS256", "n": "…", "e": "AQAB"}]}
Client->>Client: 🔐 ID トークンの署名を確かめる<br/>(ヘッダーの kid で公開鍵を選ぶ)
Client->>Client: 🆔 ID トークンの中身 (クレーム) を確かめる
Note over Client,AS: {<br/>"iss": "https://auth.example.com", ← 発行した認可サーバーか<br/>"aud": "<🪪 クライアントID>", ← 自分宛てか<br/>"exp": 1767225600, ← 期限 (UNIX 時間) が過ぎていないか<br/>"iat": 1767222000, ← 発行した時刻<br/>"sub": "1101694…", ← 利用者 ID<br/>"nonce": "<🧷 nonce>",<br/>"email": "user@example.com",<br/>"email_verified": true ← OP がメールアドレスを確認済みか<br/>}
Client->>Client: 🧷 nonce が ② で覚えた値と同じか確かめる
end
rect rgb(150, 150, 150)
Note over User,AS: 5. ✅ ログイン
opt ID トークンに無い情報が要るとき ✨
Client->>+AS: 🔑 アクセストークンを付けて、ユーザー情報をください
Note over Client,AS: GET https://auth.example.com/oauth2/userinfo<br/>-H "Authorization: Bearer <🔑 アクセストークン>"
AS-->>-Client: 👤 ユーザー情報
Note over Client,AS: HTTP 200<br/>{"sub": "1101694…", "name": "山田 太郎", "picture": "https://…"}
Client->>Client: sub が 🆔 ID トークンの sub と同じか確かめる
end
Client->>Client: ✨ iss と sub の組で利用者を探す (初めてなら登録する)<br/>(メールアドレスは変わることがあるので、利用者を見分けるのに使わない)
Client->>Client: 🍪 セッションを作り直す (ログイン前のものを使い続けない)
Client-->>-User: ログインしました
Note over User,Client: HTTP 302<br/>https://client.example.com/<ログインを始めた画面><br/>Set-Cookie: <🍪 セッション>
end
🧷 nonce: ID トークンを、このログインのものだと確かめる
クライアントは ② で nonce を作ってこのブラウザのセッションに覚えておき、認可リクエストに付けます。認可サーバーはその nonce を ID トークンに入れて署名し、クライアントは ID トークンの nonce が、覚えた値と同じかを確かめます。
攻撃者が盗んだ認可コードを自分のブラウザのログインで使っても、返ってくる ID トークンの nonce は盗まれた側のブラウザで作った値なので、合わずに拒否できます。
| 結び付けるもの | 確かめる人 | |
|---|---|---|
| 🎲 state | 認可の応答 (⑧) と、このブラウザ | クライアント |
| 🧩 PKCE | 認可コードと、それを頼んだクライアント | 認可サーバー |
| 🧷 nonce | ID トークンと、このブラウザのログイン | クライアント |
🪪 認可と認証の違い: アクセストークンを受け取ってログインさせると、なりすまされる
アクセストークンは「API を呼んでよい」という鍵で、読むのは API (リソースサーバー) です。クライアントが中身を読んで「自分に発行されたものか」を確かめる決まりはありません。そのため、アクセストークンを受け取ってログインさせるアプリは、ほかのアプリに発行されたアクセストークンを差し出されても見分けられません。
- 悪いアプリ X が、利用者に「X に Google でログイン」してもらい、利用者のアクセストークンを手に入れる
- X が、そのアクセストークンを、アクセストークンを受け取ってログインさせるアプリ Y に差し出す
- Y がそのアクセストークンで UserInfo を呼ぶと利用者の情報が返ってくるので、X を利用者としてログインさせてしまう
ID トークンには、宛先 (aud) に 🪪 クライアントID が書かれ、認可サーバーが署名しています。Y は、aud が自分のクライアント ID でない ID トークンを拒否できます。
なお、自分で認可コードを交換して受け取ったアクセストークンなら、自分宛てなのは確かです。OIDC に対応していない GitHub などのログインは、この形で、アクセストークンを使って本人の情報を API から取ります。
📚 参考文献
Section titled “📚 参考文献”OAuth認可コードフローの簡易的解説|Kawaiiパワーで完全に理解!しっかりやり切るOAuthとOIDC入門 が最もわかりやすい
OAuth
- Authorization - Model Context Protocol
- The OAuth 2.1 Authorization Framework
- The OAuth 2.0 Authorization Framework
- クライアント登録方式 CIMD: OAuth Client ID Metadata Document
- RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage
- RFC 9068 - JSON Web Token(JWT) Profile for OAuth 2.0 Access Tokens
- RFC 7662 - OAuth 2.0 Token Introspection
- RFC 7009 - OAuth 2.0 Token Revocation
- RFC 9700 - Best Current Practice for OAuth 2.0 Security
- RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients
JWT
- RFC 7519 – JSON Web Token (JWT)
- RFC 7797 - JSON Web Signature (JWS) Unencoded Payload Option
- RFC 8725 - JSON Web Token Best Current Practices
OIDC