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

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

OAuth には場面ごとにいくつかのフローがありますが、利用者がブラウザでアプリに許可を出す場面では、OAuth 2.1 で残っているのは認可コードフロー (+ PKCE) だけです。ほかのフロー (インプリシット・パスワード) は、トークンやパスワードが漏れやすいため削除されました。
認可コードフローは、まず「認可コード」を受け取り、それを「アクセストークン」に交換するフローです。
このアプリでの使い方と、実装で気をつけることは [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
パスワードを入れるのは 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 (どちらもランダムな値) を作って覚えておく
🧩 code_challenge = code_verifier を SHA-256 でハッシュした値
Client->>-User: まずは認可コードを取ってきてください
Note right of User: HTTP 302
https://auth.example.com/oauth2/authorize
?response_type=code
&client_id=<🪪 クライアントID>
&redirect_uri=<🔗 認可コードを受け取るリダイレクト先(⑧ の宛先)>
&scope=<📦 スペース区切りのスコープ一覧>
&state=<🎲 state>
&code_challenge=<🧩 code_challenge>
&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: 🪪 リソースオーナーを認証
(未ログインの場合)
AS->>AS: ✔️ 認可同意を得る
(「このアプリケーションに以下の権限を許可しますか?」を表示)
AS->>AS: 🎫 認可コードを発行
(🧩 code_challenge と結び付けて覚えておく)
AS-->>-User: 認可しました ( 🎫 認可コードを渡す )
Note left of AS: HTTP 302
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
-H "Authorization: <🪪 クライアント認証情報>"
-H "Content-Type: application/x-www-form-urlencoded"
-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 でハッシュした値が
認可コードと結び付けた code_challenge と同じか確かめる (PKCE)
AS->>AS: 🔑 アクセストークンと 🔄 リフレッシュトークンを発行
AS-->>-Client: 🔑 アクセストークン・🔄 リフレッシュトークン
Note over Client,AS: HTTP 200
{"access_token": "<🔑 アクセストークン>", "token_type": "Bearer", "expires_in": 3600,
"refresh_token": "<🔄 リフレッシュトークン>"}
(expires_in = 有効期限の秒数。refresh_token は返らないこともある)
end
```
アクセストークンを受け取った後の流れ (API の呼び方・トークンの更新) は、下の折りたたみにあります。
🗄️ 4. API を呼ぶ: アクセストークンを付けて、リソースサーバーにリクエストする
```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
-H "Authorization: Bearer <🔑 アクセストークン>"
RS->>RS: 🔍 アクセストークンを検証
(期限・この API 宛てか・スコープ)
RS-->>-Client: 📄 リソース
Note over Client,RS: HTTP 200
(期限切れなら 401、スコープが足りなければ 403)
Client-->>User: 📄 リソースを使った結果を見せる
end
```
🔄 5. トークンの更新: アクセストークンが切れたら、リフレッシュトークンで取り直す
```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
-H "Authorization: <🪪 クライアント認証情報>"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=refresh_token&refresh_token=<🔄 リフレッシュトークン>"
AS->>AS: 🪪 クライアント認証 (機密クライアントのみ)
AS->>AS: 🔍 リフレッシュトークンを検証
alt 有効
AS->>AS: 🔑 新しいアクセストークンを発行
(🔄 リフレッシュトークンも新しくすることがある = ローテーション)
AS-->>Client: 🔑 新しいアクセストークン (・🔄 新しいリフレッシュトークン)
Note over Client,AS: HTTP 200
{"access_token": "<🔑 新しいアクセストークン>", "token_type": "Bearer", "expires_in": 3600,
"refresh_token": "<🔄 新しいリフレッシュトークン>"}
(refresh_token が入るのは、ローテーションするときだけ)
Client->>Client: 🔄 リフレッシュトークンが返ってきたら上書きして覚え、
🔑 新しいアクセストークンで ⑰ からやり直す
else 失効・期限切れ
AS-->>Client: ❌ 更新できない
Note over Client,AS: HTTP 400
{"error": "invalid_grant"}
Client->>Client: ① からやり直す (許可をもらい直す)
end
end
```
🎲 state: 攻撃者の認可コードを、送り込まれないようにする

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

---
## 🪪 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 の認可コードフローに、✨ の付いたところが増えます。
```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 (どれもランダムな値) を作って覚えておく
🧩 code_challenge = code_verifier を SHA-256 でハッシュした値
Client->>-User: まずは認可コードを取ってきてください
Note right of User: HTTP 302
https://auth.example.com/oauth2/authorize
?response_type=code
&client_id=<🪪 クライアントID>
&redirect_uri=<🔗 認可コードを受け取るリダイレクト先(⑧ の宛先)>
&scope=openid email profile ✨
&state=<🎲 state>
&nonce=<🧷 nonce> ✨
&code_challenge=<🧩 code_challenge>
&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: 🪪 エンドユーザーを認証
(未ログインの場合)
AS->>AS: ✔️ 認可同意を得る
(「このアプリケーションに、名前とメールアドレスを共有しますか?」を表示)
AS->>AS: 🎫 認可コードを発行
(🧩 code_challenge と ✨ 🧷 nonce を結び付けて覚えておく)
AS-->>-User: 認可しました ( 🎫 認可コードを渡す )
Note left of AS: HTTP 302
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
-H "Authorization: <🪪 クライアント認証情報>"
-H "Content-Type: application/x-www-form-urlencoded"
-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 でハッシュした値が
認可コードと結び付けた code_challenge と同じか確かめる (PKCE)
AS->>AS: 🔑 アクセストークン・🔄 リフレッシュトークンと
✨ 🆔 ID トークン (🧷 nonce を入れて署名した JWT) を発行
AS-->>-Client: 🔑 アクセストークン・🔄 リフレッシュトークン・🆔 ID トークン
Note over Client,AS: HTTP 200
{"access_token": "<🔑 アクセストークン>", "token_type": "Bearer", "expires_in": 3600,
"refresh_token": "<🔄 リフレッシュトークン>", "id_token": "<🆔 ID トークン>" ✨}
(refresh_token は返らないこともある。
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
(URL は openid-configuration の jwks_uri)
AS-->>-Client: 🔐 公開鍵の一覧 (JWKS)
Note over Client,AS: HTTP 200
{"keys": [{"kid": "<鍵の ID>", "kty": "RSA", "alg": "RS256", "n": "…", "e": "AQAB"}]}
Client->>Client: 🔐 ID トークンの署名を確かめる
(ヘッダーの kid で公開鍵を選ぶ)
Client->>Client: 🆔 ID トークンの中身 (クレーム) を確かめる
Note over Client,AS: {
"iss": "https://auth.example.com", ← 発行した認可サーバーか
"aud": "<🪪 クライアントID>", ← 自分宛てか
"exp": 1767225600, ← 期限 (UNIX 時間) が過ぎていないか
"iat": 1767222000, ← 発行した時刻
"sub": "1101694…", ← 利用者 ID
"nonce": "<🧷 nonce>",
"email": "user@example.com",
"email_verified": true ← OP がメールアドレスを確認済みか
}
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
-H "Authorization: Bearer <🔑 アクセストークン>"
AS-->>-Client: 👤 ユーザー情報
Note over Client,AS: HTTP 200
{"sub": "1101694…", "name": "山田 太郎", "picture": "https://…"}
Client->>Client: sub が 🆔 ID トークンの sub と同じか確かめる
end
Client->>Client: ✨ iss と sub の組で利用者を探す (初めてなら登録する)
(メールアドレスは変わることがあるので、利用者を見分けるのに使わない)
Client->>Client: 🍪 セッションを作り直す (ログイン前のものを使い続けない)
Client-->>-User: ログインしました
Note over User,Client: HTTP 302
https://client.example.com/<ログインを始めた画面>
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入門](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)
---
# ⚛️ Next.js での OIDC (BFF) の実装例
[OAuth の資料](README.md) の OIDC のシーケンス (1〜5) を、Next.js (App Router) の Route Handler 2 つで書いた例です。Next.js のサーバーが機密クライアント (BFF) になり、トークンはブラウザに渡しません。
流れがつかめるよう、エラーの扱い・IdP を増やす仕組み・セキュリティの細かい確認は省いています。このアプリで実際に気をつけていることは [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) にあります。
使うライブラリ:
- [openid-client](https://github.com/panva/openid-client): OP との通信 (認可リクエストの URL・トークンの交換・ID トークンの検証)
- [iron-session](https://github.com/vvo/iron-session): Cookie に置く値の暗号化
## 🗺️ シーケンス図
```mermaid
sequenceDiagram
actor User as 🥸 エンドユーザー
participant Start as 🖥️ /oauth/google
participant Callback as 🖥️ /oauth/google/callback
participant Google as 🛡️ Google (OP)
rect rgb(150, 150, 150)
Note over User,Start: 1. フロー開始
User->>Start: GET /oauth/google
Start->>Start: 🎲 state・🧷 nonce・🧩 code_verifier を作り、
暗号化した Cookie に覚える
Start-->>User: 302 Google の認可エンドポイント
(state・nonce・code_challenge 付き)
end
rect rgb(150, 150, 150)
Note over User,Google: 2. 🎫 認可コード取得
User->>Google: ログイン・同意
Google-->>User: 302 /oauth/google/callback?code=🎫&state=🎲
end
rect rgb(150, 100, 100)
Note over User,Google: 3. 🔑 トークン取得
User->>Callback: GET /oauth/google/callback?code=🎫&state=🎲
Callback->>Callback: 🎲 state が Cookie の値と同じか確かめる
Callback->>Google: 🎫 認可コード・🧩 code_verifier・client_secret を送る
Google-->>Callback: 🔑 アクセストークン・🆔 ID トークン
end
rect rgb(100, 120, 150)
Note over Callback,Google: 4. 🆔 ID トークンの検証
Callback->>Google: 🔐 公開鍵 (JWKS) を取る
Callback->>Callback: 署名・iss・aud・exp・🧷 nonce を確かめる
end
rect rgb(150, 150, 150)
Note over User,Callback: 5. ✅ ログイン
Callback->>Callback: iss と sub で利用者を探し (初めてなら登録)、
ログイン前の Cookie を消してセッションを作る
Callback-->>User: 302 ログインした後の画面
Set-Cookie: 🍪 セッション
end
```
上の 1〜5 は、下のコードのコメントの番号と対応しています。openid-client が受け持つのは、3 と 4 の大部分です。
## 📄 コード
### OP の設定
OP のエンドポイントと公開鍵の URL は、`/.well-known/openid-configuration` から取ります (discovery)。
`lib/google.ts`
```ts
import * as client from "openid-client";
// Google の OP の設定と、このアプリの client_id・client_secret
export async function google(): Promise {
const config = await client.discovery(
new URL("https://accounts.google.com"),
process.env.GOOGLE_CLIENT_ID!,
process.env.GOOGLE_CLIENT_SECRET!,
);
// 4. ID トークンの署名を、公開鍵 (jwks_uri) で確かめるようにする
client.enableNonRepudiationChecks(config);
return config;
}
// 認可コードを受け取るコールバックの URL。Google の OAuth クライアントの「承認済みのリダイレクト URI」に登録する
export const redirectUri = `${process.env.APP_URL}/oauth/google/callback`;
```
### 1. フロー開始
`app/oauth/google/route.ts`
```ts
import { sealData } from "iron-session";
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import * as client from "openid-client";
import { google, redirectUri } from "@/lib/google";
const password = process.env.SESSION_SECRET!;
export async function GET() {
// 1. 🎲 state・🧷 nonce・🧩 code_verifier を作る (ログインを始めるたびに作り直す)
const state = client.randomState();
const nonce = client.randomNonce();
const codeVerifier = client.randomPKCECodeVerifier();
// コールバックで確かめるまで、暗号化した Cookie に覚えておく (10 分)
(await cookies()).set(
"login",
await sealData({ state, nonce, codeVerifier }, { password, ttl: 600 }),
// Google から戻ってきたときにも送られるよう、SameSite は Lax にする
{ httpOnly: true, secure: true, sameSite: "lax", path: "/", maxAge: 600 },
);
// 認可エンドポイントへ送る。code_challenge は code_verifier の SHA-256
const url = client.buildAuthorizationUrl(await google(), {
redirect_uri: redirectUri,
scope: "openid email profile",
state,
nonce,
code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
code_challenge_method: "S256",
});
return NextResponse.redirect(url);
}
```
### 2. 🎫 認可コード取得
Google の画面でのことなので、コードはありません。Google が `redirect_uri` に認可コードと state を付けて、利用者を戻します。
### 3〜5. コールバック
`app/oauth/google/callback/route.ts`
```ts
import { sealData, unsealData } from "iron-session";
import { cookies } from "next/headers";
import { type NextRequest, NextResponse } from "next/server";
import * as client from "openid-client";
import { google, redirectUri } from "@/lib/google";
import { findOrCreateUser } from "@/lib/users";
const password = process.env.SESSION_SECRET!;
export async function GET(request: NextRequest) {
const cookieStore = await cookies();
// 1. で覚えた値 (Cookie が無い・改ざんされているときは、ログインし直してもらう)
const login = await unsealData<{
state: string;
nonce: string;
codeVerifier: string;
}>(cookieStore.get("login")?.value ?? "", { password });
// 3. 🎲 state を確かめ、🎫 認可コードと 🧩 code_verifier を送って、トークンに交換する。
// 4. ID トークンの署名・iss・aud・exp・🧷 nonce も、openid-client がここで確かめる
const tokens = await client.authorizationCodeGrant(
await google(),
new URL(`${redirectUri}${request.nextUrl.search}`),
{
expectedState: login.state,
expectedNonce: login.nonce,
pkceCodeVerifier: login.codeVerifier,
idTokenExpected: true,
},
);
const claims = tokens.claims()!;
// 5. iss と sub の組で利用者を探す (初めてなら登録する)。
// メールアドレスで既存の利用者と紐付けるなら、email_verified が true のときだけにする
const user = await findOrCreateUser({
iss: claims.iss,
sub: claims.sub,
email: claims.email,
emailVerified: claims.email_verified === true,
});
// ログイン前の Cookie を消し、新しい Cookie でセッションを作る (セッション固定攻撃の対策)。
// トークンはブラウザに渡さない (API を呼ぶなら、サーバー側のセッションストアに置く)
cookieStore.delete("login");
cookieStore.set(
"session",
await sealData({ userId: user.id }, { password, ttl: 14 * 24 * 60 * 60 }),
{ httpOnly: true, secure: true, sameSite: "lax", path: "/" },
);
return NextResponse.redirect(new URL("/", process.env.APP_URL));
}
```
## 🔍 README の手順との対応
| README の OIDC | コード | 誰が確かめるか |
| :-- | :-- | :-- |
| 1. 🎲 state・🧩 code_verifier・🧷 nonce を作って覚える | `route.ts` の `randomState`・`randomPKCECodeVerifier`・`randomNonce` と Cookie | — |
| 1. 認可リクエスト (`response_type=code`・`scope=openid ...`) | `route.ts` の `buildAuthorizationUrl` | — |
| 3. 🎲 state が覚えた値と同じか | `callback/route.ts` の `expectedState` | クライアント (openid-client) |
| 3. 🎫 認可コードを 🔑・🆔 に交換する | `callback/route.ts` の `authorizationCodeGrant` | — |
| 3. 🧩 code_verifier のハッシュが code_challenge と同じか | `pkceCodeVerifier` を送る | OP (Google) |
| 4. 🔐 署名を公開鍵で確かめる | `google.ts` の `enableNonRepudiationChecks` | クライアント (openid-client) |
| 4. iss・aud・exp・🧷 nonce を確かめる | `callback/route.ts` の `expectedNonce` | クライアント (openid-client) |
| 5. iss と sub で利用者を探す・セッションを作り直す | `callback/route.ts` の `findOrCreateUser` と Cookie | — |
## ➕ 実際のアプリで足すもの
この例に、実際のアプリでは次のものを足します。どれも [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) の「実装で気をつけること」に理由があります。
- ログインした後の戻り先 (`?returnTo=`) と、それが自サイトのパスかの確認 (オープンリダイレクトの対策)
- ログインを始める URL を、別のサイトから開かせない (`Sec-Fetch-Site`)
- IdP ごとにコールバックの URL を分け、ログインを始めた IdP と同じかを確かめる (mix-up 攻撃の対策)
- 失敗したとき (同意画面での拒否・state の不一致・認可コードの使い回し) に、ログイン画面に理由を出す
- 302 の応答をキャッシュさせない (`Cache-Control: no-store`)、本番の Cookie の名前に `__Host-` を付ける
このアプリの以前の実装 (この例を、上のものまで含めて書いたもの) は、コミット [`1b44fc7`](https://github.com/theindiehacker/app.fastship.jp/tree/1b44fc7/frontend/src) の `lib/oauth/` と `app/(identity)/oauth/` にあります。
---
# 🛡️ IDaaS と BFF (Identity Platform・Cognito・Auth0)
IDaaS (Identity as a Service) は、利用者の台帳と、Google・GitHub などの IdP でのログインを引き受けるサービスです。アプリは IdP ごとの違いを知らずに、IDaaS が発行したトークンで利用者を見分けられます。
ここでは、Identity Platform・Cognito・Auth0 の 3 つで、BFF (Next.js のサーバー) がログインしてから API を呼ぶまでの流れを比べます。OAuth と OIDC の基本は [OAuth の資料](../OAuth/README.md) を先に読んでください。
前提:
- BFF は、client_secret などの秘密を持てる機密クライアントです ([OAuth の資料](../OAuth/README.md) の表)
- トークンは BFF だけが持ちます。BFF のセッションストア (Valkey など) にトークンを置き、ブラウザの Cookie には推測できないセッション ID だけを入れます。ブラウザの JS からも、Cookie を盗み見た人からも、トークンは見えません
- このアプリは Identity Platform を使っています。実装は [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) にあります
## 🧭 3 つの違い
いちばん大きな違いは、**IdP (Google) でログインした後に、どこへ戻るか**です。
- Identity Platform: IdP から**アプリのコールバック**に戻ります。BFF は、戻ってきた URL を Identity Platform に渡すだけです
- Cognito・Auth0: IdP から **IDaaS のドメイン**に戻ります。IDaaS が自分の認可コードを付けてアプリに戻すので、BFF は IDaaS を相手に、ふつうの OIDC の認可コードフローを行います
| | 🔥 Identity Platform | 🟠 Cognito | 🔴 Auth0 |
| :-- | :-- | :-- | :-- |
| IdP から戻る先 | アプリのコールバック (IdP ごと) | Cognito の `/oauth2/idpresponse` | Auth0 の `/login/callback` |
| IdP の選び方 | `createAuthUri` の `providerId` | 認可リクエストの `identity_provider` | 認可リクエストの `connection` |
| BFF が作る値 | 無し (Identity Platform が返した sessionId を覚えるだけ) | 🎲 state・🧷 nonce・🧩 code_verifier | 🎲 state・🧷 nonce・🧩 code_verifier |
| BFF がすること | REST の API を 2 つ呼ぶ | トークンの交換と ID トークンの検証 (OIDC のクライアント) | トークンの交換と ID トークンの検証 (OIDC のクライアント) |
| BFF が持つ秘密 | API キー | アプリクライアントの client_secret | アプリケーションの client_secret |
| IdP (Google) の client_secret の置き場所 | Identity Platform | Cognito | Auth0 |
| API に渡すトークン | Identity Platform の ID トークン | Cognito のアクセストークン | Auth0 のアクセストークン |
| API が宛先を確かめる値 | `aud` (プロジェクト ID) | `client_id`・`token_use` (アクセストークンに `aud` が無い) | `aud` (API の識別子) |
| トークンの更新 | `securetoken.googleapis.com` | Cognito の `/oauth2/token` | Auth0 の `/oauth/token` (`offline_access` のスコープが要る) |
| Next.js 向けの SDK | 無し (REST を呼ぶ) | 無し (openid-client などの OIDC ライブラリ) | `@auth0/nextjs-auth0` |
---
## 🔥 Identity Platform
BFF は、IdP のログイン画面の URL を Identity Platform に作らせ (`createAuthUri`)、IdP から戻ってきた URL を Identity Platform に渡します (`signInWithIdp`)。state の照合・認可コードの交換・IdP の ID トークンの検証は、すべて Identity Platform が行います。
```mermaid
sequenceDiagram
actor User as 🥸 利用者 (ブラウザ)
participant BFF as 🖥️ BFF (Next.js のサーバー)
participant Store as 🗄️ セッションストア
participant IP as 🔥 Identity Platform
participant IdP as 🔑 IdP (Google)
participant API as 🚀 API
rect rgb(150, 150, 150)
Note over User,IP: 1. ログインを始める
User->>BFF: GET /oauth/google
BFF->>IP: accounts:createAuthUri
(providerId=google.com・continueUri=アプリのコールバック・CODE_FLOW)
IP->>IP: 🎲 state を作り、sessionId と結び付けて覚える
IP-->>BFF: authUri (IdP の認可エンドポイントの URL)・sessionId
BFF-->>User: 302 authUri
Cookie: sessionId (暗号化。10 分)
end
rect rgb(150, 150, 150)
Note over User,IdP: 2. IdP でログインする
User->>IdP: ログイン・同意
IdP-->>User: 302 アプリのコールバック?code=🎫&state=🎲
end
rect rgb(150, 100, 100)
Note over User,IdP: 3. トークンを受け取る
User->>BFF: GET /oauth/google/callback?code=🎫&state=🎲
Cookie: sessionId
BFF->>IP: accounts:signInWithIdp
(requestUri=コールバックの URL とクエリ・sessionId)
IP->>IP: 🎲 state を sessionId と照合する
IP->>IdP: 🎫 認可コードをトークンに交換する
(Identity Platform に設定した Google の client_secret)
IdP-->>IP: Google の ID トークンなど
IP->>IP: Google の ID トークンを確かめ、利用者を探す (初めてなら登録する)
IP-->>BFF: 🆔 Identity Platform の ID トークン (1 時間)・🔄 リフレッシュトークン
BFF->>Store: トークンと利用者を保存する
BFF-->>User: 302 ログインを始めた画面
Cookie: セッション ID だけ
end
rect rgb(100, 120, 150)
Note over User,API: 4. API を呼ぶ
User->>BFF: 画面の操作
Cookie: セッション ID
BFF->>Store: トークンを読む
BFF->>API: Authorization: Bearer 🆔 Identity Platform の ID トークン
API->>API: 署名 (securetoken の公開鍵)・iss・aud (プロジェクト ID)・exp を確かめる
API-->>BFF: 結果
BFF-->>User: 画面 (トークンは入れない)
end
rect rgb(100, 150, 100)
Note over BFF,IP: 5. トークンを更新する (期限の前に)
BFF->>IP: POST securetoken.googleapis.com/v1/token
(grant_type=refresh_token・🔄 リフレッシュトークン)
IP-->>BFF: 新しい 🆔 ID トークン・🔄 リフレッシュトークン
(アカウントが無効なら失敗する)
BFF->>Store: 入れ替える
end
```
- IdP ごとに、アプリのコールバックの URL を IdP に登録します (Google の OAuth クライアントのリダイレクト URI など)
- BFF は IdP と直接話しません。IdP の client_secret も Identity Platform に置くので、BFF が持つ秘密は API キーだけです
---
## 🟠 Cognito
BFF は Cognito の OIDC のクライアントになります。Cognito の認可エンドポイントに `identity_provider=Google` を付けて送ると、Cognito が Google とのやり取りを済ませ、Cognito の認可コードを付けてアプリに戻します。
```mermaid
sequenceDiagram
actor User as 🥸 利用者 (ブラウザ)
participant BFF as 🖥️ BFF (Next.js のサーバー)
participant Store as 🗄️ セッションストア
participant Cognito as 🟠 Cognito (User Pool)
participant IdP as 🔑 IdP (Google)
participant API as 🚀 API
rect rgb(150, 150, 150)
Note over User,Cognito: 1. ログインを始める
User->>BFF: GET /oauth/google
BFF->>BFF: 🎲 state・🧷 nonce・🧩 code_verifier を作る
BFF-->>User: 302 https:///oauth2/authorize
?response_type=code&client_id=<🪪>&redirect_uri=アプリのコールバック
&identity_provider=Google&scope=openid email profile
&state=🎲&nonce=🧷&code_challenge=🧩
Cookie: state・nonce・code_verifier (暗号化。10 分)
end
rect rgb(150, 150, 150)
Note over User,IdP: 2. IdP でログインする (Cognito が仲立ちする)
User->>Cognito: GET /oauth2/authorize?...
Cognito-->>User: 302 Google の認可エンドポイント
(redirect_uri=Cognito の /oauth2/idpresponse)
User->>IdP: ログイン・同意
IdP-->>User: 302 Cognito の /oauth2/idpresponse?code=🎫 (Google の)
User->>Cognito: GET /oauth2/idpresponse?code=🎫
Cognito->>IdP: Google の認可コードをトークンに交換する
(Cognito に設定した Google の client_secret)
IdP-->>Cognito: Google の ID トークンなど
Cognito->>Cognito: Google の ID トークンを確かめ、利用者を探す (初めてなら登録する)
Cognito-->>User: 302 アプリのコールバック?code=🎫 (Cognito の)&state=🎲
end
rect rgb(150, 100, 100)
Note over User,Cognito: 3. トークンを受け取る
User->>BFF: GET /oauth/google/callback?code=🎫&state=🎲
Cookie: state・nonce・code_verifier
BFF->>BFF: 🎲 state が覚えた値と同じか確かめる
BFF->>Cognito: POST /oauth2/token
(code=🎫・code_verifier=🧩・client_id と client_secret)
Cognito-->>BFF: 🆔 ID トークン・🔑 アクセストークン・🔄 リフレッシュトークン
BFF->>BFF: ID トークンの署名 (User Pool の公開鍵)・iss・aud・exp・🧷 nonce を確かめる
BFF->>Store: トークンと利用者を保存する
BFF-->>User: 302 ログインを始めた画面
Cookie: セッション ID だけ
end
rect rgb(100, 120, 150)
Note over User,API: 4. API を呼ぶ
User->>BFF: 画面の操作
Cookie: セッション ID
BFF->>Store: トークンを読む
BFF->>API: Authorization: Bearer 🔑 Cognito のアクセストークン
API->>API: 署名 (User Pool の公開鍵)・iss・client_id・token_use=access・exp を確かめる
API-->>BFF: 結果
BFF-->>User: 画面 (トークンは入れない)
end
rect rgb(100, 150, 100)
Note over BFF,Cognito: 5. トークンを更新する (期限の前に)
BFF->>Cognito: POST /oauth2/token
(grant_type=refresh_token・🔄 リフレッシュトークン・client_secret)
Cognito-->>BFF: 新しい 🆔 ID トークン・🔑 アクセストークン
BFF->>Store: 入れ替える
end
```
- IdP に登録するリダイレクト URI は、Cognito の `/oauth2/idpresponse` 1 つです。アプリのコールバックの URL は、Cognito のアプリクライアントに登録します
- Cognito のアクセストークンには `aud` がありません。API は `client_id` と `token_use` で、自分宛てかを確かめます
---
## 🔴 Auth0
流れは Cognito とほぼ同じで、BFF は Auth0 の OIDC のクライアントになります。違いは、IdP を `connection` で選ぶことと、`audience` に API の識別子を渡すと、アクセストークンがその API 宛ての JWT になることです。
```mermaid
sequenceDiagram
actor User as 🥸 利用者 (ブラウザ)
participant BFF as 🖥️ BFF (Next.js のサーバー)
participant Store as 🗄️ セッションストア
participant Auth0 as 🔴 Auth0
participant IdP as 🔑 IdP (Google)
participant API as 🚀 API
rect rgb(150, 150, 150)
Note over User,Auth0: 1. ログインを始める
User->>BFF: GET /oauth/google
BFF->>BFF: 🎲 state・🧷 nonce・🧩 code_verifier を作る
BFF-->>User: 302 https://<テナント>.auth0.com/authorize
?response_type=code&client_id=<🪪>&redirect_uri=アプリのコールバック
&connection=google-oauth2&audience=
&scope=openid email profile offline_access
&state=🎲&nonce=🧷&code_challenge=🧩
Cookie: state・nonce・code_verifier (暗号化。10 分)
end
rect rgb(150, 150, 150)
Note over User,IdP: 2. IdP でログインする (Auth0 が仲立ちする)
User->>Auth0: GET /authorize?...
Auth0-->>User: 302 Google の認可エンドポイント
(redirect_uri=Auth0 の /login/callback)
User->>IdP: ログイン・同意
IdP-->>User: 302 Auth0 の /login/callback?code=🎫 (Google の)
User->>Auth0: GET /login/callback?code=🎫
Auth0->>IdP: Google の認可コードをトークンに交換する
(Auth0 に設定した Google の client_secret)
IdP-->>Auth0: Google の ID トークンなど
Auth0->>Auth0: 利用者を探す (初めてなら登録する)
Auth0-->>User: 302 アプリのコールバック?code=🎫 (Auth0 の)&state=🎲
end
rect rgb(150, 100, 100)
Note over User,Auth0: 3. トークンを受け取る
User->>BFF: GET /oauth/google/callback?code=🎫&state=🎲
Cookie: state・nonce・code_verifier
BFF->>BFF: 🎲 state が覚えた値と同じか確かめる
BFF->>Auth0: POST /oauth/token
(code=🎫・code_verifier=🧩・client_id と client_secret)
Auth0-->>BFF: 🆔 ID トークン・🔑 アクセストークン (API 宛ての JWT)
・🔄 リフレッシュトークン (offline_access のときだけ)
BFF->>BFF: ID トークンの署名 (テナントの公開鍵)・iss・aud・exp・🧷 nonce を確かめる
BFF->>Store: トークンと利用者を保存する
BFF-->>User: 302 ログインを始めた画面
Cookie: セッション ID だけ
end
rect rgb(100, 120, 150)
Note over User,API: 4. API を呼ぶ
User->>BFF: 画面の操作
Cookie: セッション ID
BFF->>Store: トークンを読む
BFF->>API: Authorization: Bearer 🔑 Auth0 のアクセストークン
API->>API: 署名 (テナントの公開鍵)・iss・aud (API の識別子)・exp・scope を確かめる
API-->>BFF: 結果
BFF-->>User: 画面 (トークンは入れない)
end
rect rgb(100, 150, 100)
Note over BFF,Auth0: 5. トークンを更新する (期限の前に)
BFF->>Auth0: POST /oauth/token
(grant_type=refresh_token・🔄 リフレッシュトークン・client_secret)
Auth0-->>BFF: 新しい 🔑 アクセストークン
(ローテーションを有効にしていれば、新しい 🔄 リフレッシュトークンも)
BFF->>Store: 入れ替える
end
```
- IdP に登録するリダイレクト URI は、Auth0 の `/login/callback` 1 つです。アプリのコールバックの URL は、Auth0 のアプリケーションに登録します
- `@auth0/nextjs-auth0` は、1・3・5 とセッションの作成を引き受けます。既定では、セッション (トークンを含む) を暗号化した Cookie に入れます。トークンをブラウザに一切出さないなら、セッションストアを使う設定にします
---
# 🍪 セッション管理 (Session Management)
## ✅ 前提条件
どの持ち方でも守ることです。
| 項目 | 守ること | 出典 |
| :-- | :-- | :-- |
| Cookie | `Secure`・`HttpOnly` (MUST)。`SameSite`・`Path=/`・`__Host-` 接頭辞 (SHOULD)。`Domain` なし。4096 バイト以内 | [RFC 10017](https://www.rfc-editor.org/rfc/rfc10017.html) §6.1.3.2・[ASVS](https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/5.0/en/0x12-V3-Web-Frontend-Security.md) V3.3 |
| CSRF | 対策する (MUST)。`SameSite` だけで足りるのは、同じサイトにほかのアプリが無いとき。対策の組み合わせは [CSRF の資料](../Security/CSRF/README.md) | [RFC 10017](https://www.rfc-editor.org/rfc/rfc10017.html) §6.1.3.3 |
| 期限 | 使っていない時間と最長の期限を、サーバー側で確かめる | [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)・[NIST](https://pages.nist.gov/800-63-4/sp800-63b/session/) |
| ログイン・権限の変更 | セッション ID を作り直し、古いものを無効にする (セッション固定攻撃の対策)。Cookie を出し直しても ID が同じなら、攻撃者が仕込んだ ID が通る | [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)・[ASVS](https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/5.0/en/0x16-V7-Session-Management.md) 7.2.4 |
| ログアウト | サーバー側でセッションを無効にする。Cookie を消すだけでは、写しが使える | [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)・[ASVS](https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/5.0/en/0x16-V7-Session-Management.md) 7.4.1 |
期限の目安です。
| | [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) | [NIST](https://pages.nist.gov/800-63-4/sp800-63b/aal/#aal2reauth) (AAL2) |
| :-- | :-- | :-- |
| 使っていない時間 | 重要なアプリで 2〜5 分 | 1 時間 |
| 最長の期限 (過ぎたら再認証) | 1 日中使うアプリで 4〜8 時間 | 24 時間 |
---
## 🔑 トークンの分類
| | stateful (発行元が記録を持つ) | stateless (記録を持たない) |
| :-- | :-- | :-- |
| **opaque** (中身を読めない) | セッション ID | 暗号化 Cookie |
| **self-contained** (中身を読める) | JWT + 失効リスト | JWT |
すぐ止められるのは stateful だけです (記録を消せばよい)。
---
## 🔒 セッションの持ち方
| | サーバー側セッション | クライアント側 + 失効の記録 | ⚠️ クライアント側 (記録なし) |
| :-- | :-- | :-- | :-- |
| Cookie の中身 | セッション ID | 署名・暗号化したデータ | 署名・暗号化したデータ |
| サーバーの記録 | セッションのデータ | 失効の記録 | 無し |
| ログアウトで止まる | ✅ | ✅ | ❌ 期限まで有効 |
| 端末ごとのログアウト | ✅ | 失効リストなら ✅ | ❌ |
| 記録が消えたとき | 全員がログアウト (安全側) | 失効リスト・失効時刻なら、失効が効かなくなる (危険側)。署名鍵なら、全員がログアウト (安全側) | ― |
| ASVS 7.4.1 (Level 1) | ✅ | ✅ | ❌ |
- サーバー側: セッション ID は、CSPRNG (暗号論的に安全な乱数生成器) で作った 128 bit 以上のランダムな値にする ([ASVS](https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/5.0/en/0x16-V7-Session-Management.md) 7.2.3)
- クライアント側: 秘密を入れるなら暗号化する ([RFC 10017](https://www.rfc-editor.org/rfc/rfc10017.html): SHOULD)。暗号鍵の管理が要る。失効の記録は、失効リスト・利用者ごとの失効時刻・利用者ごとの署名鍵のどれか ([ASVS](https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/5.0/en/0x16-V7-Session-Management.md) 7.4.1)
- 記録を毎回引くなら stateless の利点は無いので、サーバー側セッションの方が単純で、壊れ方も安全側です
### OAuth と組み合わせる場合 (BFF)
[RFC 10017](https://www.rfc-editor.org/rfc/rfc10017.html) の BFF は、アプリのサーバーを機密クライアントにし、トークンをブラウザの JavaScript から触れさせない形です。
- サーバー側セッション: トークンはサーバーだけが持つ
- クライアント側セッション: トークンを暗号化して Cookie に入れる。API が失効を確かめない ([RFC 7662](https://www.rfc-editor.org/rfc/rfc7662.html) の introspection など) と、アクセストークンは期限まで使える
---
## 📚 参考文献
- [RFC 10017 (OAuth 2.0 for Browser-Based Applications)](https://www.rfc-editor.org/rfc/rfc10017.html): BFF・Cookie・CSRF
- [RFC 6819 §3.1](https://www.rfc-editor.org/rfc/rfc6819.html#section-3.1): opaque なトークンは失効が簡単
- [RFC 7662 (Token Introspection)](https://www.rfc-editor.org/rfc/rfc7662.html): opaque なトークンを発行元に問い合わせて確かめる
- [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
- [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
- [OWASP ASVS 5.0](https://owasp.org/www-project-application-security-verification-standard/): V3.3 Cookie Setup・V7 Session Management
- [NIST SP 800-63B-4 §5](https://pages.nist.gov/800-63-4/sp800-63b/session/): 期限
- [NIST SP 800-63B-4: AAL2 の再認証](https://pages.nist.gov/800-63-4/sp800-63b/aal/#aal2reauth): 期限の目安 (使っていない時間・最長の期限)
- [Next.js: Authentication](https://nextjs.org/docs/app/guides/authentication): Stateless と Database のセッション
---
# 👔 権限 (ロールと操作)
多くの SaaS で扱う権限・ロールについて、ドメイン知識・アクセス制御モデル・ユースケースを紹介します。
この repo の権限の設計は [設計書](IMPLEMENT.md) にまとめています。
## 🗺️ ドメイン知識

認可は「ユーザーが、リソースに、操作をしてよいか」を決めることです。アクセス制御モデルは、ユーザーと権限をどう結ぶかで分かれます。
> [!WARNING]
> 日本の SaaS の画面では、ロールを「権限」と呼ぶことがあります (「管理者権限」など)。ここでは「管理者ロール」と呼びます。
---
## 📚 アクセス制御モデル (Access Control Model)
### ACL (アクセス制御リスト)
> リソースごとに、「誰が、どの操作をできるか」の一覧を保持するモデル
| リソース | ユーザー | 操作 |
|:--|:--|:--|
| 見積書.pdf | A さん | 閲覧・編集 |
| 見積書.pdf | B さん | 閲覧 |
テーブル構成図:
```mermaid
erDiagram
file ||--o{ acl_entry : "許可"
user ||--o{ acl_entry : "許される"
file {
uuid id PK
string name
}
user {
uuid id PK
string email
}
acl_entry {
uuid file_id PK, FK
uuid user_id PK, FK
string permission PK "read・write などの操作"
}
```
ロールを挟まず、リソースごとにユーザーと操作を直接結びます。1 行が 1 件の許可 (ACE: Access Control Entry) です。
- 例: ファイルを特定のユーザーに共有する、S3 のオブジェクト ACL
- 引き換え: ユーザーやリソースが増えると管理しきれない。「チームの全員」「フォルダの中すべて」を表せない
### 固定 RBAC (ロールベースアクセス制御)
> 製品があらかじめ決めたロールをユーザーに付け、そのロールが許す操作で決めるモデル
| ロール | 操作 |
|:--|:--|
| owner | すべて |
| admin | テナントの設定を変える・メンバーを招待する・メンバーのロールを変える・メンバーを外す |
| member | テナントの中のリソースを使う |
テーブル構成図:
```mermaid
erDiagram
tenant ||--|{ membership : "メンバー"
user ||--o{ membership : "所属"
tenant {
uuid id PK
string name
}
user {
uuid id PK
string email
}
membership {
uuid id PK
uuid tenant_id FK "user_id と合わせて一意"
uuid user_id FK
string role "owner・admin・member のどれか"
}
```
ロールが許す操作はコードに書き、テーブルにはユーザーのロールだけを持ちます。
- 例: Slack のワークスペース (オーナー・管理者・メンバー・ゲスト)、Notion のワークスペース (オーナー・メンバー・ゲスト)
- 引き換え: テナントごとにロールを作れない。テナントの中のすべてのリソースに同じロールが効く
### 動的 RBAC
> テナントの管理者が、操作を選んでロールを作り、ユーザーに付けるモデル
| テナント | ロール | 操作 |
|:--|:--|:--|
| A 社 | 経理 | 請求を見る |
| A 社 | 営業 | 顧客を見る・顧客を編集する |
| B 社 | 閲覧者 | 顧客を見る |
テーブル構成図:
```mermaid
erDiagram
tenant ||--|{ membership : "メンバー"
user ||--o{ membership : "所属"
tenant |o--o{ role : "作ったロール"
role ||--o{ membership : "付ける"
role ||--o{ role_permission : "許す操作"
tenant {
uuid id PK
string name
}
user {
uuid id PK
string email
}
membership {
uuid id PK
uuid tenant_id FK "user_id と合わせて一意"
uuid user_id FK
uuid role_id FK "同じテナントのロールか、既定のロール"
}
role {
uuid id PK
uuid tenant_id FK "空なら、すべてのテナントで使える既定のロール"
string name
}
role_permission {
uuid role_id PK, FK
string permission PK "invoice.read などの操作"
}
```
ロールと、ロールが許す操作をテーブルに持ちます。ロールの名前はテナントごとに違うので、コードはロールの名前ではなく操作 (`invoice.read` を持つか) で確かめます。
- 例: GitHub のカスタムリポジトリロール (Enterprise Cloud)、Google Cloud IAM のカスタムロール
- 引き換え: 自分が持たない操作を含むロールを、作ったり付けたりさせない確認が要る (権限の昇格を防ぐ)。製品に足した操作は、作られたロールには入らない
### リソース単位の RBAC
> テナントの中のリソース (プロジェクトなど) ごとにロールを付け、上の階層に付けたロールが下の階層にも効くモデル
| ユーザー | ロールを付ける所 | ロール |
|:--|:--|:--|
| A さん | テナント | admin (テナントの中のすべてのプロジェクトに効く) |
| B さん | プロジェクト X | editor |
| B さん | プロジェクト Y | viewer |
テーブル構成図:
```mermaid
erDiagram
tenant ||--o{ project : "持つ"
user ||--o{ role_binding : "付けられる"
tenant ||..o{ role_binding : "resource_id で指す"
project ||..o{ role_binding : "resource_id で指す"
tenant {
uuid id PK
string name
}
project {
uuid id PK
uuid tenant_id FK
string name
}
user {
uuid id PK
string email
}
role_binding {
uuid id PK
uuid user_id FK "resource_type・resource_id と合わせて一意"
string resource_type "tenant・project のどれか"
uuid resource_id "resource_type のテーブルの id"
string role "tenant なら owner・admin・member、project なら admin・editor・viewer"
}
```
テナントもロールを付けるリソースの 1 つとして扱い、ロールの付与を `role_binding` にまとめます。確かめるときは、そのプロジェクトと親のテナントのロールを合わせて決めます。
- 例: GitHub (Organization のロールと、リポジトリごとの Read・Triage・Write・Maintain・Admin)、Google Cloud IAM (組織・フォルダ・プロジェクトに付けたロールが、下に継承される)
- 引き換え: 確かめるたびに親の階層をたどる。チームを挟んだり、共有の形が増えたりすると表しきれない
### ReBAC (関係ベースアクセス制御)
> ユーザーとリソース、リソースとリソースの関係 (チームのメンバー・フォルダの中など) をたどって、操作ができるかを決めるモデル
関係は、リレーションシップ・タプル (以下、タプル) で持ちます。タプルは「主体 (Subject) が、関係 (Relation) として、リソース (Object) に結び付く」という 1 件の事実です。
| リソース (Object) | 関係 (Relation) | 主体 (Subject) | 意味 |
|:--|:--|:--|:--|
| `team:営業部` | `member` | `user:A` | A さんは、営業部のメンバー |
| `folder:営業` | `viewer` | `team:営業部#member` | 営業部のメンバーは、営業フォルダの閲覧者 |
| `document:見積書` | `parent` | `folder:営業` | 見積書の親は、営業フォルダ |
| `document:見積書` | `owner` | `user:B` | B さんは、見積書の所有者 |
タプルをつなぐとグラフになります (矢印は主体 → リソース)。
```mermaid
flowchart LR
a(("👤 A さん")) -->|member| team["👥 team:営業部"]
team -->|"viewer (メンバー全員)"| folder["📁 folder:営業"]
folder -->|parent| doc["📄 document:見積書"]
b(("👤 B さん")) -->|owner| doc
```
どの関係があれば何ができるかは、別に定義します。例えば文書を見られるのは、次のどれかのときです。
- 文書に、viewer のタプルがある (自分か、自分が入っているチーム)
- 文書の owner である
- 親フォルダの viewer である
A さんが見積書を見られるかは、次のようにたどって確かめます。
1. 見積書に A さんの viewer のタプルは無く、owner は B さん → 親フォルダの viewer かを見る
2. 見積書の parent は営業フォルダ。営業フォルダの viewer は、営業部のメンバー
3. A さんは営業部の member → 見られる
テーブル構成図:
```mermaid
erDiagram
relation_tuple {
string object_type "document・folder・team など"
string object_id
string relation "owner・viewer・member・parent など"
string subject_type "user・team・folder など"
string subject_id
string subject_relation "team#member の member。空なら主体そのもの"
}
```
タプルを 1 つのテーブルに持ちます。ロールも「テナントとの関係」(`tenant#admin`) として書けるので、RBAC を含められます。
- 例: Google ドライブ (フォルダの共有が中のファイルに効く・グループに共有する)。Google は Zanzibar (2019 年の論文) で権限を確かめている
- 実装: OpenFGA・SpiceDB・Ory Keto・Permify。どれも Zanzibar を元にしている
- 引き換え: 確かめるのにグラフをたどる。専用のサービス (OpenFGA など) を使うと、関係のデータをアプリの DB と別に持ち、そろえ続ける
### ABAC (属性ベースアクセス制御)
> ユーザー・リソース・環境 (時刻・IP アドレスなど) の属性を、条件 (ポリシー) で比べて、操作ができるかを決めるモデル
| ポリシー | 操作 | 条件 |
|:--|:--|:--|
| 自分の下書きだけ直せる | 文書を直す | 文書の作成者が自分で、文書の状態が下書き |
| 経理のユーザーだけ請求を見られる | 請求を見る | 自分の部署が経理 |
| 社内からだけ使える | すべて | 接続元の IP アドレスが社内の範囲 |
テーブル構成図:
```mermaid
erDiagram
tenant ||--o{ policy : "作ったポリシー"
tenant ||--|{ membership : "メンバー"
user ||--o{ membership : "所属"
membership ||--o{ member_attribute : "持つ属性"
policy {
uuid id PK
uuid tenant_id FK
string action "invoice.read などの操作"
string effect "allow・deny のどれか"
jsonb condition "属性・比べ方・値の式 (部署が経理、など)"
}
user {
uuid id PK
string email
}
membership {
uuid id PK
uuid tenant_id FK "user_id と合わせて一意"
uuid user_id FK
}
member_attribute {
uuid membership_id PK, FK
string key PK "department など。テナントが足せる"
string value
}
```
テナントの管理者がポリシーを作り、確かめるときに条件を評価します。時刻・IP アドレスなどの環境の属性は、リクエストから取ります。ロールもユーザーの属性の 1 つとして扱えるので、RBAC を含められます。
- 例: AWS IAM の Condition (タグで絞る)
- 実装: OPA (Rego)・Cedar・Casbin。ポリシーで書くため、PBAC (Policy-based Access Control) とも呼ぶ
- 引き換え: 「このユーザーは何ができるか」「このリソースを誰が触れるか」を一覧にしにくい (条件を評価しないと分からない)
---
## 🧭 ユースケース
1 つのモデルに決める必要はありません。多くの SaaS は固定 RBAC で始め、要件が出た所だけほかのモデルを足します。
| ユースケース | 向いているモデル | 理由 |
|:--|:--|:--|
| タスク管理・チャットなど。ロールはオーナー・管理者・メンバーで足りる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) | どの顧客も同じロールでよい |
| 1 件の文書を、社外の人や一部のメンバーにだけ見せる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ACL](#acl-アクセス制御リスト) | 例外の共有だけ、文書ごとに許可を足す |
| 会計・人事・CRM など。顧客が部署に合わせてロールを作る (経理は請求だけ見られる) | [動的 RBAC](#動的-rbac) | 顧客ごとに要るロールが違い、製品で用意しきれない |
| プロジェクト管理・開発ツールなど。プロジェクトごとにメンバーを分ける | [リソース単位の RBAC](#リソース単位の-rbac) | テナントのロールは、すべてのプロジェクトに同じく効いてしまう |
| 文書・ファイルの共有。フォルダの共有が中のファイルに効き、チームにも共有できる | [ReBAC](#rebac-関係ベースアクセス制御) | チーム・フォルダの関係をたどって決まり、入れ子の深さも決まっていない |
| 勤怠・人事評価など。上長が部下のデータを見る・承認する | [ReBAC](#rebac-関係ベースアクセス制御) | 部署の親子と部署の長の関係をたどって決まる |
| 稟議・経費精算など。下書きは作った人だけが直せる・10 万円を超える申請は部長だけが承認できる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ABAC](#abac-属性ベースアクセス制御) | 申請の状態・作成者・金額で結果が変わる |
| 社内の IP アドレスからだけ・営業時間内だけ使わせる | [固定 RBAC](#固定-rbac-ロールベースアクセス制御) + [ABAC](#abac-属性ベースアクセス制御) | 接続元や時刻で決まる |
---
# 🛠️ 設計・実装
## 非機能要件
- **モジュール性**: モジュラモノリスの各モジュールが簡単にマイクロサービスに移行できること
- **変更容易性**:
- 権限を簡単に増やしたり、減らしたりできること
- ロールを簡単に増やしたり、減らしたりできること
- **拡張性**: 固定の RBAC で始めて、あとから動的な RBAC (テナントごとに作れるロール) にしても作り直さずに済むこと
- **自己完結性**: ユーザーのロール・権限を都度問い合わせずに判定できること
- **リアルタイム性**: 権限やロールが変わった時にできるだけ早く反映できること
- **置換性**: IDaaS を差し替えても、権限の仕組みを作り直さずに済むこと
- **安全性**: ロールを付けたり作ったりするときに、自分が持たない権限を与えられない (権限の昇格を防げる) こと
---
## 設計案
### 1. 集中型 (Clerk型)
クラスやファイル、1モジュール(マイクロサービス)でロールと権限を一元管理する方式。権限を増やすたびに更新が必要になる。
> Clerk との違い: Clerk はロールと権限をダッシュボードのデータで持ち、確かめるときは Clerk に問い合わせず、セッショントークンに載った権限 (`fea`・`o.per`・`o.fpm` から組み立てる) を読む。
```mermaid
flowchart LR
project("📁 project モジュール")
other("🧩 ほかの機能のモジュール")
subgraph tenant ["🏢 tenant モジュール"]
role(["👔 Role
owner・admin・member"])
projectPermission(["🔑 project.create・project.delete"])
tenantPermission(["🔑 tenant.update"])
otherPermission(["🔑 ほかの機能の権限"])
role -->|権限を束ねる| projectPermission & tenantPermission & otherPermission
end
project -->|"リクエストのたびに
project.delete をできるか"| tenant
other -->|リクエストのたびに問い合わせる| tenant
user(("👤 ユーザー")) --> project & other
```
実装例
```python
# backend/src/tenant/domain/model/membership/permission.py
class Permission(Enum):
# テナント
TENANT_UPDATE = "tenant.update" # テナントの名前・設定を変える
TENANT_DELETE = "tenant.delete" # テナントを削除する
# 課金
BILLING_MANAGE = "billing.manage" # プランを変える・請求を見る
# メンバー
MEMBERSHIP_INVITE = "membership.invite" # メンバーを招待する・招待を取り消す
MEMBERSHIP_CHANGE_ROLE = "membership.change_role" # メンバーのロールを変える
MEMBERSHIP_REMOVE = "membership.remove" # メンバーを外す
# プロジェクト (project モジュール)
PROJECT_CREATE = "project.create"
PROJECT_DELETE = "project.delete"
# backend/src/tenant/domain/model/membership/role.py
class Role(Enum):
# (permissions と __new__ は今と同じ)
# すべての権限を持つので、足した権限も書かずに済む
OWNER = ("owner", frozenset(Permission))
ADMIN = (
"admin",
frozenset(
{
Permission.TENANT_UPDATE,
Permission.MEMBERSHIP_INVITE,
Permission.MEMBERSHIP_CHANGE_ROLE,
Permission.MEMBERSHIP_REMOVE,
Permission.PROJECT_CREATE,
Permission.PROJECT_DELETE,
}
),
)
MEMBER = ("member", frozenset({Permission.PROJECT_CREATE}))
```
### 2. 分散型 (IDDD型)
各モジュールが自分の権限を持ち、ロールだけを tenant モジュールに問い合わせて自分の Role に訳す方式。ロールを増やすたびに、そのロールに権限を許すモジュールの Role の写しも更新が必要になる (写しに無いロールは拒否する)。
> IDDD との違い: IDDD は権限を持たず、「この人は Moderator ロールか」を問い合わせて、`Moderator` などの値オブジェクトに訳す。
```mermaid
flowchart LR
subgraph project ["📁 project モジュール"]
projectRole(["👔 Role (tenant のロールの写し)
owner・admin・member"])
projectPermission(["🔑 Permission
project.create, ..."])
projectRole -->|権限を束ねる| projectPermission
end
subgraph other ["🧩 ほかの機能のモジュール"]
otherRole(["👔 Role (tenant のロールの写し)"])
otherPermission(["🔑 Permission"])
otherRole -->|権限を束ねる| otherPermission
end
subgraph tenant ["🏢 tenant モジュール"]
role(["👔 Role
owner・admin・member"])
permission(["🔑 Permission
tenant.update, ..."])
role -->|権限を束ねる| permission
end
project -->|"リクエストのたびに
この人のロールは何か"| tenant
other -->|リクエストのたびに問い合わせる| tenant
user(("👤 ユーザー")) --> project & other
```
実装例
```python
# 各モジュールごとに定義
class Role(Enum):
"""tenant のロールを、このモジュールで使う形に訳したもの。ACL アダプターが tenant の公開 IF から作る"""
OWNER = "owner"
ADMIN = "admin"
MEMBER = "member"
class Permission(Enum):
"""プロジェクトの操作と、それを許すロール"""
roles: frozenset[Role]
def __new__(cls, value: str, roles: set[Role]) -> Self:
# Role と同じく、value は文字列のままにする。許すロールが同じ操作が、別名にまとめられないため
permission = object.__new__(cls)
permission._value_ = value
permission.roles = frozenset(roles)
return permission
# プロジェクト
PROJECT_CREATE = ("project.create", {Role.OWNER, Role.ADMIN, Role.MEMBER})
PROJECT_DELETE = ("project.delete", {Role.OWNER, Role.ADMIN})
```
### 3. 合流型 (Kubernetes型)
各モジュールが自分の権限と、それを許すロールの名前を宣言し、起動時に tenant モジュールへ集める方式。機能を足しても tenant モジュールは変えずに済む。tenant モジュールがすべての権限を知るので、集中型と同じく、ロールを DB に移せばテナントごとに作るロールも扱える (宣言した許すロールは、既定のロールの中身になる)。owner には tenant モジュールがすべての権限を許すので、宣言には書かない。
確かめ方は、次の 2 つから選べる。tenant モジュールのロールと権限はどちらも同じで、違うのは確かめる所だけ。
- **tenant に聞く**: 各モジュールは「この人は project.delete をできるか」を tenant モジュールに聞き、tenant モジュールが確かめる
- **権限の集合を受け取る**: 各モジュールは「この人の権限の集合」を tenant モジュールから受け取り、要る権限があるかを自分で確かめる。トークンに権限の集合を載せるときは、こちらになる
> Kubernetes との違い: Kubernetes はコントロールプレーンのコントローラーが、ラベル (`aggregate-to-admin` など) の付いた ClusterRole を動いている間ずっと合流させる。ここでは起動時に 1 回集めるだけ。
```mermaid
flowchart LR
user(("👤 ユーザー"))
subgraph project ["📁 project モジュール"]
projectPermission(["🔑 project.create → admin・member
project.delete → admin"])
end
subgraph other ["🧩 ほかの機能のモジュール"]
otherPermission(["🔑 権限 → 許すロール"])
end
subgraph tenant ["🏢 tenant モジュール"]
role(["👔 Role
owner・admin・member"])
permission(["🔑 tenant.update
project.create・project.delete (合流)"])
role -->|権限を束ねる| permission
end
user --> project & other
project -.->|起動時に宣言を渡す| tenant
other -.->|起動時に宣言を渡す| tenant
project -->|"リクエストのたびに
project.delete をできるか
(または この人の権限の集合)"| tenant
other -->|リクエストのたびに問い合わせる| tenant
```
実装例
```python
# project モジュール: 権限と、それを許すロールの名前を宣言する。起動時に AppModule.permissions で tenant に集める
class Permission(Enum):
# (roles と __new__ は 2 と同じ形。tenant の Role は import できないので、ロールは名前で書く)
PROJECT_CREATE = ("project.create", {"admin", "member"})
PROJECT_DELETE = ("project.delete", {"admin"})
# project モジュール (tenant に聞く): tenant に「この人は project.delete をできるか」を聞く
if not permission_service.can(tenant_id, user_id, Permission.PROJECT_DELETE):
raise SystemException(
ErrorCode.PERMISSION_DENIED, f"permission={Permission.PROJECT_DELETE.value}"
)
# project モジュール (権限の集合を受け取る): tenant から「この人の権限の集合」を受け取り、自分で確かめる
# 例: {"tenant.update", "project.create", "project.delete"}
permissions = permission_service.permissions_of(tenant_id, user_id)
if Permission.PROJECT_DELETE.value not in permissions:
raise SystemException(
ErrorCode.PERMISSION_DENIED, f"permission={Permission.PROJECT_DELETE.value}"
)
# tenant モジュール: 確かめ方に合わせて、できるかだけを答えるか、権限の集合をそのまま返す
def can(self, tenant_id: TenantId, user_id: UserId, permission: Enum) -> bool:
# 各モジュールの権限の Enum を受け取り、値の文字列で権限の集合と比べる
return permission.value in self.permissions_of(tenant_id, user_id)
def permissions_of(self, tenant_id: TenantId, user_id: UserId) -> frozenset[str]:
membership = self.__membership_repository.membership_of(tenant_id, user_id)
if membership is None:
return frozenset()
# ② の Role。権限の値の文字列の集合を持つ
role = self.__role_repository.role_of(membership.role_id)
return role.permissions if role is not None else frozenset()
```
---
## 比較検討
◯ 設計案のとおりで満たす・△ 手を加えれば満たす・× 作り直さないと満たせない
| 非機能要件 | 1. 集中型 (Clerk型) | 2. 分散型 (IDDD型) | 3. 合流型 (Kubernetes型) |
|:--|:-:|:-:|:-:|
| モジュール性 | △ | ◯ | △ |
| 変更容易性 (権限) | × | ◯ | ◯ |
| 変更容易性 (ロール) | ◯ | × | △ |
| 拡張性 | ◯ | × | ◯ |
| 自己完結性 | △ | △ | △ |
| 安全性 | ◯ | × | ◯ |
1. 集中型 (Clerk型)
- メリット
- ロールを足す・減らすのは tenant の Role だけ (変更容易性 (ロール))
- tenant がすべての権限を知っているので、ロールを DB に移せば動的な RBAC にできる。各モジュールは変えない (拡張性)
- tenant がすべての権限を知るので、ロールを付けるときの権限の昇格の確認がすべての権限に効く (安全性)
- ロールと権限の一覧が 1 か所にあり、見通しがよい
- デメリット
- 移す作業は問い合わせる先を tenant の API に替えるだけだが、移したモジュールの権限は tenant に残る。機能を足すたびに tenant も一緒にリリースすることになり、独立してリリースできない (モジュール性)
- 機能を足すたびに、機能のモジュールと tenant の両方を変える。機能のモジュールだけで済ませるには、権限を各モジュールに移す作り直しになる (変更容易性 (権限))
- 動的な RBAC にすると、消した権限の文字列がカスタムロールに残るので、読むときに落とす処理が要る (拡張性)
2. 分散型 (IDDD型)
- メリット
- tenant に聞くのはロールだけなので、問い合わせる先を tenant の API に替えればマイクロサービスに分けられる (モジュール性)
- 権限を足す・減らすのは機能のモジュールだけ (変更容易性 (権限))
- 確かめるのに要るのはロール 1 つなので、トークンに載せても小さい (自己完結性)
- デメリット
- ロールを足す・減らすと、tenant の Role と、そのロールに権限を許すモジュールの Role の写し・訳を変える。マイクロサービスに分けたあとは、それらを一緒にリリースする。tenant だけで済ませるには、ロールに許す権限を tenant に移す作り直しになる (変更容易性 (ロール))
- 各モジュールはコードにあるロールにしか訳せないので、テナントごとのロールを扱えない (拡張性)
- tenant は機能の権限を知らないので、ロールを付けるときの権限の昇格の確認が、tenant の権限にしか効かない。機能の権限は、「ロール X に許すなら、X を付けられるロールにも許す」という手の決まりで守るしかない (安全性)
3. 合流型 (Kubernetes型)
- メリット
- 権限を足す・減らすのは機能のモジュールの宣言だけで、tenant は変えない (変更容易性 (権限))
- tenant がすべての権限を知るので、ロールを DB に移せば動的な RBAC にできる。各モジュールは変えない (拡張性)
- tenant がすべての権限を知るので、ロールを付けるときの権限の昇格の確認がすべての権限に効く (安全性)
- 書き間違えたロールの名前や、重なった権限を起動時に見つけられる
- 権限の集合を受け取る確かめ方なら、1 リクエストで 1 回受け取れば、何度確かめても問い合わせ直さずに済む。画面に「できる操作」もそのまま返せる
- デメリット
- 起動時の合流は 1 つのプロセスの中でしか効かない。マイクロサービスでは、デプロイ時に tenant へ権限を登録する仕組みが要る (モジュール性)
- 既定のロールを足すと、tenant の Role と、そのロールに許す権限を宣言しているモジュールを変える (変更容易性 (ロール))
- 動的な RBAC にすると、消した権限の文字列がカスタムロールに残るので、読むときに落とす処理が要る (拡張性)
- fastship-py の `AppModule` に、権限の宣言を足す必要がある
どの案にも当てはまること
- 図のとおりなら、どの案もリクエストのたびに tenant に問い合わせる。問い合わせずに確かめるには、トークンに載せる。載せるのは、2 はロール、1・3 は権限の集合で、権限が増えるほど大きくなる (自己完結性)
- トークンは、所属するテナントの数でも大きくなる。Clerk のように、選んでいるテナントの分だけ載せる (自己完結性)
- 問い合わせる形なら、ロールの付け替えはすぐ効く。トークンに載せると、トークンが切れるまで効かない。自己完結性とは引き換えになる (リアルタイム性)
- IDaaS から受け取るのはユーザー ID だけで、ロールと権限は tenant に持つ。トークンに載せるときも、IDaaS のカスタムクレームではなく自前で発行するトークンに載せれば、IDaaS を差し替えられる (置換性)
---
## 実装
3. 合流型を、権限の集合を受け取る確かめ方で作る。各モジュールは権限と一緒に既定のロールを公開し、新しい権限を既定のロールに紐付けるのは、権限を足すモジュール自身にする。権限だけを公開すると、機能を足すたびに tenant モジュールの紐付けを変えることになり、集中型と同じ困りごとに戻るため。
| | モジュラモノリス | マイクロサービス |
|:--|:--|:--|
| tenant が全モジュールの権限を集める | 起動時に `CompositeModule.permissions` から | 各サービスのデプロイのたびに、新しい版の `GET /internal/permissions` から |
| 各モジュールが権限の集合を受け取る | tenant モジュールから、同じプロセスの中で | 内部通信トークンのクレームから |
マイクロサービスでは、足した権限はトラフィックを新しい版に流す前に取り込み、発行済みのトークンが切れるのを待つ。先に流すと、取り込むまでとトークンが切れるまで、足した権限を要る操作が owner も含めて拒否される。消した権限は、古い版がまだ確かめているので、流した後に落とす。
```mermaid
sequenceDiagram
autonumber
participant CI as CI (project のデプロイ)
participant P as project サービス (新しい版)
participant T as tenant サービス
participant B as 入口 (BFF)
CI->>P: トラフィックを流さずにデプロイする
CI->>T: project の権限を取り込む (足すだけ)
T->>P: GET /internal/permissions
P-->>T: project.create (既定: admin・member)
project.delete (既定: admin)
T->>T: DB の一覧に足す (取れなければ前回の一覧のまま)
CI->>CI: 内部通信トークンの寿命 (5 分) を待つ
CI->>P: トラフィックを新しい版に流す
CI->>T: project の権限を取り込み直す (新しい版に無い権限を落とす)
B->>T: IDaaS のトークンと、選んでいるテナント
T-->>B: 内部通信トークン (permissions クレーム)
B->>P: DELETE /{tenant_id}/projects/{project_id}
+ 内部通信トークン
P->>P: tenant_id がトークンと同じで、permissions に project.delete があるか
```
### ① 各モジュール: 権限と既定のロールを宣言し、公開する
権限の Enum の基底 (fastship-py の `Permission`。モジュールの `Permission` と名前が重なるので `_Permission` として import する)、`AppModule.permissions` と、それを JSON にして返す `GET /internal/permissions` は fastship-py に足す。
権限の Enum はドメインに置かない。使うのはルート・ツールの門と `core.py` で、ルート (`port.adapter.resource`) やツール (`port.adapter.tool`) は lint-imports の規約で domain を import できないため。
```python
# project/permission/rbac.py
@unique # 値が重なると別名になり、2 つ目の既定のロールが黙って捨てられるため
class Permission(_Permission):
# プロジェクト
PROJECT_CREATE = ("project.create", {"admin", "member"})
PROJECT_DELETE = ("project.delete", {"admin"})
# project/core.py
class Project(AppModule):
@property
@override
def permissions(self) -> list[_Permission]:
return list(Permission)
```
### ② tenant: 全モジュールの権限を集め、ロールを組み立てる
```python
# tenant/domain/model/permission/permission.py
@dataclass(frozen=True)
class Permission:
"""全モジュールの権限の 1 件。モジュラモノリスでは各モジュールの Permission から、マイクロサービスでは JSON から作る。
tenant/permission/rbac.py の Permission (tenant 自身の権限の Enum) とは別物。1 つのファイルで両方は import しない
"""
value: str # 「リソース.操作」
# 既定のロールの名前。owner は書かない (すべての権限を持つ)
default_roles: frozenset[str]
# tenant/domain/model/permission/permission_catalog.py
class PermissionCatalog(abc.ABC):
"""全モジュールの権限の一覧。モジュラモノリスでは、起動時の CompositeModule.permissions から作る"""
@abc.abstractmethod
def permissions(self) -> list[Permission]: ...
# tenant/port/adapter/service/permission/http_permission_catalog.py (マイクロサービス)
class HttpPermissionCatalog(PermissionCatalog):
def refresh(self, service: str, url: str, *, prune: bool) -> None:
"""service の権限を、新しい版の url から取り込む。CI がデプロイの中で 2 回呼ぶ。
トラフィックを流す前は prune=False で足すだけにし、流した後に prune=True で、新しい版に無い権限を落とす
"""
permissions = self.__client.get(f"{url}/internal/permissions")
# 重なった権限や知らない既定のロールがあれば、取り込まずに止める (CI が落ちる)
validate(permissions, self.__repository.all_except(service))
# 取れなかった・止めたときは DB を書き換えない。消えたと扱うと、カスタムロールからも落ち、全員がその権限を失う
if prune:
self.__repository.replace(service, permissions)
else:
self.__repository.merge(service, permissions)
@override
def permissions(self) -> list[Permission]:
return self.__repository.all()
# tenant/domain/model/role/role.py
# owner はすべての権限を持つので、宣言には書かない
BUILT_IN_ROLE_NAMES = ("admin", "member")
@dataclass(frozen=True)
class Role:
"""権限の集合。既定のロール (固定) もカスタムロール (動的) も、同じ形で持つ"""
id: RoleId # 既定のロールは名前 (owner・admin・member)、カスタムロールは UUID
name: str
permissions: frozenset[str] # 権限の値。トークンにそのまま載せる
def covers(self, other: Role) -> bool:
"""other の権限をすべて持つか。ロールを付ける・作るときに確かめ、権限の昇格を防ぐ"""
return other.permissions <= self.permissions
@staticmethod
def built_in(permissions: list[Permission]) -> list[Role]:
"""既定のロールを、全モジュールの宣言から組み立てる。DB には入れない"""
owner = Role(
RoleId("owner"),
"owner",
frozenset(permission.value for permission in permissions),
)
return [owner] + [
Role(
RoleId(name),
name,
frozenset(
permission.value
for permission in permissions
if name in permission.default_roles
),
)
for name in BUILT_IN_ROLE_NAMES
]
@staticmethod
def custom(
role_id: RoleId,
name: str,
stored: frozenset[str],
permissions: list[Permission],
) -> Role:
"""カスタムロールを DB から組み立てる。一覧に無い権限 (消した権限) は落とす"""
return Role(
role_id,
name,
stored & frozenset(permission.value for permission in permissions),
)
```
### ③ tenant: 内部通信トークンを発行する
```python
# tenant/application/token/token_application_service.py
class TokenApplicationService:
def issue(self, id_token: str, tenant_id: str) -> str:
"""IDaaS のトークンを、選んでいるテナントの権限の集合を載せた内部通信トークンに替える。入口 (BFF) が呼ぶ"""
# IDaaS から受け取るのはユーザー ID だけ
user_id = self.__identity_provider.verify(id_token)
membership = self.__membership_repository.membership_of(
TenantId(tenant_id), user_id
)
if membership is None:
raise SystemException(
ErrorCode.PERMISSION_DENIED,
f"tenant_id={tenant_id} user_id={user_id.value}",
)
# 既定のロールは PermissionCatalog から、カスタムロールは DB から
role = self.__role_repository.role_of(membership.role_id)
# 消したカスタムロールが付いたままのときも、500 にせず拒否する
if role is None:
raise SystemException(
ErrorCode.PERMISSION_DENIED, f"role_id={membership.role_id.value}"
)
return self.__token_signer.sign(
# 選んでいるテナントの分だけ載せ、所属するテナントの数でトークンが大きくならないようにする
{
"sub": user_id.value,
"tenant_id": tenant_id,
"permissions": sorted(role.permissions),
},
# 短いほどロールの付け替えが早く効き (リアルタイム性)、長いほど tenant に問い合わせずに済む (自己完結性)
expires_in=timedelta(minutes=5),
)
```
### ④ 各モジュール: 権限の集合で判定する
ルートの門 (`GetCurrentUser`) と、権限の集合を取るポート (`PermissionSource`) は fastship-py に足す。門は、path の `tenant_id` のテナントに所属していなければ 404 (テナントがあることを伏せる)、権限の集合に要る権限が無ければ 403 で拒否する。構成で替わるのは `PermissionSource` の実装だけで、ルートは変わらない。
- **モジュラモノリス**: IDaaS のトークンを確かめ、tenant モジュールから同じプロセスの中で取る
- **マイクロサービス**: 内部通信トークンを tenant の公開鍵 (JWKS) で確かめ、クレームから取る。path の `tenant_id` がクレームと違えば、所属していないときと同じく 404 で拒否する
```python
# project/port/adapter/resource/project/project_resource.py
@router.delete("/{tenant_id}/projects/{project_id}")
def delete_project(
project_id: str,
current_user: Annotated[
CurrentUser, Depends(GetCurrentUser(Permission.PROJECT_DELETE))
],
) -> None:
# 門が確かめるのは「tenant_id のテナントで、その権限があるか」だけ。
# プロジェクトは必ず current_user.tenant_id で絞って取る (ほかのテナントのプロジェクトの ID を指定されても消さない)
...
```
---
# 🛡️ セキュリティ (OWASP Top 10:2025)
> **Web アプリの代表的な 10 のリスクと、その攻撃手法・対策の一覧**
[OWASP Top 10:2025](https://top10.owasp.org/2025/) の項目ごとに、主な攻撃手法と対策を 1 行ずつまとめます。
仕組みと対策のコードまで書いた資料は、攻撃ごとのページにあります。
| 攻撃ごとの資料 | 項目 |
|:--|:--|
| [🔓 IDOR (Insecure Direct Object Reference)](IDOR/README.md) | A01 |
| [👑 権限昇格 (Privilege Escalation)](PrivilegeEscalation/README.md) | A01 |
| [📁 パストラバーサル (Path Traversal)](PathTraversal/README.md) | A01 |
| [🌐 CORS の設定ミス (CORS Misconfiguration)](CORS/README.md) | A01 |
| [👿 CSRF (Cross-Site Request Forgery)](CSRF/README.md) | A01 |
| [🛡️ SSRF (Server-Side Request Forgery)](SSRF/README.md) | A01 |
| [💉 XSS (Cross-Site Scripting)](XSS/README.md) | A05 |
## 🗺️ 全体像
| # | 項目 | 何が起きるか | 主な攻撃手法 |
|:--|:--|:--|:--|
| A01 | [🔓 アクセス制御の不備](#a01--アクセス制御の不備-broken-access-control) | 権限の外のデータ・操作に届く | IDOR・権限昇格・パストラバーサル・CORS の設定ミス・CSRF・SSRF |
| A02 | [🔧 セキュリティの設定ミス](#a02--セキュリティの設定ミス-security-misconfiguration) | 既定の設定や公開設定から入られる | 既定のパスワード・デバッグの公開・XXE |
| A03 | [📦 サプライチェーンの不備](#a03--ソフトウェアのサプライチェーンの不備-software-supply-chain-failures) | 依存や CI から悪意あるコードが入る | 既知の脆弱性・乗っ取られたパッケージ |
| A04 | [🔐 暗号の不備](#a04--暗号の不備-cryptographic-failures) | 秘密が読まれる・推測される | 盗聴・ハッシュの総当たり・予測できる乱数 |
| A05 | [💉 インジェクション](#a05--インジェクション-injection) | 入力がコードとして実行される | SQL インジェクション・XSS・コマンドインジェクション |
| A06 | [📐 安全でない設計](#a06--安全でない設計-insecure-design) | 仕様どおりに動くのに悪用される | 業務ロジックの悪用・競合状態 |
| A07 | [🪪 認証の不備](#a07--認証の不備-authentication-failures) | 他人になりすまされる | パスワードリスト攻撃・セッション固定・JWT の検証漏れ |
| A08 | [🧬 完全性の不備](#a08--ソフトウェアやデータの完全性の不備-software-or-data-integrity-failures) | 改ざんされたコード・データを信じる | 安全でないデシリアライズ・CDN の改ざん |
| A09 | [📜 ログとアラートの不備](#a09--ログとアラートの不備-security-logging-and-alerting-failures) | 攻撃に気づけない | 記録しない・ログから秘密が漏れる |
| A10 | [💥 例外的な状況の誤った扱い](#a10--例外的な状況の誤った扱い-mishandling-of-exceptional-conditions) | エラーのときに守りが外れる | 失敗したら通す (Fail Open)・途中で止まって不整合 |
---
## A01 🔓 アクセス制御の不備 (Broken Access Control)
> 利用者が、権限の外のデータや操作に届いてしまう
| 攻撃手法 | 何をされるか | 対策 |
|:--|:--|:--|
| IDOR (他人の ID の指定) | `/invoices/123` を `124` に変え、他人の請求書を読む | サーバーで、そのリソースに届いてよい利用者かを毎回確かめる ([IDOR の資料](IDOR/README.md)) |
| 権限昇格 | 一般の利用者が、管理者の API を直接呼ぶ | 既定で拒否し、操作ごとに権限を確かめる ([権限昇格の資料](PrivilegeEscalation/README.md)) |
| パストラバーサル | `../../etc/passwd` を渡し、サーバーのファイルを読む | ファイルは ID で引き、利用者の入力でパスを組み立てない ([パストラバーサルの資料](PathTraversal/README.md)) |
| CORS の設定ミス | どのサイトにも Cookie 付きの応答を読ませる | 許可するオリジンを列挙する (`*` と `allow_credentials` を組み合わせない・`Origin` をそのまま返さない・正規表現で許すときは前後を固定する) ([CORS の資料](CORS/README.md)) |
| CSRF | 罠サイトから、ログイン中の利用者に操作を送らせる | [CSRF の資料](CSRF/README.md) |
| SSRF | サーバーに、内部 (メタデータサーバーなど) へリクエストを送らせる | [SSRF の資料](SSRF/README.md) |
- ⚠️ 画面でボタンを隠すだけでは防げません。API を直接呼ばれるので、確かめるのは必ずサーバーです
## A02 🔧 セキュリティの設定ミス (Security Misconfiguration)
> 既定の設定・不要な機能・緩い公開設定が、そのまま本番に残る
| 攻撃手法 | 何をされるか | 対策 |
|:--|:--|:--|
| 既定のアカウント・パスワード | 管理画面に `admin` / `admin` でログインされる | 既定のアカウントを消し、設定を IaC (Terraform) で管理する |
| デバッグ・詳細なエラーの公開 | スタックトレースから、構成や秘密を知られる | 本番ではデバッグを切り、エラーの詳細はログにだけ出す |
| セキュリティヘッダーの不足 | クリックジャッキング・MIME の誤判定で XSS | CSP・`X-Frame-Options` などを付ける |
| XXE (XML の外部実体) | XML の外部実体で、サーバーのファイルを読まれる | XML パーサーの外部実体を切る (Python は `defusedxml`) |
| クラウドの公開設定ミス | ストレージのバケットを公開にして、データが漏れる | 公開アクセスの禁止を組織のポリシーで強制する |
- Trivy などのスキャナーで、IaC (Terraform など) の設定ミスも検出できます
## A03 📦 ソフトウェアのサプライチェーンの不備 (Software Supply Chain Failures)
> 依存パッケージ・ビルド・CI/CD から、脆弱性や悪意あるコードが入る
| 攻撃手法 | 何をされるか | 対策 |
|:--|:--|:--|
| 既知の脆弱性がある依存 | 公開された脆弱性を突かれる (例: 2021 年の Log4Shell) | 依存を更新し続け (Renovate)、脆弱性を検出する (Trivy) |
| 乗っ取られたパッケージ | 新しい版に悪意あるコードを入れられる | 公開から日がたった版だけを取り込む (例: Renovate の `minimumReleaseAge`。Renovate の待ちは Renovate の PR にだけ効くので、手で入れる版や間接の依存は、パッケージマネージャーの設定 (bun の `minimumReleaseAge` など) で待つ) |
| タイポスクワッティング・依存関係の混乱 | 似た名前や、社内と同じ名前の公開パッケージを入れさせる | 入れる前に名前を確かめ、lockfile で版を固定する |
| CI/CD の乗っ取り | 改ざんされた GitHub Actions に、secrets を盗まれる | Actions をコミットの SHA で固定し、ワークフローの権限を最小にする |
## A04 🔐 暗号の不備 (Cryptographic Failures)
> 暗号を使わない・弱い暗号を使うことで、秘密が読まれる・推測される
| 攻撃手法 | 何をされるか | 対策 |
|:--|:--|:--|
| 平文の通信の盗聴 | 通信の途中で、Cookie やパスワードを読まれる | HTTPS を必須にし、HSTS を付ける |
| パスワードのハッシュの総当たり | 漏れたハッシュから、パスワードを復元される | Argon2id か bcrypt を使う (MD5・SHA-256 をそのまま使わない) |
| 予測できる乱数 | セッション ID やトークンを推測される | Python は `secrets`、JS は `crypto.getRandomValues()`・`crypto.randomUUID()` を使う (`random`・`Math.random` は使わない) |
| 弱い暗号・自作の暗号 | 暗号文を解読される | 標準ライブラリの認証付き暗号 (AES-GCM など) を使い、自作しない |
| 秘密の書き込み | リポジトリやイメージから、鍵やパスワードが漏れる | Secret Manager に置き、コミット前に検出する (Gitleaks) |
## A05 💉 インジェクション (Injection)
> 利用者の入力が、SQL・HTML・コマンドの一部として解釈される
| 攻撃手法 | 何をされるか | 対策 |
|:--|:--|:--|
| SQL インジェクション | `' OR 1=1 --` を渡し、全件を読まれる・消される | SQLAlchemy の `select()` やバインドパラメータを使い、f-string で SQL を組み立てない |
| XSS (クロスサイトスクリプティング) | 投稿に `
```
⑤ で、ブラウザは次のリクエストを送ります。`Origin` はブラウザが付け、罠の JS からは書き換えられません。
```http
GET /me HTTP/1.1
Host: api.example
Origin: https://evil.example
Sec-Fetch-Site: cross-site
Cookie: session=abc123
```
⑥ で狙われる API の実装 (FastAPI の例)
```python
from fastapi.middleware.cors import CORSMiddleware
# 「どこから呼ばれても動くように」と、すべてのオリジンを許した
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
`*` と `allow_credentials=True` を組み合わせると、Starlette (FastAPI の CORS の実装) は `*` ではなく、届いた `Origin` をそのまま返します。⑥ の応答は次のとおりです。
```http
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: https://evil.example
Access-Control-Allow-Credentials: true
Vary: Origin
{"email": "user@example.com", "address": "..."}
```
ブラウザは、応答のヘッダーを見て、JS に渡すかを決めます。Cookie を付けた fetch では、次のようになります。
| 応答のヘッダー | 罠の JS に渡すか |
|:--|:--|
| `Access-Control-Allow-Origin` が無い | ❌ 渡さない (同一オリジンポリシーのまま) |
| `Access-Control-Allow-Origin: https://app.example` | ❌ 渡さない (オリジンが違う) |
| `Access-Control-Allow-Origin: *` | ❌ 渡さない (Cookie を付けた fetch には、`*` が効かない) |
| `Access-Control-Allow-Origin: https://evil.example` と `Access-Control-Allow-Credentials: true` | ✅ 渡す (⑥) |
`*` だけなら Cookie 付きの応答は読まれません。危ないのは、届いた `Origin` をそのまま返すことです。
許可リストを自分で確かめる書き方でも、確かめ方が甘いと、次のオリジンが通ります。
| 渡されるオリジン | 通ってしまう確かめ方 |
|:--|:--|
| `https://evil-example.com` | 正規表現 `https://.*example\.com` (`.*` が `evil-` に当たる) |
| `https://notexample.com` | 末尾だけを比べる (`origin.endswith("example.com")`) |
| `https://app.example.com.evil.net` | 先頭だけを比べる (`origin.startswith("https://app.example.com")`・`re.match`) |
| `https://xapp.example.com.evil.net` | 前後のどちらも固定しない (`re.search(r"app\.example\.com", origin)`・`"app.example.com" in origin`) |
| `null` | 許可リストに `null` を入れる。サンドボックスの iframe や、ファイルから開いたページの `Origin` は `null` になり、攻撃者も作れる |
| `http://app.example.com` | スキームを見ずに、ホストだけを比べる。HTTP の通信は途中で書き換えられ、JS を入れられる |
| `https://old.example.com` | サブドメインをまとめて許す。乗っ取られたサブドメインや、XSS のあるサブドメインからも読まれる |
## 💥 被害例
罠のページを開いただけで、利用者として API を読まれます。
| 狙われる API | 被害 |
|:--|:--|
| 個人情報 (`/me`・注文の履歴・メッセージ) | 個人情報を読まれ、外へ送られる |
| CSRF トークン・API キーを返す API | 読んだトークンで、CSRF の対策を破られる・API を利用者として呼ばれる (例: 2016 年に PortSwigger の調査で、届いた Origin をそのまま返すビットコインの取引所などが見つかった) |
| 社内ネットワークの API (IP で認証する) | 社員のブラウザを踏み台にして、外から届かない API を読まれる。Cookie が要らないので、`Access-Control-Allow-Origin: *` でも読まれる |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
| ケース | 対策 |
|:--|:--|
| ブラウザから API を呼ばない (BFF) | 🪪 CORS を設定しない |
| 決まった画面 (別のオリジン) から、Cookie 付きで呼ぶ | 📋 許可リスト・🚫 Origin をそのまま返さない |
| サブドメインをまとめて許す | 🔤 正規表現の前後と区切りを固定する |
| 誰でも読んでよい公開の API (認証なし) | `*` だけにして、`allow_credentials` を付けない |
| 画面と API が同じサイト (サブドメイン違い) | 🍪 SameSite=Lax の Cookie |
| どのケースでも | 📏 メソッドとヘッダーを絞る・🧭 CORS を CSRF の対策にしない |
[MUST] 📋 許可リスト / 読ませてよいオリジンを、完全一致で列挙する
```python
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
# 画面のオリジンを、スキーム・ホスト・ポートまで完全一致で列挙する
allow_origins=["https://app.example.com"],
allow_credentials=True,
# ... メソッドとヘッダーは 📏 で絞る
)
```
⑤ の `Origin: https://evil.example` は許可リストに無いので、`Access-Control-Allow-Origin` が付かず、ブラウザは罠の JS に応答を渡しません。
- ⚠️ 開発用のオリジン (`http://localhost:3000`) を、本番の許可リストに残さないでください。環境ごとに設定から読みます
- ⚠️ 許可リストは、読ませるかを決めるだけです。誰が呼んでいるかの確認 (認証・認可) の代わりにはなりません。`Origin` は、ブラウザ以外 (curl など) からは自由に送れます
[MUST] 🚫 Origin をそのまま返さない / * と credentials を組み合わせない・null を許さない
```python
# ... import (省く)
# ❌ 1. 届いた Origin を、確かめずにそのまま返す。どのオリジンも許したのと同じ
@app.middleware("http")
async def add_cors_headers(request: Request, call_next):
response = await call_next(request)
if (origin := request.headers.get("origin")) is not None:
response.headers["Access-Control-Allow-Origin"] = origin
response.headers["Access-Control-Allow-Credentials"] = "true"
return response
# ❌ 2. "*" と allow_credentials を組み合わせる。Starlette は、届いた Origin をそのまま返す (1 と同じになる)
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_credentials=True)
# ❌ 3. null を許す。サンドボックスの iframe から送ると Origin が null になるので、攻撃者も使える
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com", "null"], allow_credentials=True)
```
CORS のヘッダーは自分で書かず、`CORSMiddleware` に許可リスト (📋) を渡します。プリフライトの扱いや `Vary: Origin` も、ミドルウェアがまとめて行います。
- ⚠️ 誰でも読んでよい公開の API なら、`allow_origins=["*"]` だけにして、`allow_credentials` を付けません。ブラウザは Cookie を付けた fetch に `*` を効かせないので、Cookie 付きの応答は読まれません
- ⚠️ `Access-Control-Allow-Credentials: true` を付けるのは、Cookie 付きで呼ばれる必要があるときだけです
[MUST] 🔤 正規表現で許すなら、前後と区切りを固定する / evil-example.com や example.com.evil.net を通さない
```python
# ❌ .* が evil- に当たり、https://evil-example.com も通る
app.add_middleware(CORSMiddleware, allow_origin_regex=r"https://.*example\.com", allow_credentials=True)
# ✅ 区切りの . まで書く。サブドメインに使える文字だけを許す
app.add_middleware(CORSMiddleware, allow_origin_regex=r"https://[a-z0-9-]+\.example\.com", allow_credentials=True)
```
Starlette は `allow_origin_regex` を `fullmatch` で比べるので、前後は固定されます (`https://app.example.com.evil.net` は通らない)。
自分で正規表現を比べるときも、`fullmatch` を使います。
```python
import re
ALLOWED_ORIGIN = re.compile(r"https://[a-z0-9-]+\.example\.com")
def is_allowed_origin(origin: str) -> bool:
# re.match は末尾を、re.search は前後を固定しない。fullmatch は文字列全体と比べる
return ALLOWED_ORIGIN.fullmatch(origin) is not None
```
- ⚠️ この正規表現は `https://example.com` (サブドメインの無いオリジン) を通しません。要るなら `allow_origins` に足します
- ⚠️ サブドメインをまとめて許すと、乗っ取られたサブドメイン (消し忘れた DNS のレコードが、他人のサービスを指したまま) や、XSS のあるサブドメインからも読まれます。できれば 📋 で列挙します
[SHOULD] 📏 メソッドとヘッダーを絞る / 使わないものまで許さない
```python
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True,
# 画面が使うものだけを許す。"*" にしない
allow_methods=["GET", "POST", "PATCH", "DELETE"],
allow_headers=["Content-Type"],
# プリフライトの結果を、ブラウザが覚えておく秒数 (既定は 600)
max_age=600,
)
```
`allow_headers=["*"]` にすると、Starlette はプリフライトで求められたヘッダーを、すべてそのまま許して返します。
- ⚠️ CORS のヘッダーを自分で付けるときは、`Vary: Origin` も付けます。付けないと、CDN などのキャッシュが、あるオリジン向けの応答を、別のオリジンにも返します (`CORSMiddleware` は自動で付ける)
[SHOULD] 🍪 Cookie は SameSite=Lax にする / 別サイトの fetch に Cookie を付けさせない
```ts
// セッション Cookie を発行するときの属性 (Next.js の cookies().set などに渡す)
const attributes = {
httpOnly: true,
secure: true, // HTTPS でだけ送る
sameSite: "lax",
path: "/",
} as const;
```
`SameSite=Lax` の Cookie は、別サイトからの fetch に付きません。⑤ が Cookie 無しで届くので、CORS の設定を誤っても、利用者として読まれません (条件 1 が欠ける)。
- ⚠️ 「サイト」は登録可能なドメインの単位 (`example.com`) です。同じサイトのサブドメイン (`old.example.com`) からの fetch には、Lax の Cookie も付きます
- ⚠️ 画面と API が別のサイト (例: `app.example` から `api.example2`) にあると、Lax の Cookie は正規の画面の fetch にも付きません。その場合は `SameSite=None` が要り、MUST の対策 (📋・🚫) だけが守りになります
- ⚠️ ブラウザによっては、別サイトへの Cookie (サードパーティ Cookie) を既定で付けません。それに頼らず、Cookie に SameSite を明示します
[SHOULD] 🧭 CORS を CSRF の対策にしない / CORS は読ませるかを決めるだけで、送信は止めない
```html
```
フォームの送信や、プリフライトの要らない fetch は、CORS の許可が無くてもサーバーに届き、処理されます。状態を変える操作は、[CSRF の対策](../CSRF/README.md) (SameSite・`Origin` / `Sec-Fetch-Site` の確認) で守ります。
- ⚠️ 「CORS で許したオリジンからしか呼ばれない」と考えて、ほかの確認を省かないでください
[WANT] 🪪 (設計) ブラウザから API を直接呼ばない / 画面のサーバー (BFF) だけが API を呼び、CORS を要らなくする
```mermaid
flowchart LR
browser["🖥️ ブラウザ
app.example"] -->|"同じオリジン (Cookie)"| bff["⚛️ Next.js のサーバー
app.example"]
bff -->|"サーバーから (Authorization: Bearer)"| api["🚀 API
api.example"]
browser -.-x|"直接は呼ばない"| api
```
ブラウザは同じオリジンの Next.js のサーバーだけを呼び、API は Next.js のサーバーが呼びます。ブラウザから別のオリジンを読まないので、API に CORS の許可が要りません。
この形なら、API (FastAPI) に CORS の設定は要りません。ブラウザの CSP を `connect-src 'self'` にすると、別のオリジンへの fetch も止められます。
- ⚠️ 画面と API を別のオリジンに分け、ブラウザから直接呼ぶ形に変えるときは、MUST の対策を入れます
詳しくは [OWASP の HTML5 Security Cheat Sheet の Cross Origin Resource Sharing](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#cross-origin-resource-sharing) にまとまっています。
---
# 👿 CSRF (Cross-Site Request Forgery) 攻撃
> **ログイン中の利用者のブラウザに、攻撃者が作ったリクエストを正規サイトへ送らせる攻撃**

ブラウザは、どのサイトから出たリクエストにも、宛先のサイトの Cookie を自動で付けます。そのため正規サイトからは、利用者本人の操作と見分けがつきません。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

```mermaid
sequenceDiagram
autonumber
actor User as 🥸 利用者 (被害者)
participant Bank as 🏦 正規サイト
bank.example
participant Evil as 👿 罠サイト
evil.example
rect rgb(150, 150, 150)
Note over User,Bank: 1. ふだんどおりログインする
User->>+Bank: ログイン
Bank-->>-User: 🍪 セッション Cookie を発行
end
rect rgb(150, 150, 150)
Note over User,Evil: 2. 罠サイトを開かされる
User->>+Evil: メールや SNS のリンクから開く
Evil-->>-User: 見えないフォームと、それを自動で送信するスクリプトを返す
Note left of Evil: 送信先: https://bank.example/transfer (POST)
to=攻撃者の口座&amount=100000
end
rect rgb(150, 100, 100)
Note over User,Bank: 3. 偽造されたリクエストが届く
User->>+Bank: 送金してください (ブラウザが 🍪 Cookie を自動で付ける)
Note right of User: POST /transfer
Cookie: session=<🍪> ← 送り元 (evil.example) ではなく、宛先 (bank.example) の Cookie
to=攻撃者の口座&amount=100000
Bank->>Bank: 🍪 Cookie が正しい → 本人の操作とみなす
Bank-->>-User: 送金しました
end
```
- 攻撃者はレスポンスを読めません (同一オリジンポリシーで読めない)。それでも、送金・メールアドレスの変更・投稿・削除といった副作用は起きてしまいます
- 利用者は罠のページを開いただけで、何もクリックしていなくても被害に遭います
💻 コードで見る: ⑤ はどう送られるか
⑤ を送るのは攻撃者ではありません。④ で罠サイトが返した HTML を実行した、**利用者のブラウザ**が送ります。
④ で罠サイトが返す HTML
```html
```
⑤ でブラウザがしていること
1. `form.submit()` が呼ばれ、`https://bank.example/transfer` への POST を作る。HTML のフォームはどのサイトにでも送れる仕様で、同一オリジンポリシーは送信を止めない (止めるのはレスポンスを読むことだけ)
2. Cookie の保管庫から、**宛先 (bank.example) の Cookie** を探して付ける。どのページから送ったか (evil.example) では選ばない
3. フォームの送信は画面遷移で、CORS の対象外なので、プリフライト無しでそのまま送る
② で次の Cookie が発行されていると、⑤ では次のリクエストが届きます。
```http
Set-Cookie: session=abc123; Secure; HttpOnly; SameSite=None
```
```http
POST /transfer HTTP/1.1
Host: bank.example
Origin: https://evil.example
Sec-Fetch-Site: cross-site
Content-Type: application/x-www-form-urlencoded
Cookie: session=abc123
to=attacker-account&amount=100000
```
本物の送金 (bank.example の画面から送る) と比べると、違いはブラウザが付けるヘッダーだけで、主に `Origin` と `Sec-Fetch-Site` です。どちらも罠サイトの JS からは書き換えられません。
| ヘッダー | 本物の送金 | ⑤ の偽造リクエスト |
|:--|:--|:--|
| `Cookie` | `session=abc123` | `session=abc123` (同じ) |
| 本文 | `to=...&amount=...` | `to=...&amount=...` (同じ形) |
| `Origin` | `https://bank.example` | `https://evil.example` |
| `Sec-Fetch-Site` | `same-origin` | `cross-site` |
⑥ で狙われるサーバーの実装 (FastAPI の例)
```python
@app.post("/transfer")
def transfer(
to: Annotated[str, Form()],
amount: Annotated[int, Form()],
session: Annotated[str | None, Cookie()] = None,
):
user = sessions.get(session) # Cookie だけで利用者を特定している
if user is None:
raise HTTPException(status_code=401)
bank.transfer(from_account=user.account, to=to, amount=amount)
return {"result": "送金しました"}
```
Cookie と本文は本物と同じなので、Cookie しか見ないこのハンドラーは本人の送金として処理します。
- **HttpOnly では防げない**: 攻撃者は Cookie を読む必要がない。付けるのはブラウザ
- **攻撃者は Cookie の値を知らない**: `abc123` を知らないまま、Cookie 付きのリクエストを送らせられる
- **SameSite=Lax なら ⑤ で止まる**: 別サイトからの POST には Cookie が付かず、`session` が `None` になって 401 で終わる
- **画面に気づかれないようにする**: フォームを送るとページが bank.example の応答に変わるため、見えない iframe の中で送らせることもある。`fetch()` に `credentials: "include"` を付けても、同じように Cookie 付きで送れる (レスポンスは読めない)
## 💥 被害例
状態を変える操作なら、何でも本人になりすまして実行されます。
| 狙われる操作 | 被害 |
|:--|:--|
| 送金・購入 | お金を奪われる |
| メールアドレスの変更 | パスワードリセットのメールが攻撃者に届き、アカウントを乗っ取られる |
| 投稿・書き込み | 本人の名前で投稿される (犯行予告など) |
| 削除・設定の変更 | データを消される、公開範囲を広げられる |
| ログイン (ログイン CSRF) | 入力したカード情報や履歴が、攻撃者のアカウントに残る |
## 🛡️ 対策
**SameSite=Lax を明示し、Origin (または Sec-Fetch-Site) で確かめ、GET で状態を変えない**、という多層の組み合わせが基本です。
MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
[MUST] 🍪 SameSite Cookie / 別サイトからのリクエストに Cookie を付けさせない
```ts
import { cookies } from "next/headers";
// ログインしたとき (Server Action・Route Handler の中) に発行する
(await cookies()).set("session", sessionId, {
httpOnly: true,
secure: true,
sameSite: "lax",
});
```
SameSite の値ごとに、別サイトから来たリクエストに Cookie を付けるかが変わります。
| SameSite | 別サイトのリンクから開く (画面遷移の GET) | 別サイトからのフォーム POST・img・fetch |
|:--|:--|:--|
| Strict | 送らない (リンクから来るとログアウト状態に見える) | 送らない |
| Lax | 送る | 送らない |
| None (Secure が必須) | 送る | 送る |
- ⚠️ 「サイト」は登録可能なドメインの単位 (`example.com`) で決まり、サブドメインは同じサイト扱いになります。`evil.example.com` から `app.example.com` への攻撃は防げません
[MUST] 🧭 Origin / Sec-Fetch-Site の確認 / ブラウザが付ける送り元のヘッダーを見て、別サイトからなら拒否する
```python
# 自サイトのオリジン。画面を同じサイトのサブドメイン (app.bank.example など) に置くなら、画面のオリジンも入れる (fetch で呼ぶなら CORS でも許可する)
ALLOWED_ORIGINS = {"https://bank.example"}
# FastAPI には CSRF を確かめる仕組みが無いので、ミドルウェアで書く
@app.middleware("http")
async def reject_cross_site_requests(request: Request, call_next):
# GET などは確かめないので、GET で状態を変えないことが前提
if request.method not in {"GET", "HEAD", "OPTIONS"}:
site = request.headers.get("sec-fetch-site")
origin = request.headers.get("origin")
if site is not None:
# ALLOWED_ORIGINS に無い same-site (サブドメイン) も拒否するので、SameSite で防げない攻撃も止まる
allowed = site in {"same-origin", "none"} or origin in ALLOWED_ORIGINS
else:
# Sec-Fetch-Site を送らない古いブラウザは Origin で見る。どちらも無いのはブラウザ以外か、どちらも送らない古いブラウザ (通してしまうので、守るなら CSRF トークンを足す)
allowed = origin is None or origin in ALLOWED_ORIGINS
if not allowed:
return Response(status_code=403)
return await call_next(request)
```
⑤ は `Sec-Fetch-Site: cross-site` なので 403 になります。どちらのヘッダーも、罠サイトの JS からは書き換えられません。
Next.js の Server Action は、Next.js が `Origin` と `Host` (`X-Forwarded-Host`) を比べて、違えば拒否します (`Origin` が無ければ通す)。Route Handler (`route.ts`) の POST などは確かめないので、同じ判定を自分で書きます。
[MUST] 🚫 GET で状態を変えない / 他の対策の前提
```python
# ❌ 罠サイトの location.href = "https://bank.example/transfer?to=attacker-account&amount=100000" で送金される
@app.get("/transfer")
def transfer(to: str, amount: int, session: Annotated[str | None, Cookie()] = None): ...
# ✅
@app.post("/transfer")
def transfer(...): ...
```
- ⚠️ 画面遷移 (GET) には SameSite=Lax でも Cookie が付き、Origin / Sec-Fetch-Site の確認も GET を見ません
[SHOULD] 📦 JSON や独自ヘッダーを必須にする / 別サイトのフォームからは送れず、fetch ではプリフライトになって CORS で止まる
```python
class TransferJson(BaseModel):
to: str
amount: int
# 独自ヘッダーも必須にするなら、付いていないリクエストを拒否する (画面の fetch で X-Requested-With を付ける)
def require_custom_header(x_requested_with: Annotated[str | None, Header()] = None):
if x_requested_with is None:
raise HTTPException(status_code=403)
# 本文は JSON のモデルで受ける。独自ヘッダーを使わないなら dependencies を外す
@app.post("/transfer", dependencies=[Depends(require_custom_header)])
def transfer(body: TransferJson, session: Annotated[str | None, Cookie()] = None): ...
```
⑤ のフォームは `X-Requested-With` が無いので 403 になります。`dependencies` を外しても、FastAPI は `application/json` 以外の本文を JSON として読まないので 422 になります。
fetch から呼ぶ API に使います。HTML のフォーム (Server Action など) は JSON を送れないので、当てはまりません。
- ⚠️ `FastAPI(strict_content_type=False)` にしないでください。`Content-Type` の無い本文 (プリフライト無しで送れる) も JSON として読むようになり、破られます
- ⚠️ CORS を緩く設定すると破られます。次のように書くと、Starlette は届いた `Origin` をそのまま許可して返します
```python
# ❌ どのサイトからも Cookie 付きで送らせ、応答も読ませてしまう
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
[SHOULD] 🔑 重要な操作で再認証する / パスワードの再入力や確認画面を挟む
```python
@app.post("/email")
def change_email(
new_email: Annotated[str, Form()],
password: Annotated[str, Form()],
session: Annotated[str | None, Cookie()] = None,
):
user = sessions.get(session)
if user is None:
raise HTTPException(status_code=401)
if not users.verify_password(user, password):
raise HTTPException(status_code=403)
users.change_email(user, new_email)
```
攻撃者はパスワードを知らないので、罠のフォームに入れられません。IdP (Google など) でログインするなら、IdP でログインし直してもらいます。
- ⚠️ 使い勝手とのトレードオフです。メールアドレスの変更・送金など、乗っ取りや被害につながる操作に絞ります
[WANT] 🎲 CSRF トークン / 攻撃者が知りえないランダムな値をフォームに埋めておき、送信時に照合する
```ts
import { randomBytes } from "node:crypto";
// ログインしたとき: ログインのたびに作り直し、セッションに保存する
await sessions.set(sessionId, { user, csrfToken: randomBytes(32).toString("base64url") });
```
```tsx
// app/transfer/page.tsx: 送金の画面のフォームに埋める
import { redirect } from "next/navigation";
export default async function TransferPage() {
const session = await getSession();
if (!session) redirect("/login");
return (
);
}
```
```ts
// app/api/transfer/route.ts: 送信されたトークンを、セッションの値と比べる
import { timingSafeEqual } from "node:crypto";
import { type NextRequest, NextResponse } from "next/server";
export async function POST(request: NextRequest) {
const session = await getSession();
if (!session) {
return new NextResponse(null, { status: 401 });
}
const formData = await request.formData();
const token = formData.get("csrf_token");
if (typeof token !== "string" || !isSameToken(token, session.csrfToken)) {
return new NextResponse(null, { status: 403 });
}
// ... 送金する
}
// === はかかる時間の差から値を当てられるので、時間が一定の比較を使う。timingSafeEqual は長さが違うと例外を投げるので、先に比べる
function isSameToken(sent: string, expected: string): boolean {
const a = Buffer.from(sent);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}
```
攻撃者はトークンを知らないので、罠のフォームに入れられません。
Origin / Sec-Fetch-Site の確認は、どちらのヘッダーも送らない古いブラウザを通してしまいます。そうしたブラウザまで守るときに足します。
- ⚠️ XSS があると、画面からトークンを読まれて破られます
[WANT] 🪪 (設計) Cookie で認証しない / Authorization: Bearer は自動で付かないので、CSRF が成立しない
```python
@app.post("/transfer")
def transfer(
body: TransferJson,
credentials: Annotated[HTTPAuthorizationCredentials, Depends(HTTPBearer())],
):
user = users.verify_token(credentials.credentials)
...
```
ブラウザは `Authorization` を自動で付けないので、罠サイトからは送れません (無ければ `HTTPBearer` が 401 を返す)。
BFF の形 (ブラウザは Next.js のサーバーだけを Cookie で呼び、API は Next.js のサーバーが Bearer で呼ぶ) なら、API はこの形にし、ブラウザの Cookie を受ける Next.js の側で上の対策をします。
- ⚠️ トークンを `localStorage` など JS から読める場所に置くと、XSS で盗まれます
詳しくは [OWASP の CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) にまとまっています。
---
# 🔓 IDOR (Insecure Direct Object Reference)
> **リクエストの ID を書き換えるだけで、他人のデータを読み書きできてしまう脆弱性**

ログインの確認 (認証) は「誰か」を確かめるだけです。アクセス制御 (認可) は「その人が、そのデータや操作に触ってよいか」を確かめます。認可が抜けていると、攻撃者は正規の利用者のまま、ID を書き換えるだけで他人のデータに届きます。
OWASP Top 10:2025 の 1 位 (A01 アクセス制御の不備) に入る攻撃です。同じ A01 の [権限昇格](../PrivilegeEscalation/README.md)・[パストラバーサル](../PathTraversal/README.md)・[CORS の設定ミス](../CORS/README.md)・[CSRF](../CSRF/README.md)・[SSRF](../SSRF/README.md) は、それぞれの資料にまとめています。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

2 は、ID を推測しにくくしても防ぎ切れません。ID は共有リンク・画面・ログ・ほかの API の応答から漏れます。確実に欠けさせられるのは 3 です。
```mermaid
sequenceDiagram
autonumber
actor Attacker as 👿 攻撃者
A 社の利用者
participant App as 🚀 正規サーバー
api.example
participant DB as 🐘 DB
請求書のテーブル
rect rgb(150, 150, 150)
Note over Attacker,App: ふだんは、自分の請求書を /invoices/123 で開く
end
rect rgb(150, 100, 100)
Note over Attacker,App: ID を書き換えて送る
Attacker->>+App: GET /invoices/124
Note right of Attacker: Authorization: Bearer 🔑 (A のトークン)
トークンは本物なので、ログインの確認は通る
App->>+DB: SELECT * FROM invoices WHERE id = 124
Note right of App: 持ち主 (会社) の条件が無い
DB-->>-App: B 社の請求書
App-->>-Attacker: 200 OK (B 社の請求書: 金額・請求先・振込先)
end
rect rgb(150, 100, 100)
Note over Attacker,App: 連番で、全社の請求書を集める
loop id = 1, 2, 3, ...
Attacker->>App: GET /invoices/{id}
App-->>Attacker: 他社の請求書
end
end
```
- トークンは本物なので、ログインの確認 (認証) は通ります。止められるのは、「この請求書に触ってよいか」の確認 (認可) だけです
- 読むだけでなく、書き込みにも起きます。`PATCH /invoices/124`・`DELETE /invoices/124` で、他社の請求書を書き換えられる・消されます
- 一般の利用者が、管理者だけの API を呼ぶのは、別の攻撃の権限昇格です ([権限昇格の資料](../PrivilegeEscalation/README.md))
- 一覧・検索・件数・エクスポートでも漏れます。詳細の API だけ直しても、`GET /invoices?q=...` や CSV の出力に他社の行が混ざります
- ID を UUID にしても防げません。共有リンク・ログ・通知・ほかの API の応答から ID が漏れれば、同じように届きます
💻 コードで見る: ① の ID はどう通ってしまうか
② で狙われるサーバーの実装 (FastAPI の例)
```python
# ... import と、User・current_user・get_session・Invoice・InvoiceJson の定義 (省く)
@app.get("/invoices/{invoice_id}")
def get_invoice(
invoice_id: int,
user: Annotated[User, Depends(current_user)], # ログインしているかは確かめる (認証)
session: Annotated[Session, Depends(get_session)],
) -> InvoiceJson:
invoice = session.get(Invoice, invoice_id) # ID だけで取り、持ち主を確かめない (認可が無い)
if invoice is None:
raise HTTPException(status_code=404)
return InvoiceJson.model_validate(invoice, from_attributes=True)
```
① で次のリクエストが届くと、② で ID が 124 の請求書を、どの会社のものかを見ずに取ります。
```http
GET /invoices/124 HTTP/1.1
Host: api.example
Authorization: Bearer
```
`current_user` はトークンが本物かを確かめ、A 社の利用者を返します。`user` を受け取っていても、使わなければ認可にはなりません。
ID を書き換える場所は、URL のパスだけではありません。
| 場所 | 例 |
|:--|:--|
| URL のパス | `GET /invoices/124` |
| クエリ | `GET /invoices/export?customer_id=88` で、他社の顧客の請求書を CSV で出す |
| 本文 | `POST /comments` に `{"post_id": 124}` を送り、他社の投稿にコメントする |
| ヘッダー | `X-Tenant-Id: b-corp` を送り、ヘッダーのテナントを信じるサーバーに他社として扱わせる |
## 💥 被害例
認可が抜けた API は、ID を書き換えるだけで、他人のデータを読み書きさせます。
| 狙われる場所 | 被害 |
|:--|:--|
| 詳細・取得の API | 連番で全件を集められる (例: 2019 年の First American Financial。URL の連番を変えるだけで、口座番号などを含む不動産取引の書類、約 8 億 8,500 万件を読めた) |
| 更新・削除の API | 他人のデータを書き換えられる・消される |
| 一覧・検索・エクスポート | 他のテナントの行が混ざり、まとめて漏れる |
| ファイル・添付のダウンロード | 他社の契約書や請求書の PDF を落とされる |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
| ケース | 対策 |
|:--|:--|
| ID でデータを取る・変える・消す | 🔎 持ち主・テナントで絞る |
| 一覧・検索・件数・エクスポート | 🔎 持ち主・テナントで絞る |
| どのケースでも | 🧪 認可のテスト |
| ID が漏れにくくしたい | 🎲 推測しにくい ID |
| アプリの絞り忘れも止めたい (設計) | 🛡️ DB でも絞る |
[MUST] 🔎 持ち主・テナントで絞る / ID だけで取らず、取るクエリの条件に持ち主を入れる
```python
from sqlalchemy import select
# ... ほかの import と定義 (省く)
@app.get("/invoices/{invoice_id}")
def get_invoice(
invoice_id: int,
user: Annotated[User, Depends(current_user)],
session: Annotated[Session, Depends(get_session)],
) -> InvoiceJson:
# テナントの条件を、取るクエリそのものに入れる。取ってから比べる形だと、比べ忘れた API から漏れる
invoice = session.scalar(
select(Invoice).where(Invoice.id == invoice_id, Invoice.tenant_id == user.tenant_id)
)
# 他社の請求書も、無い請求書と同じ 404 にする。403 にすると、その ID の請求書があることを教えてしまう
if invoice is None:
raise HTTPException(status_code=404)
return InvoiceJson.model_validate(invoice, from_attributes=True)
```
① は、B 社の請求書が条件に合わないので 404 になります。
`user.tenant_id` は、確かめたトークン (またはサーバーのセッション) から取ります。URL・本文・クエリ・ヘッダーで送られた `tenant_id` は書き換えられます。
- ⚠️ 一覧・検索・件数・エクスポートも、同じ条件で絞ります
- ⚠️ 更新・削除も `WHERE id = :id AND tenant_id = :tenant_id` で絞り、当たった行が 0 件なら 404 にします
- ⚠️ 子のリソース (`/invoices/123/items/9`) は、親が自分のものかに加えて、子がその親に属するか (`InvoiceItem.invoice_id == 123`) も確かめます
- ⚠️ URL にテナントを入れる設計 (`/{tenant_id}/projects/...`) なら、そのテナントに所属しているかを入口で確かめます。所属していなければ 404 (テナントがあることを伏せる)、所属していて権限が無ければ 403 を返します
[SHOULD] 🧪 認可のテスト / 他社の ID で拒否されることを、テストで確かめる
```python
# ... import と、fixture (client・login_as)・テストデータを作る関数 (create_invoice) の定義 (省く)
def test_他社の請求書は404(client: TestClient, login_as: LoginAs) -> None:
invoice_id = create_invoice(tenant="b-corp")
response = client.get(f"/invoices/{invoice_id}", headers=login_as("a-corp", Role.MEMBER))
assert response.status_code == 404
def test_他社の請求書は消せない(client: TestClient, login_as: LoginAs) -> None:
invoice_id = create_invoice(tenant="b-corp")
response = client.delete(f"/invoices/{invoice_id}", headers=login_as("a-corp", Role.MEMBER))
assert response.status_code == 404
# 404 を返しても消していないかを、B 社として確かめる
assert client.get(f"/invoices/{invoice_id}", headers=login_as("b-corp", Role.MEMBER)).status_code == 200
```
認可の穴は、自分のデータを操作するふだんのテストでは見つかりません。他社の ID で拒否される側もテストします。ロールごとに許す操作のテストは、[権限昇格の資料](../PrivilegeEscalation/README.md) にあります。
- ⚠️ 他社の ID は、詳細・更新・削除・一覧のすべての API で試します
[WANT] 🎲 推測しにくい ID / UUID は 🔎 の補助にすぎない
```python
import uuid
from sqlalchemy.orm import Mapped, mapped_column
class Invoice(Base):
__tablename__ = "invoices"
# 連番の代わりに、推測できない ID にする
id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
```
連番を順に試す攻撃 (⑤ の連番集め) を防ぎます。連番だと、件数 (売上や利用者の数) も外から分かります。
- ⚠️ ID は共有リンク・ログ・通知・ほかの API の応答から漏れます。🔎 の代わりにはなりません
- ⚠️ `uuid.uuid7` (Python 3.14) は、作った時刻が ID から分かります
[WANT] 🛡️ (設計) DB でも絞る / PostgreSQL の Row Level Security で、他社の行を返さない
```sql
-- マイグレーション: 入れたテナントの行だけを見せる
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON invoices
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
```python
# リクエストのトランザクションの始めに、トークンから取ったテナントを入れる。
# 第 3 引数の true で、トランザクションが終わると消える (接続プールで、次のリクエストに残らない)
session.execute(
text("SELECT set_config('app.tenant_id', :tenant_id, true)"),
{"tenant_id": str(user.tenant_id)},
)
```
アプリが 🔎 の条件を書き忘れても、DB が他社の行を返しません。テナントを入れ忘れると、クエリがエラーになり、行は返りません (未設定なら `current_setting` が、接続を使い回して空文字 (`''`) が残っていれば `::uuid` の変換がエラーになる)。
USING だけを書くと、INSERT・UPDATE の新しい行にも同じ条件が効きます (他社の `tenant_id` では書き込めない)。
テーブルの所有者 (マイグレーションを流すロール) と、アプリが繋ぐロールを分け、どちらにも BYPASSRLS を付けないと、アプリの接続にポリシーが効きます。
- ⚠️ テーブルの所有者 (`FORCE ROW LEVEL SECURITY` が無いとき)・スーパーユーザー・BYPASSRLS のロールには効きません
- ⚠️ `set_config(..., true)` は、トランザクションが終わると消えます。リクエストの途中で `commit` すると、その後のクエリはテナントが空になってエラーになります。トランザクションが始まるたびに入れ直します (SQLAlchemy の `after_begin` イベントなど)
- ⚠️ テナントの中の持ち主 (利用者ごと) やロールの確認は、アプリで行います。🔎 と、ロールの確認 ([権限昇格の資料](../PrivilegeEscalation/README.md)) の代わりではありません
詳しくは [OWASP の IDOR Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html) と [Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) にまとまっています。
---
# 📁 パストラバーサル (Path Traversal) 攻撃
> **ファイル名に `../` を入れて、サーバーに置き場の外のファイルを読ませる (書かせる) 攻撃**

ファイル名を受け取って、置き場 (例: `/srv/uploads`) のファイルを返す機能があります。名前をそのまま置き場のパスにつなぐと、`..` (1 つ上のディレクトリ) をたどって、置き場の外の設定ファイル・秘密鍵・ソースコードまで届きます。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

```mermaid
sequenceDiagram
autonumber
actor Attacker as 👿 攻撃者
ふつうの利用者
participant App as 🚀 正規サーバー
api.example
participant FS as 📁 サーバーのファイル
/srv/uploads・/app
rect rgb(150, 150, 150)
Note over Attacker,FS: ふだんは /files?name=report.pdf で、置き場の /srv/uploads/report.pdf を取る
end
rect rgb(150, 100, 100)
Note over Attacker,App: ファイル名に ../ を入れて送る
Attacker->>+App: GET /files?name=../../app/.env
App->>+FS: /srv/uploads/../../app/.env を開く
Note right of App: .. を 2 回たどり、置き場の外の /app/.env になる
FS-->>-App: .env の中身 (DB のパスワード・API キー)
App-->>-Attacker: 200 OK (ファイルの中身)
end
rect rgb(150, 100, 100)
Note over Attacker,App: ほかのファイルも、名前を変えて読む
loop name = ../../etc/passwd, ../../app/src/settings.py, ...
Attacker->>App: GET /files?name=...
App-->>Attacker: 置き場の外のファイル
end
end
```
- 攻撃者は、ダウンロードというふつうの機能を使うだけです。ログインの確認は通ります
- 置き場からどれだけ深いかを知らなくても届きます。`/` より上には行けないので、`../` を多めに並べれば (`../../../../../app/.env`) 必ず `/` に着きます
- 読むだけでなく、書き込みにも起きます。アップロードや ZIP の展開で名前を `../../app/main.py` にされると、置き場の外のファイルを上書きされます
💻 コードで見る: ① の名前はどう開かれるか
② で狙われるサーバーの実装 (FastAPI の例)
```python
from pathlib import Path
from fastapi.responses import FileResponse
# ... ほかの import と、User・current_user の定義 (省く)
UPLOAD_DIR = Path("/srv/uploads")
@app.get("/files")
def download(name: str, user: Annotated[User, Depends(current_user)]) -> FileResponse:
# 利用者が渡した名前を、そのまま置き場のパスにつなぐ
return FileResponse(UPLOAD_DIR / name)
```
① で次のリクエストが届くと、② で `/srv/uploads/../../app/.env` を開きます。
```http
GET /files?name=../../app/.env HTTP/1.1
Host: api.example
Authorization: Bearer <攻撃者のトークン>
```
OS は `..` を 1 つ上のディレクトリとしてたどるので、`/srv/uploads` → `/srv` → `/` → `/app/.env` になります。
`../` を文字列で弾いても、同じ名前を別の書き方で渡されます (FastAPI 0.162・uvicorn で確かめた結果)。
| 渡される値 | アプリが受け取る名前・開くパス |
|:--|:--|
| `?name=..%2f..%2fapp%2f.env` | `../../app/.env` (クエリはデコードされて届く) |
| `?name=%2e%2e%2f%2e%2e%2fapp%2f.env` | `../../app/.env` (`.` も `%2e` で書ける) |
| `?name=/app/.env` | `/app/.env`。pathlib の `/` は、右が絶対パスだと左 (置き場) を捨てる |
| `?name=....//....//app/.env` | `"../"` を消す自作の確認 (`replace("../", "")`) の後で、`../../app/.env` になる |
| `?name=..%252f..%252fapp%252f.env` | `..%2f..%2fapp%2f.env`。アプリがもう一度デコード (`unquote`) すると `../../app/.env` |
| `/files/{name:path}` に `/files/..%2f..%2fapp%2f.env` | `../../app/.env` (パスの `%2f` も `/` にデコードされる) |
| `..\..\app\.env` | Windows のサーバーなら、`\` も区切りになる |
- URL のパスに `../` をそのまま書くと、ブラウザや多くのクライアントは送る前に消します。攻撃者は `curl --path-as-is` などでそのまま送ります (uvicorn は消さずにアプリへ渡します)
- `:path` の付かない `/files/{name}` は、`/` を含む値 (`%2f` も) に一致せず 404 になります。それでも `/files/%2e%2e` のように `..` 1 つは届きます
- Python では、`\x00` の入ったパスは `ValueError` になります。ほかの言語のように、後ろに付けた拡張子 (`.pdf`) を `\x00` で切り捨てる手口は効きません。ただし例外を捕まえないと 500 になります
## 💥 被害例
サーバーのプロセスが読めるファイルは、すべて狙われます。
| 狙われるファイル | 被害 |
|:--|:--|
| 設定ファイル・`.env` | DB のパスワードや API キーを読まれ、DB や外部サービスに入られる |
| 環境変数 (`/proc/self/environ`) | コンテナに渡した秘密 (DB の URL・API キー) を読まれる |
| クラウドの鍵 (サービスアカウントの鍵の JSON など) | クラウドの API を、サーバーの権限で呼ばれる |
| ソースコード | ほかの脆弱性や、書き込まれた秘密を探される |
| ほかの利用者のファイル | 置き場の別の場所 (他人・他社のディレクトリ) を読まれる |
| 書き込み (アップロード・ZIP の展開) | コードや設定を上書きされ、任意のコードを実行される |
| Web サーバーの文書の外 | 例: 2021 年の Apache HTTP Server 2.4.49 (CVE-2021-41773)。`.%2e/` で文書のディレクトリの外を読め、CGI が有効だとコードも実行された |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
| ケース | 対策 |
|:--|:--|
| 利用者のファイルを保存する・返す | 🪪 ID で引き、置き場の名前はサーバーが決める |
| 決まったファイルから選ばせる (テンプレート・帳票の種類など) | 🪪 名前ではなくキーで受け、サーバーの表で引く |
| どうしても名前・パスを受け取る | 🧭 正規化してから、置き場の中かを確かめる |
| ZIP・tar を展開する | 📦 展開する前に、置き場の外に出ないかを確かめる |
| どのケースでも | 🔒 プロセスの権限を絞る・🪣 ファイルをアプリのディスクに置かない |
[MUST] 🪪 ID で引く / 置き場の名前はサーバーが決め、利用者の名前をパスに使わない
```python
import uuid
from pathlib import Path
from fastapi import HTTPException, UploadFile
from fastapi.responses import FileResponse
from sqlalchemy import select
# ... ほかの import と、User・current_user・get_session・StoredFile の定義 (省く)
UPLOAD_DIR = Path("/srv/uploads")
@app.post("/files")
def upload(
file: UploadFile,
user: Annotated[User, Depends(current_user)],
session: Annotated[Session, Depends(get_session)],
) -> dict[str, int]:
# 置き場の名前は、サーバーが作る (推測できず、../ も / も入らない)
storage_key = uuid.uuid4().hex
(UPLOAD_DIR / storage_key).write_bytes(file.file.read()) # ... 大きさの上限 (省く)
# 利用者が付けた名前は、DB に残すだけ
stored = StoredFile(tenant_id=user.tenant_id, storage_key=storage_key, name=file.filename or "file")
session.add(stored)
session.commit()
return {"id": stored.id}
@app.get("/files/{file_id}")
def download(
file_id: int,
user: Annotated[User, Depends(current_user)],
session: Annotated[Session, Depends(get_session)],
) -> FileResponse:
# 持ち主で絞って取る (IDOR の対策)
stored = session.scalar(
select(StoredFile).where(StoredFile.id == file_id, StoredFile.tenant_id == user.tenant_id)
)
if stored is None:
raise HTTPException(status_code=404)
# 利用者が付けた名前は、ダウンロードするときのファイル名に使うだけで、パスには使わない
return FileResponse(UPLOAD_DIR / stored.storage_key, filename=stored.name)
```
① は、名前 (`name`) を受け取らないので起きません。ID が他社のファイルなら 404 です ([IDOR の資料](../IDOR/README.md))。
決まったファイルから選ばせるときも、名前ではなくキーで受け、サーバーの表で引きます。
```python
from enum import StrEnum
TEMPLATE_DIR = Path("/app/templates")
class Report(StrEnum):
INVOICE = "invoice"
RECEIPT = "receipt"
# キーと実際のファイルの対応は、サーバーが持つ
TEMPLATES = {Report.INVOICE: "invoice.html", Report.RECEIPT: "receipt.html"}
@app.get("/reports/{report}")
def report(report: Report) -> FileResponse:
# Report に無い値は、FastAPI が 422 で弾く
return FileResponse(TEMPLATE_DIR / TEMPLATES[report])
```
- ⚠️ 利用者が付けた名前を、`Content-Disposition` 以外 (パス・オブジェクトの名前・コマンドの引数) に使わないでください
- ⚠️ 拡張子を確かめても防げません。`name.endswith(".pdf")` は `../../secret.pdf` を通します
[MUST] 🧭 正規化してから、置き場の中かを確かめる / 名前を受け取るしかないとき
```python
from pathlib import Path
from fastapi import HTTPException
from fastapi.responses import FileResponse
# ... ほかの import と、User・current_user の定義 (省く)
# 置き場も、先に正規化しておく (シンボリックリンクを解いた実際のパスと比べるため)
UPLOAD_DIR = Path("/srv/uploads").resolve()
def resolve_inside(base: Path, name: str) -> Path | None:
"""name を base につなぎ、base の中のファイルなら、その実際のパスを返す"""
try:
# .. とシンボリックリンクを解き、OS が実際に開くパスにする。右が絶対パスでも、ここで外に出たと分かる
path = (base / name).resolve()
except ValueError:
# \x00 の入った名前は、resolve が ValueError を投げる
return None
# 置き場の中で、しかもファイルであること。"" や "." は置き場そのもの (ディレクトリ) になる
if not path.is_relative_to(base) or not path.is_file():
return None
return path
@app.get("/files")
def download(name: str, user: Annotated[User, Depends(current_user)]) -> FileResponse:
path = resolve_inside(UPLOAD_DIR, name)
if path is None:
raise HTTPException(status_code=404)
return FileResponse(path)
```
① の `../../app/.env` は `/app/.env` に解けて、置き場の中ではないので 404 になります。上の表の書き方も、デコードされた後の名前を正規化して比べるので弾かれます。
- ⚠️ 文字列の先頭で比べないでください。`str(path).startswith("/srv/uploads")` は `/srv/uploads-old/...` を通します。`is_relative_to` はパスの区切りごとに比べます
- ⚠️ `..` を文字列で消すやり方 (`name.replace("../", "")`) は、`....//` で破られます (消した後に `../` が残る)
- ⚠️ 正規化した後で、もう一度デコード (`unquote`) しないでください。確かめたものと違うパスを開きます
- ⚠️ FastAPI (Starlette) の `StaticFiles` は、絶対パスを拒否し、`realpath` で解いて置き場の外なら 404 にします。静的ファイルを配るだけなら、自分で書かずにこれを使います
- ⚠️ この確認は「置き場の中か」までです。置き場の中の、他人のファイルを開かれるのは防げません。持ち主の確認には 🪪 の形が要ります
- ⚠️ 確かめた後で `FileResponse` がパスを開き直すまでの間に、置き場に書き込める者が途中のディレクトリや最後の要素をシンボリックリンクに差し替えると、確かめていないパスを開かれます (TOCTOU)。利用者が置き場に書き込めるなら、🪪 の形にします
[SHOULD] 📦 アーカイブを安全に展開する / ZIP・tar の中の名前で、置き場の外に書かせない (Zip Slip)
ZIP や tar の中のファイル名も、攻撃者が決められます。`../../app/main.py` という名前を入れたアーカイブを展開させると、置き場の外のファイルを上書きされます。
```python
import tarfile
import zipfile
from pathlib import Path
def extract(archive: Path, dest: Path) -> None:
if zipfile.is_zipfile(archive):
with zipfile.ZipFile(archive) as zf:
# extractall は、名前の .. と先頭の / を取り除き、dest の中に展開する
zf.extractall(dest)
else:
with tarfile.open(archive) as tf:
# filter="data": dest の外に出る名前・外や絶対パスを指すリンク・デバイスファイルを拒否し、先頭の / を取り除く
# Python 3.14 は既定で "data" だが、意図を残すために書く
tf.extractall(dest, filter="data")
# ... 展開する前の、合計の大きさとファイル数の上限 (ZIP 爆弾の対策。パストラバーサル以外なので省く)
```
```python
# ❌ 中の名前を自分でつなぐと、../../evil.txt は dest の外に書かれる
with zipfile.ZipFile(archive) as zf:
for name in zf.namelist():
(dest / name).write_bytes(zf.read(name))
```
- ⚠️ 名前を自分でつなぐ必要があるときは、🧭 の `resolve_inside` と同じく、`(dest / name).resolve()` が `dest` の中にあり `dest` そのものではないことを確かめてから書きます (書き込みなので `is_file()` は外します。親ディレクトリだけを見ると、最後の要素がシンボリックリンクのときに外へ書かれます)
- ⚠️ tar の `filter` は Python 3.12 で入りました (3.8〜3.11 にも、2023 年のセキュリティ更新で入っています)。`filter` の無い古い Python や、ほかの言語・ライブラリで展開するときは、同じ確認を自分で書きます
[SHOULD] 🔒 プロセスの権限を絞る / 外に出られても、読めるもの・書けるものを減らす
```dockerfile
# root で動かさない。読めるのは、appuser に許したファイルだけになる
RUN useradd --system --no-create-home appuser
USER appuser
```
- ⚠️ root でなくても、アプリ自身のソースコードや環境変数 (`/proc/self/environ`) は読めます。秘密はファイルや環境変数に平文で置かず、Secret Manager から必要なときに取ると、読まれる量を減らせます
- ⚠️ 書き込める場所は、置き場だけにします。ソースコードや設定のディレクトリを、アプリの利用者が書き込めないようにします
- ⚠️ MUST の対策の代わりにはなりません。被害を小さくするための二段目です
[WANT] 🪣 (設計) ファイルをアプリのディスクに置かない / Cloud Storage に置き、署名付き URL で配る
```python
import os
from datetime import timedelta
import google.auth
from google.auth.transport.requests import Request
from google.cloud import storage
# ... ほかの import と、User・current_user・get_session・StoredFile の定義 (省く)
# バケット・署名する SA・URL の宛先は、環境ごとの設定 (環境変数) から渡す
bucket = storage.Client().bucket(os.environ["UPLOAD_BUCKET"])
SIGNER = os.environ["SIGNER_SERVICE_ACCOUNT"]
# ローカルのエミュレーターでは、ブラウザから届く宛先を渡す。本番では設定せず、storage.googleapis.com にする
ENDPOINT = os.environ.get("SIGNED_URL_ENDPOINT", "https://storage.googleapis.com")
def signed_download_url(storage_key: str) -> str:
# Cloud Run の既定の認証情報には秘密鍵が無いので、IAM の signBlob で SIGNER として署名する (トークンを渡す)
credentials, _ = google.auth.default()
credentials.refresh(Request()) # ... トークンの使い回し (省く)
return bucket.blob(storage_key).generate_signed_url(
version="v4",
expiration=timedelta(minutes=5),
method="GET",
response_disposition="attachment",
service_account_email=SIGNER,
access_token=credentials.token,
api_access_endpoint=ENDPOINT,
)
@app.get("/files/{file_id}")
def download(
file_id: int,
user: Annotated[User, Depends(current_user)],
session: Annotated[Session, Depends(get_session)],
) -> dict[str, str]:
stored = session.scalar(
select(StoredFile).where(StoredFile.id == file_id, StoredFile.tenant_id == user.tenant_id)
)
if stored is None:
raise HTTPException(status_code=404)
# オブジェクトの名前 (storage_key) も、サーバーが決めた値。利用者の名前で組み立てない
return {"url": signed_download_url(stored.storage_key)}
```
アプリのディスクにファイルを置かなければ、名前を書き換えられても、アプリのソースコードや設定には届きません。
バケット・署名する SA・URL の宛先は、本番とローカルで変わるので、設定から渡します (アップロードも署名付き URL で直接上げさせる形は [SSRF の資料](../SSRF/README.md) の 🪪 にあります)。
- ⚠️ 利用者が決めた名前をそのままオブジェクトの名前にすると、ほかの利用者と同じ名前になって上書きされます。オブジェクトの名前もサーバーが決めます
- ⚠️ `response_disposition="attachment"` は、HTML や SVG をブラウザで開かせず、保存させるためです ([XSS の資料](../XSS/README.md) の 📄)
- ⚠️ signBlob で署名するには、実行する SA に、署名する SA (`SIGNER`) への「サービス アカウント トークン作成者」(`roles/iam.serviceAccountTokenCreator`) のロールが要ります。署名付き URL は署名した SA の権限で認可されるので、署名する SA には、バケットのオブジェクトを読む権限 (`storage.objects.get`) も要ります。引数なしの `generate_signed_url()` は、秘密鍵の無い Cloud Run の既定の認証情報では `AttributeError` になります
- ⚠️ ローカルのエミュレーター (fake-gcs-server など) では IAM の signBlob を使えません。エミュレーターは署名を確かめないので、ローカルでは使い捨ての鍵で署名します (上の例では省く)
詳しくは [OWASP の Path Traversal](https://community.owasp.org/attacks/Path_Traversal) と [File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) にまとまっています。
---
# 👑 権限昇格 (Privilege Escalation)
> **利用者が、自分のロールに許されていない操作を、API を直接呼んで実行したり、自分のロールを上げたりできてしまう脆弱性**

画面は、利用者のロールに合わせてボタンやメニューを隠します。けれども API は、画面を通さなくても curl や開発者ツールで呼べます。サーバーが操作ごとに権限を確かめていないと、一般の利用者が管理者の操作をしたり、自分のロールを上げたりできます。
OWASP Top 10:2025 の A01 (アクセス制御の不備) に入る攻撃です。ここでは、自分のテナントの中で、ロールに許されていない操作に届く攻撃 (縦の昇格) を扱います。他のテナントのデータに届く攻撃 (横) は [IDOR の資料](../IDOR/README.md) にまとめています。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

2 は防ぎ切れません。API の呼び方は、画面の JS・API クライアントの型・推測 (`/admin` など) から分かります。確実に欠けさせられるのは 3 です。
```mermaid
sequenceDiagram
autonumber
actor Attacker as 👿 攻撃者
一般のメンバー (member)
participant App as 🚀 正規サーバー
api.example
participant DB as 🐘 DB
メンバーのテーブル
rect rgb(150, 150, 150)
Note over Attacker,App: ふだんの画面には、ロールを変えるボタンが出ない (member なので)
end
rect rgb(150, 100, 100)
Note over Attacker,DB: 画面を通さず、API を直接呼ぶ
Attacker->>+App: PATCH /members/7 {"role": "owner"}
Note right of Attacker: Authorization: Bearer 🔑 (自分のトークン)
7 は自分のメンバー ID
App->>+DB: UPDATE memberships SET role = 'owner'
WHERE id = 7 AND tenant_id = (自分のテナント)
Note right of App: ログインとテナントは確かめるが、
ロールを変えてよいかは確かめない
DB-->>-App: 1 行を更新
App-->>-Attacker: 200 OK (role: owner)
end
rect rgb(150, 100, 100)
Note over Attacker,App: オーナーとして、何でもできる
Attacker->>+App: DELETE /members/1 (本当のオーナーを外す)
App-->>-Attacker: 204 No Content
end
```
- トークンは本物で、テナントでも絞っています (IDOR は防げている)。止められるのは、「この人がロールを変えてよいか」の確認 (認可) だけです
- 縦の昇格には 2 つの形があります。操作の権限を見ない形 (member がロールを変える・メンバーを外す) と、付けるロールの上限を見ない形 (ロールを変えられる admin が、自分をオーナーにする) です
- 画面にリンクの無い管理画面や API を直接開く (強制ブラウジング、CWE-425) も同じです。`/admin`・`/internal/export` などは推測で試されます
💻 コードで見る: ① の PATCH はどう通ってしまうか
画面は、ロールを変える権限が無い人にはボタンを出しません。
```tsx
// 画面: ロールを変える権限が無ければ、ボタンを出さない。隠すのは見た目だけで、API はそのまま呼べる
{me.permissions.includes("membership.change_role") && }
```
② で狙われるサーバーの実装 (FastAPI の例)
```python
# ... import と、User・current_user・get_session・Member・MemberJson・Role の定義 (省く)
class ChangeRoleJson(BaseModel):
role: Role
@app.patch("/members/{member_id}")
def change_role(
member_id: int,
body: ChangeRoleJson,
user: Annotated[User, Depends(current_user)], # ログインしているかは確かめる (認証)
session: Annotated[Session, Depends(get_session)],
) -> MemberJson:
# 自分のテナントのメンバーに絞っている (IDOR は防げている)
member = session.scalar(select(Member).where(Member.id == member_id, Member.tenant_id == user.tenant_id))
if member is None:
raise HTTPException(status_code=404)
member.role = body.role # 変える人 (user) が、ロールを変えてよいかを見ていない (認可が無い)
session.commit()
return MemberJson.model_validate(member, from_attributes=True)
```
① で次のリクエストが届くと、② で自分の行のロールを owner に変えます。
```http
PATCH /members/7 HTTP/1.1
Host: api.example
Authorization: Bearer <攻撃者のトークン>
Content-Type: application/json
{"role": "owner"}
```
画面にボタンが無くても、開発者ツールで別の画面のリクエストを見たり、画面の JS から API の呼び方を読んだりすれば、このリクエストは作れます。
ロールを上げる道は、ロールの変更の API だけではありません。
| 穴 | 何をされるか | 例 |
|:--|:--|:--|
| 操作の権限を確かめない (上の例) | 一般の利用者が、管理者の操作をする | member が `DELETE /members/1` を送る |
| 付けるロールの上限を確かめない | ロールを変えられる人が、自分や仲間を、自分より権限の多いロールにする | admin が `PATCH /members/7 {"role": "owner"}` を送る |
| 招待で上げる | 自分が持たない権限のロールで招待し、別のアカウントで承諾する | admin が owner で招待する |
| 強制ブラウジング (CWE-425) | 画面にリンクの無い管理画面・API を直接開く | `/admin`・`/internal/export` |
| Mass Assignment (OWASP では A08) | 自分の情報の更新に `role` を混ぜる | `PATCH /me {"name": "...", "role": "owner"}` |
## 💥 被害例
ロールを上げられると、そのロールに許された操作が、すべて攻撃者の手に渡ります。
| 狙われる操作 | 被害 |
|:--|:--|
| ロールの変更 | 自分をオーナーにして、テナントを乗っ取る。本当のオーナーを外して、取り戻せなくする |
| メンバーの招待・削除 | 外部の人を招待して、データを持ち出させる。社員を外して、仕事を止める |
| テナントの設定・削除 | SSO などの設定を変えられる。テナントごとデータを消される |
| 課金 | プランを変えられる・請求の情報を見られる |
| 運営向けの管理機能 | 全テナントのデータを見られる・利用者を消される |
| 本文に混ぜたロール (Mass Assignment) | 自分の情報の更新に項目を混ぜて、権限を得る (例: 2012 年の GitHub。更新に項目を混ぜて、自分の公開鍵を他人の組織に登録し、rails/rails に commit を push できた) |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
| ケース | 対策 |
|:--|:--|
| 特定のロールにだけ許す操作 (管理・メンバー・課金) | 👔 操作ごとに権限を確かめる |
| ロールを付ける・変える・招待する・外す | 🪜 自分が持たない権限のロールを扱わせない |
| どのルートも (画面にリンクの無いルートも) | 🚪 既定で拒否 |
| 本文で項目を受け取る | 📝 受け取る項目をモデルで決める |
| どのケースでも | 🧪 ロールと操作の組み合わせのテスト |
| 運営 (社内) 向けの管理機能 | 🏝️ 利用者向けのアプリと分ける |
| 他のテナントのデータに届く (横) | [IDOR の資料](../IDOR/README.md) |
[MUST] 👔 操作ごとに権限を確かめる / ロールではなく操作 (権限) で確かめ、画面で隠すだけにしない
```python
# ... import と、User・current_user・get_session・Permission・ChangeRoleJson・MemberJson の定義 (省く)
class RequirePermission:
"""ルートに要る操作 (権限) を宣言する門。ロールではなく、操作で確かめる"""
def __init__(self, permission: Permission) -> None:
self.permission = permission
def __call__(self, user: Annotated[User, Depends(current_user)]) -> User:
if not user.role.can(self.permission):
raise HTTPException(status_code=403)
return user
@app.patch("/members/{member_id}")
def change_role(
member_id: int,
body: ChangeRoleJson,
user: Annotated[User, Depends(RequirePermission(Permission.MEMBERSHIP_CHANGE_ROLE))],
session: Annotated[Session, Depends(get_session)],
) -> MemberJson:
# ... メンバーは user のテナントで絞って取り (IDOR の対策)、付けるロールも 🪜 で確かめる
...
```
① は、member が `MEMBERSHIP_CHANGE_ROLE` の権限を持たないので 403 になります。
「管理者か」(`user.role == Role.ADMIN`) のようにロールで確かめると、ロールを足すたびにルートを直すことになります (経理だけ・閲覧だけのロールなど)。ルートは要る操作 (権限) を宣言し、どのロールにどの操作を許すかは 1 か所にまとめます。
この資料の例では、ロールに許す操作を `Role` にまとめ、`Role.can` で確かめます。member は管理の操作を 1 つも持たず、admin はテナントの削除と課金の管理を持たないとします。
- ⚠️ 画面でボタンを隠す・メニューから外すのは、使いやすさのためです。守るのはサーバーです
- ⚠️ 上の例では、権限の確認 (403) が、テナントで絞った取得 (404) より先に動きます。権限が無ければ ID に関係なく 403 なので、他のテナントのリソースがあるかは漏れません。権限がある人が他のテナントの ID を送ると、テナントで絞って取るので 404 になります
- ⚠️ API 以外の入口 (MCP のツール・バッチなど) にも、同じ確認を入れます
[MUST] 🪜 自分が持たない権限のロールを扱わせない / ロールを変えられる人に、自分や仲間を上げさせない
```python
# ... import と、Permission・Member・User・app の定義 (省く)
class Role(Enum):
# ... OWNER・ADMIN・MEMBER と、それぞれに許す操作 (permissions)
def can(self, permission: Permission) -> bool:
return permission in self.permissions
def covers(self, other: Role) -> bool:
"""other の権限をすべて持つか"""
return other.permissions <= self.permissions
class PermissionDenied(Exception):
"""操作してよい権限が無い。ドメインは HTTP を知らないので、API の層で 403 に変える"""
def change_role(member: Member, new_role: Role, changed_by: User) -> None:
# 今のロールと新しいロールの両方で、変える人が「ロールを変える権限」と「そのロールの権限すべて」を持つかを確かめる。
# 持たない権限を含むロールに上げることも、自分より権限の多い人を下げることもさせない
for role in (member.role, new_role):
if not changed_by.role.can(Permission.MEMBERSHIP_CHANGE_ROLE) or not changed_by.role.covers(role):
raise PermissionDenied
member.role = new_role
# API の層: ドメインの例外を 403 に変える (MCP やバッチの入口では、それぞれの形のエラーに変える)
@app.exception_handler(PermissionDenied)
async def permission_denied(request: Request, exc: PermissionDenied) -> JSONResponse:
return JSONResponse(status_code=403, content={"detail": "permission denied"})
```
admin が `PATCH /members/7 {"role": "owner"}` を送ると、admin はテナントの削除と課金の管理を持たないので (`ADMIN.covers(OWNER)` が False)、403 になります。admin が member を admin にするのは通ります (自分と同じ権限までは付けられる)。
テナント・操作の権限・相手のロールの 3 つを確かめる処理は、ドメインのモデル (メンバーシップなど) の 1 か所にまとめます。ロールの変更 (今のロールと新しいロールの両方)・メンバーを外す・招待・招待の取り消しのどれも、この確認を通します。
- ⚠️ ロールに順位 (owner > admin > member) を付けて比べず、権限の集合を含むかで比べます。順位で表せないロール (経理だけ・閲覧だけ) を足しても、正しく比べられます
- ⚠️ 招待でも同じ確認が要ります。持たない権限のロールで招待し、別のアカウントで承諾すれば、同じように上げられます
- ⚠️ 自分自身のロールの変更も、同じ確認を通します
[MUST] 🚪 既定で拒否 / 門を付け忘れたルートを、公開しない (強制ブラウジング)
```python
# ... import と、User・current_user・RequirePermission・Permission の定義 (省く)
# ログインの要るルートは、門 (current_user) を付けたルーターに載せる。公開するルートだけを、別のルーターに分ける
public = APIRouter()
private = APIRouter(dependencies=[Depends(current_user)])
@public.get("/health/check")
def health_check() -> dict[str, bool]:
return {"health": True}
@private.delete("/members/{member_id}", status_code=204)
def remove_member(
member_id: int,
# ルーターの dependencies は、門の戻り値を捨てる。テナントで絞るルートや、権限を確かめるルートは、引数でも門を受け取る。
# FastAPI は同じリクエストの中で依存の結果をキャッシュするので、current_user は二度は呼ばれない
user: Annotated[User, Depends(RequirePermission(Permission.MEMBERSHIP_REMOVE))],
) -> None:
# ... 外す相手は user のテナントで絞って取り (IDOR の対策)、相手のロールも 🪜 で確かめる
...
app.include_router(public)
app.include_router(private)
```
付け忘れは、全ルートを並べて呼ぶテストで見つけます。
```python
# test/test_route_auth.py: トークン無しで呼ぶと、公開するルート以外はすべて 401 になるかを確かめる
import re
from fastapi.testclient import TestClient
from api import app
PUBLIC = {("get", "/health/check")}
def test_公開するルート以外はログインが要る() -> None:
with TestClient(app) as client:
# 全ルートを、API の仕様書 (OpenAPI) から並べる。仕様書を公開しない設定 (openapi_url=None) でも作れる
for path, operations in app.openapi()["paths"].items():
for method in operations:
if (method, path) in PUBLIC:
continue
# パスの変数はダミーの値で埋める。FastAPI は依存 (current_user) を、パスや本文の検査より先に解くので、401 で止まる
response = client.request(method, re.sub(r"\{[^}]+\}", "1", path))
assert response.status_code == 401, f"{method} {path}"
```
ルートを足すと、このテストが公開するかどうかを聞いてきます (`PUBLIC` に足すか、門を付ける)。
- ⚠️ ここで確かめるのは「ログインが要るか」までです。操作の権限 (👔) は、ルートごとに宣言します
- ⚠️ `include_in_schema=False` のルート・`app.mount()` したアプリ・Starlette の `Route` は仕様書に載らないので、このテストから漏れます。マウントしたアプリには、それぞれで同じ門とテストを用意します
- ⚠️ 画面 (Next.js) の管理ページも、表示する前にサーバーで権限を確かめます。漏れても、データは API が権限を確かめてから返すので、中身は渡りません
[SHOULD] 📝 受け取る項目をモデルで決める / 本文に role を混ぜられても、入れない (Mass Assignment)
```python
from pydantic import BaseModel, ConfigDict
# ... ほかの import と、User・current_user・get_session・UserJson の定義 (省く)
class UpdateProfileJson(BaseModel):
# 利用者が自分で変えてよい項目だけを書く。role・tenant_id は書かない
model_config = ConfigDict(extra="forbid") # 知らない項目 (role など) が来たら 422 にする
name: str
@app.patch("/me")
def update_profile(
body: UpdateProfileJson,
user: Annotated[User, Depends(current_user)],
session: Annotated[Session, Depends(get_session)],
) -> UserJson:
user.name = body.name # 1 項目ずつ入れる
session.commit()
return UserJson.model_validate(user, from_attributes=True)
```
```python
# ❌ 本文の項目を、すべてそのまま入れる。{"name": "...", "role": "owner"} で自分をオーナーにできる
for key, value in body.items():
setattr(user, key, value)
```
Pydantic の既定 (`extra="ignore"`) でも、モデルに無い項目は捨てられます。`extra="forbid"` にすると、混ぜられたことに 422 で気づけます。
Mass Assignment は、OWASP Top 10:2025 では A08 (ソフトウェアやデータの完全性の不備) に入ります ([一覧](../README.md))。
- ⚠️ DB のモデル (SQLAlchemy) を、入力のモデルに使いません。DB にある項目を、すべて書き換えられます
- ⚠️ ロールを変えるのは、👔 と 🪜 を通す専用の API だけにします
[SHOULD] 🧪 ロールと操作の組み合わせのテスト / 拒否される側も、表にしてテストする
```python
# ... import と、fixture (client・login_as)・テストデータを作る関数 (add_member) の定義 (省く)
@pytest.mark.parametrize(
("role", "status"),
[(Role.OWNER, 204), (Role.ADMIN, 204), (Role.MEMBER, 403)],
)
def test_メンバーを外せるのはオーナーと管理者だけ(
client: TestClient, login_as: LoginAs, role: Role, status: int
) -> None:
member_id = add_member("a-corp", Role.MEMBER)
response = client.delete(f"/members/{member_id}", headers=login_as("a-corp", role))
assert response.status_code == status
@pytest.mark.parametrize(
("changed_by", "target", "new_role", "status"),
[
(Role.OWNER, Role.MEMBER, Role.OWNER, 200),
(Role.ADMIN, Role.MEMBER, Role.ADMIN, 200),
(Role.ADMIN, Role.MEMBER, Role.OWNER, 403), # 自分が持たない権限 (テナントの削除・課金) を含むロールには上げられない
(Role.ADMIN, Role.OWNER, Role.MEMBER, 403), # 自分より権限の多い人 (今のロール) は下げられない
(Role.MEMBER, Role.MEMBER, Role.ADMIN, 403), # ロールを変える権限が無い
],
)
def test_ロールを変えられる範囲(
client: TestClient, login_as: LoginAs, changed_by: Role, target: Role, new_role: Role, status: int
) -> None:
member_id = add_member("a-corp", target)
response = client.patch(
f"/members/{member_id}", json={"role": new_role.value}, headers=login_as("a-corp", changed_by)
)
assert response.status_code == status
```
権限昇格は、自分のロールで許された操作をするふだんのテストでは見つかりません。ロールと操作の組み合わせを表にして、拒否される側もテストします。
API のテストに加えて、ドメインのテストでも、ロールごとの操作や「管理者がメンバーをオーナーにすると拒否する」などの組み合わせを確かめます。
- ⚠️ 操作 (Permission) を足したら、表にも足します。`list(Permission)` で parametrize すると、足した操作が漏れません
[WANT] 🏝️ (設計) 運営向けの管理機能を、利用者向けのアプリと分ける / 利用者の API から、運営の操作に届かせない
```mermaid
flowchart LR
user["🥸 利用者"] --> app["🚀 app.example
利用者向け"]
staff["🧑💼 運営"] --> gate["🔐 社内の ID・端末で絞る
Identity-Aware Proxy など"]
gate --> admin["🛠️ admin.example
運営向け"]
user -.-x admin
```
全テナントを見る・利用者を消すといった運営の操作を、利用者向けの API に混ぜると、権限の確認が 1 つ漏れただけで、利用者が運営の操作をできます。
運営向けは別のサービス・別のドメインにし、手前で社内の ID と端末に絞ります。利用者向けの API には、運営の操作を置きません。
- ⚠️ 分けても、運営向けのサービスの中で、操作ごとの権限 (👔) は要ります (サポート担当・経理など)
- ⚠️ 運営の操作は、誰が・いつ・どのテナントに何をしたかを記録に残します
詳しくは [OWASP の Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) と [Mass Assignment Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html) にまとまっています。
---
# 🛡️ SSRF (Server-Side Request Forgery) 攻撃
> **攻撃者が指定した宛先へ、サーバーにリクエストを送らせる攻撃**

サーバーは、外からは届かない場所 (メタデータサーバー・内部の API・DB) にも届きます。URL を受け取って取りに行く機能があると、攻撃者はサーバーを踏み台にして、そこへ送らせます。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

```mermaid
sequenceDiagram
autonumber
actor Attacker as 👿 攻撃者
participant App as 🚀 正規サーバー
api.example
participant Meta as 🔑 メタデータサーバー
169.254.169.254
participant Cloud as ☁️ クラウドの API
ストレージなど
rect rgb(150, 100, 100)
Note over Attacker,App: 内部を指す URL を渡す
Attacker->>+App: この URL の画像を取り込んで
Note right of Attacker: POST /avatar/import
{"url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/app-role"}
end
rect rgb(150, 100, 100)
Note over App,Meta: サーバーが内部へ取りに行く
App->>+Meta: GET /latest/meta-data/iam/security-credentials/app-role
Note right of App: 外からは届かないが、サーバーからは届く
Meta-->>-App: サーバーの認証情報 (AccessKeyId・SecretAccessKey・Token)
App-->>-Attacker: 取ってきた中身を、そのまま返す
end
rect rgb(150, 100, 100)
Note over Attacker,Cloud: 盗んだ認証情報で、クラウドの API を呼ぶ
Attacker->>+Cloud: ストレージのデータを読む (🔑 認証情報を付ける)
Cloud-->>-Attacker: 認証情報が正しい → サーバーの権限 (app-role) で返す
end
```
- 攻撃者は内部へ直接送れませんが、正規サーバーが代わりに送るので、ファイアウォールや IP の制限を通ります
- 応答を返さない機能でも危険です (ブラインド SSRF)。内部の API を呼ぶだけで副作用が起き、応答の時間やエラーの違いから、内部のホストやポートも調べられます
💻 コードで見る: ① の URL はどう取りに行かれるか
② で狙われるサーバーの実装 (FastAPI の例)
```python
class ImportAvatar(BaseModel):
url: str
@app.post("/avatar/import")
async def import_avatar(body: ImportAvatar):
async with httpx2.AsyncClient() as client:
response = await client.get(body.url) # 利用者が渡した URL へ、確かめずに送る
# 取ってきた中身を、そのまま返す (プレビューのため)
return Response(response.content, media_type=response.headers.get("content-type"))
```
① で次のリクエストが届くと、② でサーバーは `http://169.254.169.254/...` へ GET します。
```http
POST /avatar/import HTTP/1.1
Host: api.example
Content-Type: application/json
{"url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/app-role"}
```
169.254.169.254 は、クラウド (AWS・GCP・Azure) のメタデータサーバーの IP で、VM やコンテナの中からだけ届きます。サーバーの権限 (IAM ロール・サービスアカウント) の一時的な認証情報を返します。③ の応答 (AWS の IMDSv1) は次のとおりです。
```json
{
"Code": "Success",
"LastUpdated": "2026-11-02T00:00:00Z",
"Type": "AWS-HMAC",
"AccessKeyId": "ASIA...",
"SecretAccessKey": "...",
"Token": "...",
"Expiration": "2026-11-02T06:00:00Z"
}
```
文字列で `169.254.169.254` や `localhost` を弾いても、同じ宛先を別の書き方で渡されます。
| 渡される URL | 実際の宛先 |
|:--|:--|
| `http://2852039166/` | 169.254.169.254 (10 進数で書いた IP) |
| `http://0xa9fea9fe/` | 169.254.169.254 (16 進数で書いた IP) |
| `http://127.1/` | 127.0.0.1 (省略して書いた IP) |
| `http://[::1]/` | 自分自身 (IPv6 のループバック) |
| `http://meta.evil.example/` | 攻撃者の DNS が 169.254.169.254 を返す |
| `https://evil.example/r` | 302 で `http://169.254.169.254/...` へリダイレクトする (リダイレクトを追うクライアントのとき。httpx2 は既定で追わない) |
DNS とリダイレクトは、送る前に URL の文字列を見ても見抜けません。
## 💥 被害例
サーバーから届く場所は、すべて狙われます。
| 狙われる場所 | 被害 |
|:--|:--|
| クラウドのメタデータサーバー | サーバーの権限の認証情報を盗まれ、ストレージや DB を読まれる (例: 2019 年の Capital One の情報流出、1 億人超) |
| 内部の API・管理画面 | 認証の無い内部の API を呼ばれ、データを読まれる・消される |
| DB・キャッシュ (Redis など) | `gopher://` を扱うクライアント (curl など) だと、任意のコマンドを送られる |
| サーバーのファイル | `file://` を扱うクライアント (urllib など) だと、設定ファイルや秘密鍵を読まれる |
| 内部ネットワーク | 応答の時間やエラーの違いから、ホストとポートを調べられる |
| 外部のサイト | サーバーを踏み台にして攻撃される (送り元がサーバーの IP になる) |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。
| ケース | 対策 |
|:--|:--|
| 送り先が決まっている (連携先の API・決まった CDN の画像など) | 📋 許可リスト + ↪️ リダイレクトを追わない |
| 任意の URL へ送る (Webhook・OGP のプレビュー・URL からの画像の取り込み) | 🌐 名前解決した IP の確認 + ↪️ リダイレクトを追わない |
| 利用者のファイルを受け取るだけ (画像のアップロード) | 🪪 サーバーに URL を取りに行かせない (署名付き URL) |
| どのケースでも | 🙈 応答とエラーをそのまま返さない・🔑 メタデータサーバーのヘッダー必須・🧱 出口をネットワークで絞る |
[MUST] 📋 許可リスト / 決めたホストにだけ送る
```python
from urllib.parse import urlsplit
from fastapi import HTTPException
ALLOWED_HOSTS = {"images.example", "cdn.example"}
def check_allowed(url: str) -> None:
parts = urlsplit(url)
# netloc (userinfo・ホスト・ポート) を完全一致で比べる。endswith や in は evil-images.example などで破られる
if parts.scheme != "https" or parts.netloc.lower() not in ALLOWED_HOSTS:
raise HTTPException(status_code=400)
```
`https://user@images.example` や `https://images.example:8080` も弾かれます。
URL の代わりに ID (連携先の名前など) を受け取り、サーバーで URL を組み立てられるなら、さらに確実です。
- ⚠️ ブロックリスト (`169.254.169.254`・`localhost` を弾く) にしないでください。上の表の書き方で破られます
- ⚠️ 許可したホストにオープンリダイレクトがあると、そこから内部へ飛ばされます。↪️ リダイレクトを追わない、も実装します
- ⚠️ Next.js の `next/image` も、サーバーが画像を取りに行きます。`images.remotePatterns` は必要なホストだけにし、`hostname: "**"` や `images.dangerouslyAllowLocalIP: true` にしません
[MUST] 🌐 名前解決した IP の確認 / 内部の IP なら送らず、確かめた IP に送る
SSRF 以外の対策 (応答の大きさ・時間の上限など) は `# ...` で省いています。
```python
import asyncio
import ipaddress
import socket
from urllib.parse import urlsplit
import httpx2
class ForbiddenDestinationError(Exception):
pass
# NAT64 は、出口で埋め込まれた IPv4 (内部の IP もありうる) に変換されて届く
NAT64 = ipaddress.ip_network("64:ff9b::/96")
# IPv6 はグローバルユニキャストだけを通す。::a9fe:a9fe (IPv4 互換) など、is_global が True になる形を弾く
GLOBAL_UNICAST = ipaddress.ip_network("2000::/3")
def is_public(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
if isinstance(ip, ipaddress.IPv6Address):
if ip in NAT64:
ip = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
elif ip not in GLOBAL_UNICAST:
return False
return ip.is_global
async def fetch_public(url: str) -> httpx2.Response:
parts = urlsplit(url)
host = parts.hostname
if parts.scheme != "https" or host is None:
raise ForbiddenDestinationError(url)
# ... 国際化ドメイン名・末尾のドット・IPv6 のリテラルの扱い (SSRF 以外なので省く)
# 名前解決し、返ったすべての IP がインターネット上の IP かを確かめる
infos = await asyncio.get_running_loop().getaddrinfo(host, 443, type=socket.SOCK_STREAM)
ips = [ipaddress.ip_address(info[4][0]) for info in infos]
# not ips は念のための備え (all() は空のリストで True になる)
if not ips or not all(is_public(ip) for ip in ips):
raise ForbiddenDestinationError(url)
# 確かめた IP に繋ぐ。ホスト名のまま送ると、もう一度名前解決され、内部の IP を返されうる (DNS リバインディング)
# URL のポートと userinfo は捨て、443 に繋ぐ
ip = ips[0]
pinned = parts._replace(netloc=f"[{ip}]" if ip.version == 6 else str(ip)).geturl()
# ... 名前解決・応答の時間の上限、応答の大きさ、同時に取りに行く数、圧縮した応答、
# 繋ぐ IP の選び方 (IPv4 の優先など) (SSRF 以外なので省く)
async with httpx2.AsyncClient(timeout=5) as client:
return await client.get(
pinned,
headers={"Host": host},
# 証明書は、IP ではなく元のホスト名で確かめる
extensions={"sni_hostname": host},
)
```
`is_global` は、プライベート (10.0.0.0/8 など)・ループバック (127.0.0.0/8・::1)・リンクローカル (169.254.0.0/16) で False になります。NAT64 (`64:ff9b::a9fe:a9fe`) と IPv4 互換 (`::a9fe:a9fe`) は True になるため、`is_public` で別に弾きます。
上の表の書き方は、名前解決した後の IP で確かめるので弾かれます (`http://` はスキームの確認で先に弾かれます)。302 のリダイレクトだけは、次の ↪️ で弾きます。
- ⚠️ スキームは `https` だけにします。`file://`・`gopher://` を扱うクライアントにそのまま渡しません
- ⚠️ ネットワークで独自の NAT64 のプレフィックスを使うなら、それも `NAT64` と同じように確かめます
[MUST] ↪️ リダイレクトを追わない / 確かめた URL から、内部へ飛ばされないようにする
```python
# httpx2 は既定でリダイレクトを追わない。follow_redirects=True にしない
response = await fetch_public(url)
# 2xx 以外 (Location の無い 3xx も) は使わない
if not response.is_success:
raise ForbiddenDestinationError(url)
```
```ts
// Node.js (Next.js のサーバー) の fetch は、既定でリダイレクトを追う
const response = await fetch(url, { redirect: "error" });
```
- ⚠️ `requests`・`urllib` も既定で追います
- ⚠️ 追う必要があるときは、リダイレクト先ごとに IP の確認からやり直します
- ⚠️ Node でも、`redirect: "error"` だけでは足りません。🌐 と同じ IP の確認と固定が要ります (または、`fetch_public` を持つ backend を通して取りに行きます)
[SHOULD] 🙈 応答とエラーをそのまま返さない / 内部の中身や、内部を調べる手がかりを渡さない
```python
# ... import と、User・current_user・avatars の定義 (省く)
@app.post("/avatar/import")
async def import_avatar(body: ImportAvatar, user: Annotated[User, Depends(current_user)]):
try:
response = await fetch_public(body.url)
except Exception as error:
# 失敗の理由 (弾いた・繋がらない・タイムアウト・名前解決できない) で応答を変えない。
# 変えると、その違いから内部のホストやポートを調べられる
raise HTTPException(status_code=400, detail="画像を取り込めませんでした") from error
# 2xx 以外 (リダイレクトの 3xx も) と、画像以外は取り込まない
content_type = response.headers.get("content-type", "").split(";")[0]
if not response.is_success or content_type not in {"image/png", "image/jpeg"}:
raise HTTPException(status_code=400, detail="画像を取り込めませんでした")
# ... 本文が本当に画像かの確認 (SSRF 以外なので省く)
avatars.save(user, response.content)
# 取ってきた中身は返さず、取り込んだことだけを返す
return {"result": "取り込みました"}
```
メタデータサーバーの応答は画像ではないので取り込まれず、攻撃者にも返りません。
- ⚠️ 内部へ送ること自体は止まりません (ブラインド SSRF)。画像を返す内部の宛先も守れません。MUST の対策と組み合わせます
- ⚠️ 応答の時間の違いは残ります (弾くとすぐ、接続のタイムアウトは 5 秒)。🧱 の出口のプロキシか、取り込みを非同期のジョブにすると消せます
[SHOULD] 🔑 メタデータサーバーにヘッダーを必須にする / URL を渡すだけでは、認証情報を読めなくする
```hcl
# AWS: IMDSv2 を必須にする (先に PUT でトークンを取り、ヘッダーに付けないと読めない)
resource "aws_instance" "app" {
# ...
metadata_options {
http_tokens = "required"
# 1 だと、EC2 の上のコンテナ (Docker の bridge など) からは届かない。コンテナのアプリが使うなら 2 にする
http_put_response_hop_limit = 1
}
}
```
GCP (Cloud Run など) のメタデータサーバーは、`Metadata-Flavor: Google` ヘッダーが無いと応答しないので、URL を渡すだけでは読めません。
- ⚠️ 利用者がヘッダーを決められる機能 (Webhook に付けるヘッダーの設定など) があると破られます
- ⚠️ 内部の API や DB は守れません。ほかの対策と組み合わせます
[SHOULD] 🧱 出口をネットワークで絞る / アプリの確認をすり抜けても、内部へ届かせない
```mermaid
flowchart LR
api["🚀 api
権限あり"] -->|取りに行く URL| fetcher["📥 fetcher
権限なし"]
fetcher --> proxy["🧱 出口のプロキシ
内部の IP を止める"]
proxy --> internet["🌐 インターネット"]
proxy -.-x internal["🔒 内部の API・DB"]
```
- URL を取りに行く処理を、別のサービス (fetcher) に分けます。fetcher のサービスアカウントにはロールを付けず、認証情報を盗まれても何もできないようにします
- fetcher の出口をプロキシ (例: Stripe の Smokescreen) かファイアウォールに通し、内部の IP への送信を止めます
- ⚠️ GCP の VPC のファイアウォールは、メタデータサーバーへの送信を止めません。権限の無いサービスアカウントで守ります
[WANT] 🪪 (設計) サーバーに URL を取りに行かせない / ファイルは、署名付き URL でストレージへ直接上げさせる
```mermaid
sequenceDiagram
actor User as 🥸 利用者
participant App as 🚀 正規サーバー
participant GCS as 🪣 Cloud Storage
User->>App: 画像を上げたい
App-->>User: 署名付き URL (5 分だけ、その利用者の画像の置き場に PUT できる)
User->>GCS: PUT 署名付き URL (画像の本文)
```
サーバーは署名付き URL (期限付きの書き込み先) を発行するだけで、利用者の URL へは送りません。
ファイルのアップロードを足すときは、この形にします。
- ⚠️ Webhook や OGP のプレビューのように、外部の URL へ送ること自体が機能なら使えません。🌐 と ↪️ を実装します
詳しくは [OWASP の SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html) にまとまっています。
---
# 💉 XSS (Cross-Site Scripting) 攻撃
> **攻撃者が書いたスクリプトを、正規サイトのページの一部として、ほかの利用者のブラウザで動かす攻撃**

ブラウザは、正規サイトから届いた HTML の中のスクリプトを、正規サイトのものとして実行します。利用者の入力をエスケープせずにページに出すと、攻撃者が書いたスクリプトが、見た人のブラウザで、その人の権限で動きます。
## 📚 攻撃手順
次の 3 つがそろうと成立します。

```mermaid
sequenceDiagram
autonumber
actor Attacker as 👿 攻撃者
participant App as 🚀 正規サイト
app.example
actor User as 🥸 利用者 (被害者)
participant Evil as 👿 攻撃者のサーバー
evil.example
rect rgb(150, 100, 100)
Note over Attacker,App: スクリプトを仕込む
Attacker->>App: 自己紹介を保存して
Note right of Attacker: POST /profile
bio=#lt;img src=x onerror=...#gt;
end
rect rgb(150, 150, 150)
Note over App,User: ふだんどおりページを開く
User->>+App: 攻撃者のプロフィールを開く (🍪 Cookie を付ける)
App-->>-User: 自己紹介を、エスケープせずに HTML に埋めて返す
end
rect rgb(150, 100, 100)
Note over App,Evil: スクリプトが、被害者の権限で動く
User->>User: ブラウザが、app.example のスクリプトとして実行する
User->>Evil: (スクリプトが) 画面の名前・メールアドレスを送る
User->>+App: (スクリプトが) メールアドレスを、攻撃者のものに変えて
Note right of User: 同じサイトからの送信なので、🍪 Cookie が付き、Origin も app.example
App-->>-User: 🍪 Cookie が正しい → 本人の操作とみなして変える
end
```
- 攻撃者は、プロフィールの保存というふつうの機能を使うだけです。被害者は、ページを開いただけで被害に遭います
- **HttpOnly では防げない**: HttpOnly の Cookie はスクリプトから読めませんが、スクリプトは被害者のブラウザで動くので、同じサイトへの送信には Cookie が自動で付きます。盗まずに、その場で被害者として操作します
- **CSRF の対策も通る**: 送り元が正規サイトそのものなので、SameSite も Origin の確認も止めません ([CSRF の資料](../CSRF/README.md))
スクリプトの入り方で、3 つに分かれます。
| 種類 | 入り方 | 被害者に届く経路 |
|:--|:--|:--|
| 格納型 (Stored) | 投稿・自己紹介などに保存され、そのまま表示される (上の例) | ページを開いた人すべて |
| 反射型 (Reflected) | URL のパラメータ (検索語など) が、そのまま応答に出る | 罠のリンクを開かされた人 |
| DOM ベース | サーバーを通らず、ブラウザの JS が `location.hash` などを `innerHTML` に入れる | 罠のリンクを開かされた人 |
💻 コードで見る: ③ の HTML はどう作られ、④ でどう動くか
③ で狙われる実装 (Next.js の例)
```tsx
// app/users/[id]/page.tsx: プロフィールのページ
export default async function ProfilePage({ params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const profile = await getProfile(id);
// 自己紹介で改行や太字を使えるよう、HTML としてそのまま出している
return ;
}
```
① で攻撃者は、自己紹介に次の文字列を保存します。
```html
```
④ で、`src="x"` の画像の読み込みに失敗し、`onerror` の JS が app.example のスクリプトとして動きます。
サーバーで描いた HTML (最初の表示) なら、` で XSS (反射型)
@app.get("/search", response_class=HTMLResponse)
def search(q: str):
return f"「{q}」の検索結果
"
```
## 💥 被害例
スクリプトは、被害者がそのページでできることを、すべてできます。
| 狙われるもの | 被害 |
|:--|:--|
| 被害者としての操作 | メールアドレス・パスワードの変更、投稿、送金をされる。メールアドレスを変えられると、パスワードリセットで乗っ取られる |
| 画面に出ている情報 | 個人情報・メッセージ・取引の履歴を読まれ、外へ送られる |
| Cookie・トークン | HttpOnly でない Cookie や、`localStorage` のトークンを盗まれ、攻撃者のブラウザで使われる |
| 画面そのもの | 偽のログインフォームを出され、パスワードを入力させられる。表示を書き換えられる |
| ほかの利用者 | 見た人のプロフィールにも同じスクリプトを書き込ませ、広がる (ワーム。例: 2005 年の MySpace の Samy ワーム、1 日で 100 万人超) |
## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。
| ケース | 対策 |
|:--|:--|
| 利用者の入力を画面に出す (どのケースでも) | 🔤 出す場所に合わせてエスケープする |
| 利用者が書いた HTML を出す (リッチテキストなど) | 🧼 サニタイズしてから出す |
| 利用者の URL を、リンクや遷移先に使う | 🔗 プロトコルの許可リスト |
| どのケースでも | 🛡️ CSP・🍪 Cookie とトークンをスクリプトから読ませない・📄 利用者のファイルをアプリのオリジンから配らない |
| 画面を作り直す・新しく作る | 🧷 Trusted Types |
入力の確かめ (文字数・形式) は補いにはなりますが、XSS の対策の中心ではありません。名前やコメントには `<` も `"` も入りうるので、出すときに守ります。
[MUST] 🔤 出す場所に合わせてエスケープする / HTML を文字列で組み立てず、JSX やテンプレートに任せる
```tsx
// ✅ JSX の {} に入れると、React が < > & などをエスケープし、文字として出す
// 改行は HTML ではなく CSS で出す
return {profile.bio}
;
```
① の文字列は、`
` という文字のまま画面に出て、動きません。
FastAPI で HTML を返すときは、テンプレート (Jinja2) を使うか、入れる値をすべて `html.escape` します。
```python
import html
from fastapi.responses import HTMLResponse
@app.get("/search", response_class=HTMLResponse)
def search(q: str):
# < > & " ' を < などに置き換える
return f"「{html.escape(q)}」の検索結果
"
```
- ⚠️ HTML のエスケープが効くのは、タグの間と、引用符で囲んだ属性の値だけです。`` で抜けられます
- ⚠️ FastAPI (Starlette) の `Jinja2Templates` は、拡張子が `.html`・`.htm`・`.xml` のテンプレートだけを自動でエスケープします (Starlette 1.10 は `jinja2.select_autoescape()` を渡す。古い版は `autoescape=True` だった)。`.txt` などのテンプレートで HTML を返さない・`|safe` や `Markup()` を使わないでください
[MUST] 🧼 利用者の HTML はサニタイズしてから出す / dangerouslySetInnerHTML に、そのまま渡さない
```tsx
import DOMPurify from "isomorphic-dompurify";
// 許可したタグと属性だけを残す。onerror・