Okta API Bearer 認証

Okta によって発行された OAuth 2.0 Bearer token を使用して、Halo API へのプログラムによるアクセスを認証します。

概要​

Halo は API-Access service を通じて REST API を公開しています。すべての API リクエストには、Authorization header に有効な Bearer token を含める必要があります。token は、OAuth 2.0 Client Credentials flow（machine-to-machine）を使用して Okta から取得します。

このガイドでは、Halo API-Access service の Identity Provider として Okta を設定し、その後 Bearer token 認証で統合をテストする手順を説明します。

前提条件​

• API-Access service が設定された稼働中の Halo deployment
• 管理者アクセス権を持つ Okta organization
• Halo 用に設定された Okta authorization server（Okta Authorization Server を参照）
• API クライアントから Okta と Halo API エンドポイントの両方へのネットワークアクセス

セットアップ​

Okta で API クライアントを登録する​

マシンツーマシン アプリケーションを作成する​

1. Okta Admin Console にログインします。
2. Applications -> Applications -> Create App Integration -> API Services に移動します。

3. 適切な App integration 名を指定します。例: Glasswall Halo API

DPoP（proof of possession）を無効にする​

4. アプリケーションのGeneralタブ -> General Settingsセクションに移動し、Editをクリックします。
5. Proof of possessionの下で、Require Demonstrating Proof of Possession (DPoP) header in token requestsのチェックを外します。
6. 保存します。

注: Okta では、API Services アプリケーションでデフォルトで DPoP が有効になっています。DPoP はトークンをクライアントの暗号鍵にバインドし、トークンのリプレイ攻撃を防止します。ただし、Halo API-Access service は現在 DPoP トークン検証をサポートしていないため、Bearer token authentication を機能させるにはこれを無効にする必要があります。

クライアント認証情報を設定する​

7. Client IDを控え、Client Secretを生成します。

   export CLIENT_ID="<your-client-id>"
   export CLIENT_SECRET="<your-client-secret>"
   

セキュリティに関する注記: クライアントシークレットは secrets manager（例: Azure KeyVault）を使用して安全に保管してください。シークレットをソース管理にコミットしないでください。

ロールを設定する（任意）​

8. API クライアントがライセンス管理エンドポイントへの書き込みアクセスを必要とする場合は、認可サーバーで role クレームが設定され、Admin 値がそのクライアントにマッピングされていることを確認してください（API Roles を参照）。

注: role クレームがない場合、API はデフォルトで User ロールになります。各ロールがアクセスできる内容の詳細については、API Roles to Action Mapping を参照してください。

issuer URI と audience をメモする​

9. 前提手順で設定した認可サーバーから:

   export OKTA_ISSUER_URI="https://<your-okta-domain>/oauth2/<authorization-server-id>"
   export VALID_AUDIENCE="api://halo"
   

API クライアント用のアクセスポリシーを追加する​

10. 認可サーバーの Access Policies タブに移動します（Security -> API -> 認可サーバーを選択 -> Access Policies）。
11. Add a new access policy:
    • 名前: 例 API Client Access
    • 説明: 例 Access policy for Halo API clients
    • 割り当て先: 上で作成した API Services クライアント（手順 2 のアプリケーション名 glasswall-halo-api で検索）
12. Add a rule:
    • 名前: 例 Allow API Clients
    • Grant type: Client Credentials
    • その他の設定はデフォルトのままにするか、必要に応じてトークンの有効期間を調整してください。

注: Client Credentials grant のアクセスポリシーは、どのクライアント（client_id による）がトークンを要求できるかを制御します。このフローにはユーザーコンテキストがないため、グループメンバーシップは適用されません。API へのアクセスは、secrets manager を通じて client_id と client_secret を保持できる対象を制限することで保護してください。

Okta 用に API-Access サービスを設定する​

cdrplatform-api-access Helm chart は、Okta 認可サーバーによって発行された Bearer token を検証するように設定する必要があります。この chart は、認証設定を configuration values キーの下で公開します。

設定をデプロイする​

Note: The Authority and ValidIssuer must both be set to the Okta issuer URI. The API-Access service uses Authority to discover the JWKS (JSON Web Key Set) for token signature validation, and ValidIssuer to verify the iss claim in the token.

export HALO_DOMAIN=<your-halo-domain>
helm upgrade --install cdrplatform-api-access cdrplatform-api-access --reuse-values \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__Authority="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="${VALID_AUDIENCE:?}" \
  --set strategy.type="Recreate" \
  --set ingress.enabled=true \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="${HALO_DOMAIN:?}" \
  --atomic

複数の audience（任意）​

複数の API クライアントまたはアプリケーションが、異なる audience で Halo API にアクセスする必要がある場合は、追加の ValidAudiences エントリを追加します:

  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://halo-api" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__1="<second-client-id>" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__2="<third-client-id>"

Halo API の使用​

Bearer トークンを取得する​

Client Credentials フロー（マシン間）​

このフローは、ユーザー操作が不要な自動化システム、CI/CD パイプライン、およびサービス間連携に使用します。

export TOKEN_ENDPOINT="${OKTA_ISSUER_URI}/v1/token"

トークンをリクエストします:

curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api"

レスポンス例:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "halo.api"
}

トークンを抽出します:

export ACCESS_TOKEN=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api" | jq -r '.access_token')

APIリクエストを認証する​

すべてのAPIリクエストのAuthorizationヘッダーにBearer tokenを含めます:

export HALO_API_URL="https://<your-halo-domain>"

認証を確認する​

保護されたendpointでテストします。tokenなしのリクエストは401を返し、有効なtokenありのリクエストは200を返すはずです:

# Without token - expect 401
curl -s -o /dev/null -w "%{http_code}" \
  "${HALO_API_URL}/api/v1/policies"

# With token - expect 200
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${HALO_API_URL}/api/v1/policies"

例: 処理のためにファイルを送信する​

curl -s -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "file=@/path/to/document.pdf" \
  "${HALO_API_URL}/api/v1/rebuild/file" \
  --output rebuilt_document.pdf

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