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

![OAuth の登場人物: リソースオーナー・クライアント・認可サーバー・リソースサーバー](overview.svg)

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

![OAuth と OIDC の比べ: OAuth は認可 (鍵 = アクセストークン)、OIDC は認証 (身分証 = ID トークン)](oauth-vs-oidc.svg)

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

このアプリでの使い方と、実装で気をつけることは [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) にまとめています。下の OIDC のシーケンスを Next.js で 1 つずつ書いた例 (コードとシーケンス図) は [NEXTJS.md](NEXTJS.md) にあります。

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

ex) Google

<img src="consent-google.png" alt="Google の同意画面: クライアントは「Google OAuth 2.0 Playground」、認可サーバーは「Google」、スコープは「Google ドライブのファイルに関する情報の参照」" width="900">

パスワードを入れるのは Google の画面だけで、クライアントには渡らない。許可は Google アカウントからいつでも取り消せる

クライアントは、client_secret を安全に持てるかで 2 種類に分かれます。

| | 🔒 機密クライアント | 🌐 公開クライアント |
|:--|:--|:--|
| 例 | Web アプリのサーバー (BFF) | SPA・スマホのアプリ・CLI |
| client_secret | 持てる | 持てない (アプリを解析すれば取り出せる) |
| トークンリクエスト (⑪) | client_secret で認証する | `client_id` だけを送る |

```mermaid
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 の呼び方・トークンの更新) は、下の折りたたみにあります。

<details><summary>🗄️ <b>4. API を呼ぶ: アクセストークンを付けて、リソースサーバーにリクエストする</b></summary>

```mermaid
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
```

</details>

<details><summary>🔄 <b>5. トークンの更新: アクセストークンが切れたら、リフレッシュトークンで取り直す</b></summary>

```mermaid
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
```

</details>

<details><summary>🎲 <b>state: 攻撃者の認可コードを、送り込まれないようにする</b></summary>

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

</details>

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

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

</details>

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

ex) 「Google でログイン」

<img src="login-google.png" alt="Google のログイン画面: クライアントは「Google OAuth 2.0 Playground」、認可サーバーは「Google」、スコープ (openid email profile) で渡すのは「名前とプロフィール写真」と「メールアドレス」" width="900">

OIDC (OpenID Connect) は、OAuth 2.0 の上に「誰か」を確かめる仕組みを足したものです。scope に `openid` を入れると、認可サーバーはアクセストークンと一緒に ID トークンを返します。<br/>
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 の認可コードフローに、✨ の付いたところが増えます。

```mermaid
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
```

<details><summary>🧷 <b>nonce: ID トークンを、このログインのものだと確かめる</b></summary>

クライアントは ② で nonce を作ってこのブラウザのセッションに覚えておき、認可リクエストに付けます。認可サーバーはその nonce を ID トークンに入れて署名し、クライアントは ID トークンの nonce が、覚えた値と同じかを確かめます。<br/>
攻撃者が盗んだ認可コードを自分のブラウザのログインで使っても、返ってくる ID トークンの nonce は盗まれた側のブラウザで作った値なので、合わずに拒否できます。

| | 結び付けるもの | 確かめる人 |
|:--|:--|:--|
| 🎲 state | 認可の応答 (⑧) と、このブラウザ | クライアント |
| 🧩 PKCE | 認可コードと、それを頼んだクライアント | 認可サーバー |
| 🧷 nonce | ID トークンと、このブラウザのログイン | クライアント |

</details>

<details><summary>🪪 <b>認可と認証の違い: アクセストークンを受け取ってログインさせると、なりすまされる</b></summary>

アクセストークンは「API を呼んでよい」という鍵で、読むのは API (リソースサーバー) です。クライアントが中身を読んで「自分に発行されたものか」を確かめる決まりはありません。そのため、アクセストークンを受け取ってログインさせるアプリは、ほかのアプリに発行されたアクセストークンを差し出されても見分けられません。

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

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

</details>

---
## 📚 参考文献
**[OAuth認可コードフローの簡易的解説｜Kawaiiパワーで完全に理解！しっかりやり切るOAuthとOIDC入門](https://zenn.dev/calloc134/books/sikkari-oauth-oidc/viewer/01-intro)** が最もわかりやすい

**OAuth**
 - [Authorization - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
 - [The OAuth 2.1 Authorization Framework](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-15)
 - [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
 - クライアント登録方式 CIMD: [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-01)
 - [RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
 - [RFC 9068 - JSON Web Token(JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068)
 - [RFC 7662 - OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662)
 - [RFC 7009 - OAuth 2.0 Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)
 - [RFC 9700 - Best Current Practice for OAuth 2.0 Security](https://datatracker.ietf.org/doc/html/rfc9700)
 - [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/info/rfc7636/)

**JWT**

 - [RFC 7519 – JSON Web Token (JWT)](https://www.rfc-editor.org/info/rfc7519/)
 - [RFC 7797 - JSON Web Signature (JWS) Unencoded Payload Option](https://www.rfc-editor.org/info/rfc7797/)
 - [RFC 8725 - JSON Web Token Best Current Practices](https://www.rfc-editor.org/info/rfc8725/)

**OIDC**

 - [OpenID Connect 入門：概要と基本的なフロー解説](https://zenn.dev/powersei45/articles/e02e966983ce86)
 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
