コンテンツにスキップ

🆔 OAuth 2.1 + OIDC

OAuth は、利用者がパスワードを渡さずに、アプリが利用者の代わりに API を呼べるようにする仕組みです。

OAuth の登場人物: リソースオーナー・クライアント・認可サーバー・リソースサーバー

OAuth は「何をしてよいか」(認可)、OIDC は「誰か」(認証) を扱います。利用者の代わりに API を呼びたいなら OAuth、アプリにログインさせたいなら OIDC を使います。OIDC は OAuth の上に作られているので、OAuth から読んでください。

OAuth と OIDC の比べ: OAuth は認可 (鍵 = アクセストークン)、OIDC は認証 (身分証 = ID トークン)

OAuth には場面ごとにいくつかのフローがありますが、利用者がブラウザでアプリに許可を出す場面では、OAuth 2.1 で残っているのは認可コードフロー (+ PKCE) だけです。ほかのフロー (インプリシット・パスワード) は、トークンやパスワードが漏れやすいため削除されました。
認可コードフローは、まず「認可コード」を受け取り、それを「アクセストークン」に交換するフローです。

このアプリでの使い方と、実装で気をつけることは identity の README にまとめています。下の OIDC のシーケンスを Next.js で 1 つずつ書いた例 (コードとシーケンス図) は NEXTJS.md にあります。


「別のアプリが、ログイン済みのユーザーの代わりに API にリクエストする」ことを認可 (Authorization) するための仕組み

ex) Google

Google の同意画面: クライアントは「Google OAuth 2.0 Playground」、認可サーバーは「Google」、スコープは「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: 攻撃者の認可コードを、送り込まれないようにする

state: 攻撃者の認可コードを送り込まれても、このブラウザが覚えている state と違うので拒否できる

🧩 PKCE: 盗まれた認可コードを、使わせないようにする

PKCE: 認可コードを盗まれても、攻撃者のピース (code_verifier) が型 (code_challenge) に合わないので拒否できる


外部サービス (Google, Facebook, 独自IdPなど) のユーザー情報を用いて認証 (Authentication) を行うための仕組み

ex) 「Google でログイン」

Google のログイン画面: クライアントは「Google OAuth 2.0 Playground」、認可サーバーは「Google」、スコープ (openid email profile) で渡すのは「名前とプロフィール写真」と「メールアドレス」

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 (リソースサーバー) です。クライアントが中身を読んで「自分に発行されたものか」を確かめる決まりはありません。そのため、アクセストークンを受け取ってログインさせるアプリは、ほかのアプリに発行されたアクセストークンを差し出されても見分けられません。

  1. 悪いアプリ X が、利用者に「X に Google でログイン」してもらい、利用者のアクセストークンを手に入れる
  2. X が、そのアクセストークンを、アクセストークンを受け取ってログインさせるアプリ Y に差し出す
  3. Y がそのアクセストークンで UserInfo を呼ぶと利用者の情報が返ってくるので、X を利用者としてログインさせてしまう

ID トークンには、宛先 (aud) に 🪪 クライアントID が書かれ、認可サーバーが署名しています。Y は、aud が自分のクライアント ID でない ID トークンを拒否できます。
なお、自分で認可コードを交換して受け取ったアクセストークンなら、自分宛てなのは確かです。OIDC に対応していない GitHub などのログインは、この形で、アクセストークンを使って本人の情報を API から取ります。


OAuth認可コードフローの簡易的解説|Kawaiiパワーで完全に理解!しっかりやり切るOAuthとOIDC入門 が最もわかりやすい

OAuth

JWT

OIDC