Reporting Data API への認証

アプリケーションから OpenLM Platform のレポートデータを読み取るには、Reporting Data API に対して認証します。このガイドは、OpenLM Reporting へのアクセスが必要な外部およびクライアント側のインテグレーター向けです。Reporting Data API は認証に OAuth 2.0 を使用します。

認証の仕組み

Reporting Data API からデータを読み取るには、OpenLM Identity Server で認証し、短期間有効な JSON Web Token（JWT）アクセストークンを受け取り、そのトークンをすべての API リクエストで Bearer 認証情報として送信します。

フローは次の 3 ステップです。

1. Client ID + Client Secret  ──▶  2. POST /connect/token  ──▶  3. Call the API
   (issued to your service)         (Identity Server)

これはサーバー間 (server-to-server) フローです。ユーザーのサインインやブラウザーのリダイレクトはありません。アプリケーションは自分自身として認証します。

前提条件

認証して API を呼び出すには、次のものが必要です。

必要なもの	値または取得元
Client ID	お客様ごとに発行されるクライアント。
Client Secret	クライアントとともに発行されます。秘密として扱い、決してコミットしないでください。
Identity Server ベース URL {IDENTITY_URL}	https://cloud-us.openlm.com/identity（prod-us）または https://cloud-eu.openlm.com/identity（prod-eu）。
ベース URL {BASE_URL}	https://cloud-us.openlm.com（prod-us）または https://cloud-eu.openlm.com（prod-eu）。
スコープ	openlm.reporting-data-api-service.scope
Reporting Data API ベース URL {API_BASE_URL}	{BASE_URL}/api/reportingdataapi

注意

このクライアントは client_credentials グラントをサポートします。アクセストークンは JWT で、有効期間は 3,600 秒（1 時間）です。Client ID の末尾は、クライアントが属するお客様のグローバル一意識別子（GUID）で、トークンはそのお客様を customer_name クレームに含みます。

クライアント認証情報を生成する

インテグレーションは Client ID で識別され、Client Secret で認証されます。これらの値は、サインイン後に OpenLM Identity ページで自分で生成します。お客様ごとに個別のクライアントがプロビジョニングされるため、生成される Client ID にはお客様 ID が含まれます。

Identity ページを開く

OpenLM アカウントでサインインした後、ブラウザーで OpenLM Identity ページを開きます。

• prod-us: https://cloud-us.openlm.com/identity
• prod-eu: https://cloud-eu.openlm.com/identity

新しいクライアントを生成する

新しいクライアントを生成するには、次の手順を実行します。

1. Identity ページのナビゲーションメニューで、Management、Authorization の順に選択します。
2. 新しいクライアントを追加します。
3. Add Client Type フォームで、Select Client Type を ReportingDataApi に設定します。
4. クライアントの Description を入力します。
5. Save を選択します。

Client ID と Client Secret をコピーする

クライアントを生成したら、両方の値をすぐにコピーするか、JSON をダウンロードします。

• Client ID
• Client Secret（作成時にのみ表示されます）

Client Secret を安全に保管する

Client Secret は、クライアントを生成したときに一度だけ表示されます。紛失した場合は、新しいクライアントを生成してください。シークレットはシークレットマネージャーまたは環境変数に保存し、ソースにハードコードしたりリポジトリにコミットしたりしないでください。

以降の手順で値を使用できるように、環境変数としてエクスポートします。

export OPENLM_CLIENT_ID="<your-client-id>"
export OPENLM_CLIENT_SECRET="<your-client-secret>"
export OPENLM_IDENTITY_URL="https://<your-base-url>/identity"

トークンエンドポイントを確認する

Identity Server は OpenID Connect ディスカバリードキュメントを公開しています。正確なトークンエンドポイントを確認するには、次の URL にリクエストします。

GET {IDENTITY_URL}/.well-known/openid-configuration

該当するフィールドは token_endpoint で、次のように解決されます。

{IDENTITY_URL}/connect/token

ディスカバリーは一度だけ実行すれば十分です。トークンエンドポイントのパス（/connect/token）は安定しています。

アクセストークンをリクエストする

grant_type=client_credentials を指定して、トークンエンドポイントに POST を送信します。

リクエスト（curl）

次のコマンドを実行します。

curl -X POST "$OPENLM_IDENTITY_URL/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$OPENLM_CLIENT_ID" \
  -d "client_secret=$OPENLM_CLIENT_SECRET" \
  -d "scope=openlm.reporting-data-api-service.scope"

レスポンス

レスポンスにアクセストークンが含まれます。

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "openlm.reporting-data-api-service.scope"
}

access_token を取り出します。これは JWT です。デコードして（例: jwt.io で）、customer_name、name、email、role などのクレームを確認できます。

トークンを使用して Reporting Data API を呼び出す

トークンをすべてのリクエストで Authorization: Bearer ヘッダーとして送信します。サポートされるクエリの完全な一覧については、Reporting Data API のクエリを参照してください。レポートクエリはデフォルトで直近 90 日間のローリング期間を対象とします。レポート期間のルールも同ページに記載しています。

リクエストの例

次のコマンドを実行します。

curl -X POST "{API_BASE_URL}/graphql" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ licenseUsage(first: 25) { totalCount pageInfo { hasNextPage endCursor } nodes { user_name feature_name vendor start_time_utc } } }" }'

トークンの有効期間と更新

トークンの有効期間には次の点が適用されます。

• アクセストークンの有効期間は 1 時間（3,600 秒、expires_in の値）です。
• client_credentials フローはリフレッシュトークンを発行しません。トークンの有効期限が近づいたら、「アクセストークンをリクエストする」の手順を繰り返して新しいトークンを取得します。
• トークンをメモリにキャッシュし、expires_in の値を追跡して、API 呼び出しのたびにではなく有効期限の少し前に再取得します。

トラブルシューティング

次の表に、よくある症状、考えられる原因、対処を示します。

症状	考えられる原因	対処
400 invalid_client	Client ID または Secret が間違っているか、シークレットが別の環境のものです。	認証情報がその環境の Identity Server と一致していることを確認します。
400 invalid_scope	スコープのスペルが間違っています。	正確に openlm.reporting-data-api-service.scope を使用します。
API からの 401 Unauthorized	トークンが欠落または期限切れか、オーディエンスが間違っています。	トークンを再取得し、Authorization: Bearer <token> ヘッダーがあることを確認します。
403 Forbidden	トークンは有効ですが、そのテナントまたはリソースに対する権限がありません。	customer_name クレームまたは X-Customer-Name ヘッダーを確認します。
トークンが機能した後、約 1 時間で失敗する	トークンが期限切れになりました。	「アクセストークンをリクエストする」の手順で新しいトークンを取得します。

Identity 設定リファレンス

次の表に、このクライアントの Identity Server の設定を示します。

設定	値
クライアントシークレットの要否	必須
スコープ	openlm.reporting-data-api-service.scope
アクセストークンの種類	JWT
アクセストークンの有効期間	3,600 秒（1 時間）
トークンクレーム	name, email, customer_name, role
トークンエンドポイント	{IDENTITY_URL}/connect/token
ディスカバリー	{IDENTITY_URL}/.well-known/openid-configuration

関連ページ

詳細については、次のページを参照してください。

• Reporting Data API のクエリ: エンドポイントと GraphQL クエリの完全なカタログ。
• Reporting Data API フィールドリファレンス: 各クエリが返すフィールド。