# 認証とOAuth

> APIキー、PKCEを使用したOAuth 2.1（SMART on FHIRスタンドアロン起動）、OpenID Connect id_token、SMART v2患者スコープ、トークンの有効期間、および同意のライフサイクル。

Source: https://developers.anpheros.com/ja/guides/authentication

Anpheros Platformは3種類の認証情報を受け入れます。各リクエストは、そのうちの1つのみを送信します。

| 認証情報 | 見た目 | 誰が | 見ることができるか |
|---|---|---|---|
| APIキー | `sk_test_…`（サンドボックス） / `sk_live_…`（本番環境） | プロジェクトのサーバー | プロジェクトが作成した患者（サンドボックスでは、30人の合成患者の独自のコピーを含む） |
| OAuthアクセストークン | `at_…` | 同意の下で1人の患者のために動作するアプリケーション | 付与されたSMARTスコープ内で、その患者のみ |
| Firebase IDトークン | JWT | ダッシュボードの開発者、または「接続」の患者 | 自身の組織 / 自身のレコード |

これを`Authorization: Bearer <credential>`として送信します（APIキーは`X-Api-Key`としても機能します）。

## APIキー
- ダッシュボードまたは`POST /admin/projects/{id}/keys`から作成されます。一度のみ表示され、SHA-256ハッシュとして保存されます。
- スコープ：`read`、`write`。キーはプロジェクトの環境を越えることはありません（`sk_test_`は本番データに到達できず、その逆も同様です）。
- キーごとのレート制限（デフォルト600/分）は、プラットフォーム全体（共有ストア）で適用され、429エラー時に`Retry-After`が発生します。IPごとの制限は600/分です。
- 書き込み時のオプションヘッダー：`X-Anpheros-Author-Type`、`X-Anpheros-Author-Ref`、`X-Anpheros-Source-System`、`X-Anpheros-Origin-Id`、`X-Anpheros-Acting-As`（**自身のディレクトリ内の**Practitioner/PractitionerRole）、`X-Anpheros-On-Behalf-Of`（自身のディレクトリ内のOrganization）。これらはProvenanceを生成します。

## OAuth 2.1 (SMART on FHIR, standalone launch)
Discovery: `GET /.well-known/smart-configuration`.

1. `GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&state=…&code_challenge=…&code_challenge_method=S256[&purpose=treatment][&patient=<pairwise id>][&lang=ro]`
   ホストされている同意ページを表示します。PKCE S256 は必須です。`redirect_uri` は正確に登録する必要があります。
2. 患者はサインインし（Firebase 経由で Google またはメール）、レコード（自身のものまたは扶養家族のもの）を選択し、期間（30/90/180/365 日）を選択して許可します。プラットフォームは 1 回限りのコード（10 分間）を発行します。
3. `grant_type=authorization_code&code=…&code_verifier=…&redirect_uri=…&client_id=…` を使用して `POST /oauth/token` します（機密クライアントは `client_secret` を追加します）。
   レスポンス: `access_token`（30 分）、`refresh_token`（30 日、ローテーション）、`patient`（レコードのペアワイズ ID）、`grant_id`、`scope`。
4. リフレッシュ: `grant_type=refresh_token`。各リフレッシュ トークンは 1 回限り使用可能です。**使用済みリフレッシュ トークンを提示すると、チェーン全体が取り消されます**（盗難検出）。リフレッシュ リクエストの並列重複は拒否され、チェーンを取り消す可能性もあるため、同時にローテーションしないでください。
5. 取り消し: `POST /oauth/revoke`（トークン + client_id）。リフレッシュ トークンを取り消すと、そのアクセス トークンもすべて取り消されます。

トークン レスポンスには、SMART が要求する `Cache-Control: no-store` と `Pragma: no-cache` が含まれます。

### OpenID Connect (`openid fhirUser`)
患者スコープと共に `openid fhirUser` を要求すると、トークン レスポンスには `id_token` も含まれます。これは RS256 で署名された JWT で、`iss`（プラットフォームのベース URL）、`sub`（人物のペアワイズ ID）、`aud`（`client_id`）、`exp`、`iat`、および `fhirUser`（受け取ったばかりのアクセス トークンで読み取れる、人物の Patient リソースの絶対 URL）が含まれます。Discovery は `GET /.well-known/openid-configuration` にあり、公開鍵は `GET /oauth/jwks`（トークン ヘッダーの `kid`）にあります。`nonce` パラメータはまだサポートされていません（認可コード フローではオプションです）。`launch/patient` と `offline_access` は受け入れられます。トークン レスポンスの `patient` フィールドは、起動コンテキストです。

その他の grant タイプ: `client_credentials`（機密クライアント。API キーのように動作します）、およびファーストパーティ ID grant（信頼されたクライアントのみ）。

### 同意ページでのブランド表示

アプリケーションは、ホストされている同意ページにロゴとアクセント カラーを表示できます。コンソール（Applications → Brand）または管理者 API で設定します。

```http
PUT /admin/applications/{application_id}/branding
{"logo": "data:image/png;base64,…", "brand_color": "#1D4ED8"}
```

- **ロゴ:** データ URI の PNG、JPEG、または WebP 画像。最大 64 KB。コンテンツがチェックされ、宣言されたタイプはチェックされません。SVG は受け入れられません。画像はアプリケーションと共に保存され、ページに埋め込まれるため、同意ページはサーバーにリクエストを送信しません。
- **アクセント カラー:** `#RRGGBB`。プライマリ ボタンに使用されます。その上の白文字は、少なくとも 4.5:1（WCAG AA）のコントラストを維持する必要があります。明るすぎる色は拒否されます。
- 省略されたフィールドはそのまま維持されます。`null` または空文字列で削除されます。

ページの残りの部分は変更されません。「Secured by Anpheros Platform」の行、アプリケーションが要求しているものの平易な言葉でのリスト、サンドボックス プロジェクトの TEST バナーはそのまま残るため、同意が Anpheros によって保持されていることを常に確認できます。AI コネクタ（MCP）は、アプリケーション ブランドなしで常に Anpheros ページを表示します。

### スコープ
SMART v2 患者スコープ: `patient/<Type>.<cruds>` にオプションの `?category=<code>` フィルター（サーバーが強制する唯一のフィルター。他のフィルターは認可時に拒否されます）。`patient/*.rs` はすべてを読み取ります。`offline_access` はリフレッシュ トークンを追加します。患者の人口統計情報とディレクトリは、常に付与の下で読み取ることができます。付与外のリソース タイプは 403 を返し、付与外の患者は 404 を返します。

### 同意ライフサイクル
同意は自動的に期限切れになり、患者はいつでも取り消すことができます（Connections 画面 / `/me`）。同意の下でのすべての読み取りは、アプリケーション ID と共にログに記録されます。Webhook `consent.granted` / `consent.revoked` がプロジェクトに通知します。

## エラー
401 unknown/expired credential · 403 the credential exists but may not do this · 404 the resource does not exist *for you* · 429 rate limited (`Retry-After`)。詳細は [`errors.md`](https://developers.anpheros.com/ja/guides/errors) を参照してください。