> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgea.app/llms.txt
> Use this file to discover all available pages before exploring further.

# JWT 認証

> IDプロバイダー（Entra ID、Oktaなど）が発行するJWTベアラートークンでシステム間のAPIリクエストを認証

## 概要

JWTトークン認証では、ユーザー固有のCorgea APIトークンの代わりに、Microsoft Entra IDやOktaなど、IDプロバイダー(IdP)から直接発行されたベアラートークンを使ってCorgea APIを呼び出すことができます。

これは、CI/CDパイプライン、自動スキャナー、社内ツールなど**システム間統合**において推奨されるアプローチです。

* 特定のユーザーアカウントではなく、サービスプリンシパルやアプリ登録に紐づくトークン
* IdPが制御するトークンの寿命と範囲
* Corgeaに手を出さずに、IdPを通じて一元で取り消しを行う

Corgea APIトークンは常に個々のユーザーに紐づいています。そのユーザーが退出したりアカウントが無効化されたりすると、そのトークンを使った自動化は無効になります。JWT認証は認証をユーザーアカウントから完全に切り離します。

## 仕組み

1. システムがクライアント認証情報（クライアントIDとシークレット）を使用して、IdPにアクセストークンを要求します。
2. IdPが、`iss`（発行者）や`aud`（オーディエンス）などのクレームを含む署名済みJWTを返します。
3. システムがCorgea APIを呼び出す際に、`Authorization`ヘッダーで`Bearer`トークンとして渡します。
4. CorgeaがIdPの公開鍵でトークンの署名を検証し、`iss`、`aud`、`appid`/`cid`クレームが登録済みの設定と一致することを確認します。

## Corgea CLIでJWTを利用する

CLIログインフローでJWTアクセストークンを直接利用できます:

```bash theme={null}
corgea login YOUR_JWT_TOKEN
```

または環境変数で設定することもできます:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export CORGEA_TOKEN="your-jwt-access-token"
  corgea login
  ```

  ```powershell Windows theme={null}
  $env:CORGEA_TOKEN="your-jwt-access-token"
  corgea login
  ```
</CodeGroup>

## CorgeaでのJWT認証の設定

**Settings → Integrations**に移動し、**JWT Authentication**セクションの\*\*+ Add\*\*をクリックします。

<Card>
  <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/corgae_jwt_token_form.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=4e2279f885450dc9756704ae02ef498a" style={{ borderRadius: '0.5rem' }} alt="JWT認証設定フォームを追加Corgea" width="2796" height="2116" data-path="images/jwt_token/corgae_jwt_token_form.png" />
</Card>

以下の項目に記入してください:

| フィールド               | 説明                                              |
| ------------------- | ----------------------------------------------- |
| **名前**              | この構成の記述ラベル(例: `Entra CICD Pipeline`)。           |
| **発行者**             | トークン発行者のURLはアクセストークン内の `iss` クレームと一致しなければなりません。 |
| **オーディエンス**         | アクセストークンの `aud` クレームと一致しなければなりません。              |
| **許可されたアプリケーションID** | 1行につき1つのクライアントIDを使い、この構成を使用できるアプリケーションです。       |

<Info>
  [jwt.io](https://jwt.io)を使ってIdPからアクセストークンをデコードし、`iss`、`aud`、`appid`/`cid`の正確な値を確認してからフォームに記入してください。
</Info>

**提供者固有の値:**

* **Entra ID発行者**: `https://sts.windows.net/{your-tenant-id}/`
* **Entra IDオーディエンス**:アプリのApplication ID URI（例:`api://{client_id}`）。Entraの**Expose an API**で設定します
* **Okta発行者**: `https://{domain}.okta.com/oauth2/default`
* **Oktaオーディエンス**: `api://default` (またはカスタム認証サーバーオーディエンス)

## Microsoft Entra ID設定

<Steps>
  <Step title="Entraでアプリケーションを登録する">
    [Azure portal](https://portal.azure.com)で、**Microsoft Entra ID → App registrations → New registration**に移動します。アプリに分かりやすい名前（例:`corgea-cicd`）を付けて登録します。
  </Step>

  <Step title="APIを公開し、Application ID URIを設定します">
    アプリの登録で**Expose an API**を開きます。**Application ID URI**を設定または確認します — これがこのアプリで発行されるトークンの`aud`クレームとなります。

    <Card>
      <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/entra_expose_an_api.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=d04b83470b69fca5190511bef80e3129" style={{ borderRadius: '0.5rem' }} alt="Expose an API in Microsoft Entra" width="6054" height="2320" data-path="images/jwt_token/entra_expose_an_api.png" />
    </Card>

    Application ID URI(例: `api://5d63c8f0-c9a8-4195-90ee-a9e27e4510b8`)をコピーしてください。これはCorgeaの **オーディエンス** として入力されます。
  </Step>

  <Step title="クライアントシークレットを作成する">
    **Certificates & secrets → New client secret**を開きます。説明と有効期限を設定し、**Add**をクリックします。

    <Card>
      <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/entra_client_secret.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=e09e3cdc9aed42edd27ba14d6c294a0d" style={{ borderRadius: '0.5rem' }} alt="Microsoft Entraでクライアントシークレットを追加" width="5798" height="2372" data-path="images/jwt_token/entra_client_secret.png" />
    </Card>

    **シークレットの値**をコピーします。この値は一度しか表示されないため、CI/CDのシークレットストアなどに安全に保存してください。
  </Step>

  <Step title="アクセストークンを要求">
    システムはクライアントの認証フローを使ってEntraにトークンを要求しています:

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      curl -X POST \
        https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
        -d "grant_type=client_credentials" \
        -d "client_id={client-id}" \
        -d "client_secret={client-secret}" \
        -d "scope=api://{client-id}/.default"
      ```

      ```powershell Windows theme={null}
      Invoke-RestMethod -Method Post `
        -Uri "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" `
        -Body @{
          grant_type    = "client_credentials"
          client_id     = "{client-id}"
          client_secret = "{client-secret}"
          scope         = "api://{client-id}/.default"
        }
      ```
    </CodeGroup>

    レスポンスには`access_token`が含まれています。Corgeaを呼ぶ際にはこれをベアラートークンとして渡してください:

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      curl -H "Authorization: Bearer {access_token}" https://www.corgea.app/api/...
      ```

      ```powershell Windows theme={null}
      Invoke-RestMethod -Uri "https://www.corgea.app/api/..." `
        -Headers @{ Authorization = "Bearer {access_token}" }
      ```
    </CodeGroup>

    <Note>
      プライベートデプロイの場合は `https://www.corgea.app` を `https://your_instance.corgea.app` に置き換えてください。
    </Note>
  </Step>

  <Step title="Corgeaに設定を登録">
    Corgeaの**Add JWT Auth Configuration**フォームに次の値を入力します。

    * **発行者**: `https://sts.windows.net/{your-tenant-id}/`
    * **オーディエンス**:ステップ2のアプリケーションID URI(例: `api://5d63c8f0-...`)
    * **Allowed Application ID**:アプリ登録の**Application (client) ID**

    **Add**をクリックして保存します。
  </Step>
</Steps>

## Postmanとのテスト

CurlよりGUIを好む場合は、PostmanでトークンリクエストやAPI呼び出しを直接テストできます。

**curlコマンドをインポートする**

Postmanでは、上記のcurlコマンドをリクエストに変換できます。左上の**Import**をクリックしてcurlコマンドを貼り付けると、メソッド、URL、ヘッダー、ボディが自動的に入力されます。

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_import_curl.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=d634e6065afdb582aa09a69b9a21ff5f" style={{ borderRadius: '0.5rem' }} alt="Postmanにcurlコマンドをインポートする方法" width="2026" height="1202" data-path="images/jwt_token/postman_import_curl.png" />
</Card>

**アクセストークンのリクエスト**

`tenant-id`、`client_id`、`client_secret`、`scope`をボディ欄に記入し、リクエストを送信します。レスポンスの`access_token` 値をコピーしてください。

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_request_access.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=eb94f562884a32bb361dbd23206c03b7" style={{ borderRadius: '0.5rem' }} alt="クライアント認証情報を使ったPostmanでのアクセストークンのリクエスト" width="2400" height="2066" data-path="images/jwt_token/postman_request_access.png" />
</Card>

**トークンを使ってCorgea APIを呼び出します**

Corgeaエンドポイントへの新しいリクエストを作成します。**Authorization**タブで、Typeを**Bearer Token**に設定し、`access_token`を貼り付けます。

<Card>
  <img src="https://mintcdn.com/corgea/9RMZY-Ts5g1RCFSA/images/jwt_token/postman_call_api_with_token.png?fit=max&auto=format&n=9RMZY-Ts5g1RCFSA&q=85&s=66c68bafb415fa42282f6225d50bcd9f" style={{ borderRadius: '0.5rem' }} alt="Postmanでベアラートークンで Corgea API に電話をかける" width="2522" height="2462" data-path="images/jwt_token/postman_call_api_with_token.png" />
</Card>

<Note>
  もし会社がアウトバウンドネットワークアクセスを制限しているなら、プロキシの設定が必要かもしれません。Postmanで **設定→プロキシ** に行き、企業プロキシを追加します。curlの場合は、 `HTTPS_PROXY` 環境変数を設定するかパス `--proxy https://your-proxy:port`。
</Note>

## トークンの検証

Corgeaを設定する前に [jwt.io](https://jwt.io) を使ってアクセストークンをデコードしてください。トークンをデバッガに貼り付け、 **デコード済みペイロード** を確認して、 `iss`、 `aud`、 `appid` の値を確認してください。

<Card>
  <img src="https://mintcdn.com/corgea/shid6yjMRFa2jrlq/images/jwt_token/jwt_io.png?fit=max&auto=format&n=shid6yjMRFa2jrlq&q=85&s=d00c729ec30d74b31bd448b410e67ca0" style={{ borderRadius: '0.5rem' }} alt="jwt.io で JWT トークンを解読してISSおよびAUDクレームを検証する" width="2776" height="2326" data-path="images/jwt_token/jwt_io.png" />
</Card>

強調された `aud` と `iss` フィールドは、Corgeaが受信リクエストの検証時に確認するものです。

## トラブルシューティング

* **401 Unauthorized**: jwt.io でトークンをデコードし、 `iss`、 `aud`、 `appid` がCorgea JWT認証設定の値と正確に一致していることを確認します。
* **ローテーション後にトークンが拒否された場合**:クライアントシークレットをローテーションした場合、新しいシークレットがCI/CD環境で更新されていることを確認してください。Corgeaの設定自体は、トークンクレームを検証するため変更する必要がありません。
* **複数環境**:Corgeaで各アプリケーションや環境(例:ステージングと本番環境)ごとに、異なるクライアントIDを持つ異なるアプリ登録を用いて、別々のJWT認証設定を作成します。

### ネットワーク接続の問題

トークン要求やAPI呼び出しが接続エラーで失敗した場合は、これらのコマンドを使ってファイアウォールやプロキシがトラフィックをブロックしているかどうかを調べてください。

<CodeGroup>
  ```bash macOS / Linux theme={null}
  # Check DNS resolution
  nslookup login.microsoftonline.com
  nslookup www.corgea.app

  # Check TCP connectivity on port 443
  nc -zv login.microsoftonline.com 443
  nc -zv www.corgea.app 443

  # Trace the network path
  traceroute login.microsoftonline.com

  # Test with verbose curl output (shows TLS handshake and redirect chain)
  curl -v https://login.microsoftonline.com

  # Test through a proxy if required
  curl -v --proxy https://your-proxy:port https://login.microsoftonline.com
  ```

  ```powershell Windows theme={null}
  # Check DNS resolution
  Resolve-DnsName login.microsoftonline.com
  Resolve-DnsName www.corgea.app

  # Check TCP connectivity on port 443
  Test-NetConnection -ComputerName login.microsoftonline.com -Port 443
  Test-NetConnection -ComputerName www.corgea.app -Port 443

  # Trace the network path
  tracert login.microsoftonline.com

  # Test with verbose curl output
  curl.exe -v https://login.microsoftonline.com

  # Test through a proxy if required
  curl.exe -v --proxy https://your-proxy:port https://login.microsoftonline.com
  ```
</CodeGroup>

TCP接続テストが失敗したり、tracerouteが内部ホップで停止した場合は、ネットワークやセキュリティチームに連絡して、アウトバウンドHTTPS(ポート443)を `login.microsoftonline.com` ・ `www.corgea.app`できるようにします。