XDR GraphQL APIの認証🔗
専用のAPIクライアント認証情報を作成するには、4部構成のクライアント認証情報の作成ガイドの手順に従ってください。デバイス認証を使用する場合は、デバイス認証セクションを参照してください。
パート1: クライアント認証情報の作成🔗
アプリケーションやスクリプトがSecureworks® Taegis™ XDR GraphQL APIにアクセスするには、クライアント認証情報を生成してログインできるようにする必要があります。これらはユーザーのユーザー名とパスワードに似ていますが、自動化専用であり、他のログイン認証情報と同様に保護する必要があります。この手順は一度だけ実施してください。すでにクライアント認証情報を作成済みの場合は、それを再利用し、パート2: アクセストークンの生成に進んでください。
XDRのクライアント認証情報は、対象テナントでテナントアナリストまたはテナント管理者のロールを持つXDRユーザーによって作成できます。認証情報は作成された1つのテナント、およびリージョンでのみ有効です。アプリケーションが複数のリージョンにアクセスする必要がある場合は、各リージョンごとに個別のクライアント認証情報を作成する必要があります。
重要
デフォルトでは、クライアント認証情報にはテナントアナリストロールが付与され、通常のアナリストユーザーが実行できるアクションのみ実行可能です。一部のXDR APIでは追加の権限が必要であり、テナントアナリストロールでは失敗する場合があります。多くの場合、これらの追加権限はドキュメント化されていません。APIの失敗理由が不明な場合、権限不足が原因である可能性があることに注意してください。デフォルトより多くの権限を持つクライアント認証情報を作成する必要がある場合は、下記の特権クライアント認証情報の作成を参照してください。
地域
XDR APIにアクセスするためのURLは、お客様の環境が展開されているリージョンによって異なる場合があります。
- US1—
https://api.ctpx.secureworks.com - US2—
https://api.delta.taegis.secureworks.com - US3—
https://api.foxtrot.taegis.secureworks.com - EU1—
https://api.echo.taegis.secureworks.com - EU2—
https://api.golf.taegis.secureworks.com
このXDR APIドキュメントの例では、https://api.ctpx.secureworks.com を使用しています。別のリージョンをご利用の場合は、適切なURLに置き換えてください。
注意
Python SDKを使用した認証方法および関連する使用例については、XDR Python SDK認証を参照してください。
注意
1時間あたりにテナントごとで作成できるクライアント認証情報の数は10件までに制限されています。
API認証情報の追加🔗
XDRテナントのAPI認証情報を生成するには、UIまたはCLIの2つの方法があります。より簡便なUI経由の手順を推奨します。
Taegis XDR UIでのAPI認証情報管理は、CLIによる手動作成プロセスに代わるものです。
注意
API認証情報の設定は、テナント管理者またはテナントアナリストのロールを持つユーザーのみが可能です。下記の方法で生成されたAPI認証情報には、デフォルトでテナントアナリストロールの権限が付与されます。必要に応じて特権クライアント認証情報の作成の詳細を参照してください。
新しいAPI認証情報を追加するには:
- Taegis Menuからテナント設定 → API認証情報の管理を選択します。
- ページ右上の認証情報の追加を選択します。
- API認証情報追加モーダルで、新しい認証情報の名前を入力します。
- 送信を選択します。
送信後、システムが新しいクライアントIDとシークレットを生成します。
重要
クライアントシークレットは作成直後の1回のみ表示されます。必ずコピーして安全に保存してください。再度取得することはできません。
以下の手順は、クライアント認証情報作成の従来手順です。新しい手順はUI経由タブに記載されています。従来手順も引き続きサポートされていますが、セキュリティと利便性向上のため新しいワークフローの利用を推奨します。
サブスクリプションページでテナントIDを確認🔗
テナントIDを確認するには、Taegis Menuからテナント設定を選択し、サブスクリプションを選択します。
認証情報の手動作成🔗
クライアント認証情報を手動で作成するには、以下を実施してください。
- ChromeでXDRにログインします。
- Chromeデベロッパーツールを開きます。
-
Consoleタブで以下を入力します。
-
access_tokenがクリップボードにコピーされます。access_tokenトークンはChromeデベロッパーツールのConsoleには表示されず、クリップボードにのみコピーされます。コマンドの戻り値はundefinedです。 - コマンドラインターミナルで、以下のコマンドを実行してクライアント認証情報を作成します。クリップボードから
your_access_tokenの部分に貼り付け、your_tenant_idにはテナントID、your_unique_application_nameにはアプリケーションを識別する一意の名前を入力してください。 - 新しいクライアント認証情報が返されます。レスポンスから
client_idとclient_secretの値を保存してください。アプリケーションがXDRシステムにログインする際に必要です。これらはユーザーのユーザー名とパスワードに相当するため、他のログイン認証情報と同様に保護してください。
以下の例は、デフォルト権限でクライアント認証情報を作成する方法を示しています。追加権限が必要な場合は、特権クライアント認証情報の作成（オプション）を参照してください。
注意
このページの例では、cURLコマンドラインツールを使用してXDR APIリクエストを発行しています。他のHTTPリクエスト発行ツールや方法も利用可能ですので、使い慣れたものを使用してください。
重要
CreateClient APIコールにはレート制限があります。1時間あたりにテナントごとで作成できるクライアント認証情報の数は10件までに制限されています。
Linuxでの認証情報作成🔗
export ACCESS_TOKEN="your_access_token"
export TENANT_ID="your_tenant_id"
curl -g \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Context: $TENANT_ID" \
-H "Content-type: application/json" \
-X POST \
-d '{"query": "mutation createClient($name: String!, $roles: [ID!]) { createClient(name: $name, roles: $roles) { client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret } }", "variables": {"name": "your_awesome_app_name"}}' \
https://api.ctpx.secureworks.com/graphql
Windowsでの認証情報作成🔗
set ACCESS_TOKEN=your_access_token
set TENANT_ID=your_tenant_id
curl -H "Authorization: Bearer %ACCESS_TOKEN%" -H "X-Tenant-Context: %TENANT_ID%" -H "Content-type: application/json" https://api.ctpx.secureworks.com/graphql -d "{\"query\": \"mutation createClient($name: String!, $roles: [ID!]) { createClient(name: $name, roles: $roles) { client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret } }\", \"variables\": {\"name\": \"your_awesome_app_name\"}}"
ここでyour_access_tokenは上記ステップ4でコピーしたアクセストークン、your_tenant_idはアクセスしたいXDRのテナントID、your_unique_application_nameは任意の一意なアプリケーション名です。
ヒント
{"error":["Existing client in tenant"]}と表示された場合は、アプリケーション名を変更してください。アプリケーション名は一意である必要があります。
以下のようなレスポンスが得られます。
{
"data": {
"createClient": {
"client": {
"client_id": "<YOUR_CLIENT_ID>",
"created_at": "2023-03-03T20:58:40.24986Z",
"created_by": "0000",
"environment": "production",
"id": "<UUID>",
"name": "your_awesome_app_name",
"role_assignments": [
{
"expires_at": null,
"id": "<UUID>",
"role_id": "a4903f9f-465b-478f-a24e-82fa2e129d2e",
"role_name": "TenantAnalyst",
"tenant_id": "50530"
}
],
"roles": "tenantAnalyst",
"tenant_id": "<TENANT_ID>",
"updated_at": "2023-03-03T20:58:40.24986Z",
"updated_by": "0000"
},
"client_secret": "<YOUR_CLIENT_SECRET>"
}
}
}
特権クライアント認証情報の作成（オプション）🔗
デフォルトのテナントアナリスト以外のロールでクライアント認証情報を作成する必要がある場合のみ、このセクションが必要です。すでにデフォルトロールでクライアント認証情報を作成済みの場合は、パート2に進んでください。
下記の表で必要なロールIDを確認してください。
| ロール名 | ロールID |
|---|---|
| 管理者 | ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068 |
| アナリスト | a4903f9f-465b-478f-a24e-82fa2e129d2e |
| 対応者 | a72dace7-4536-4dbc-947d-015a8eb65f4d |
| 監査役 | ace1cae4-59fd-4fd1-9500-40077dc529a7 |
Linuxでの特権認証情報作成🔗
export ACCESS_TOKEN="your_access_token"
export TENANT_ID="your_tenant_id"
curl -g \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Context: $TENANT_ID" \
-H "Content-type: application/json" \
-X POST \
-d '{"query": "mutation createClient($name: String!, $roles: [ID!]) { createClient(name: $name, roles: $roles) { client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret } }", "variables": {"name": "your_awesome_app_name", "roles": ["<desired_role_id>"]}}' \
https://api.ctpx.secureworks.com/graphql
Windowsでの特権認証情報作成🔗
set ACCESS_TOKEN=your_access_token
set TENANT_ID=your_tenant_id
set ROLE_ID=desired_role_id
curl -H "Authorization: Bearer %ACCESS_TOKEN%" -H "X-Tenant-Context: %TENANT_ID%" -H "Content-type: application/json" https://api.ctpx.secureworks.com/graphql -d "{\"query\": \"mutation createClient($name: String!, $roles: [ID!]) { createClient(name: $name, roles: $roles) { client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret } }\", \"variables\": {\"name\": \"your_awesome_app_name\", \"roles\": [\"%ROLE_ID%\"]}}"
ヒント
setxを使うことで環境変数をセッション間で永続化できます。環境変数を設定した後は新しいcmdシェルを開く必要がある場合があります。以下の例を参照してください。
認証情報作成スクリプト例🔗
以下の2つのサンプルスクリプトは、API認証情報の作成を簡単に行うためのガイドです。これらのスクリプトは、TaegisのAPIクライアント認証情報管理を支援します。ご利用のOSやプラットフォームに応じてPython版とPowerShell版があります。
現在のバージョン: 1.0
パート2: アクセストークンの生成🔗
パート1: クライアント認証情報の作成で作成したクライアント認証情報を使って、アプリケーションはXDRシステムにログインし、アクセストークンを生成します。このアクセストークンは、他のすべてのXDR APIリクエストに含めて、アプリケーションの識別と有効な認証の証明に使用します。アクセストークンの有効期間は数時間のみのため、必要に応じてこのプロセスを繰り返す必要があります。
重要
新しいトークンが必要なたびに新しいクライアント認証情報を作成しないでください。クライアント認証情報はアプリケーションの存続期間中有効です。
以下の例は、cURLツールを使ってこのプロセスを手動で完了する方法を示しています。プロセスを理解するためにご利用ください。多くの場合、アプリケーションは他の方法でこれらのリクエストを発行できますが、必要なリクエスト内容は同じです。
このステップを実施するには、以下の3つの情報が必要です。
- 認証URL:
https://api.ctpx.secureworks.com/auth/api/v2/auth/token - パート1で取得したclient_id
- パート1で取得したclient_secret
必要に応じて、認証URLのサーバー名をリージョンに合わせて置き換えてください。
your_client_idおよびyour_client_secretは、パート1で作成したクライアント認証情報です。
UNIX系システムでのトークン生成🔗
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"
curl --basic -u "$CLIENT_ID:$CLIENT_SECRET" -H "Content-Type: application/json" -d '{"grant_type":"client_credentials"}' https://api.ctpx.secureworks.com/auth/api/v2/auth/token
Windowsシステムでのトークン生成🔗
set CLIENT_ID=your_client_id
set CLIENT_SECRET=your_client_secret
curl --basic -u "%CLIENT_ID%:%CLIENT_SECRET%" -H "Content-Type: application/json" -d "{\"grant_type\":\"client_credentials\"}" https://api.ctpx.secureworks.com/auth/api/v2/auth/token
your_client_idおよびyour_client_secretは、パート1で作成したクライアント認証情報です。
このコマンドは、以下のような結果を返します。
{"access_token":"your_unique_token_value","expires_in":36000,"expiry":"2022-04-22T09:40:06.677Z","token_type":"Bearer"}
アプリケーションは、以降のすべてのAPIリクエストでyour_unique_token_valueを使用します。トークンはexpiry値に示された時刻まで有効であり、その後は新しいトークンを生成する必要があります。
パート3: XDR APIサービスの呼び出し🔗
アプリケーション用の有効なアクセストークンがある場合、XDR APIへのリクエストを発行できます。認証には、パート2で生成したアクセストークンをHTTPリクエストのAuthorizationヘッダーに含めます。トークンは「ベアラートークン」と呼ばれ、ヘッダー値の先頭にBearerを付けてトークンを記載します。正しい形式の認証ヘッダー例:
your_unique_token_valueは、パート2で生成したトークンです。
API呼び出し例として、サービスのバージョンをクエリする方法を示します。これはあくまで例であり、認証プロセスの一部ではありません。
Linuxでサービスのバージョン取得🔗
export ACCESS_TOKEN="your_unique_token_value"
curl -H "Authorization: Bearer $ACCESS_TOKEN" "Content-Type: application/json" https://api.ctpx.secureworks.com/assets/version
Windowsでサービスのバージョン取得🔗
set ACCESS_TOKEN=your_unique_token_value
curl -H "Authorization: Bearer %ACCESS_TOKEN%" "Content-Type: application/json" https://api.ctpx.secureworks.com/assets/version
レスポンス例🔗
{"tag":"0.1.11","revision":"1332dad18827c3d6e60b801e6b4b44737e8f11f6","timestamp":"2019-10-02T06:01:28Z"}
アクセストークンの利用方法とパート1で使用したコマンドの類似性に注目してください。ユーザーのアクセストークンとクライアント認証情報で作成したトークンは、XDR APIにとっては同等ですが、API自動化用のトークン作成には必ずクライアント認証情報を使用してください。
パート4: アプリケーションでOAuth2クライアントを利用（オプション）🔗
XDRで手動認証する代わりに、アプリケーションで事前パッケージ化されたOAuth2クライアントソフトウェアを利用する方が便利な場合があります。これらのパッケージは一般的に認証プロセスを自動で処理し、アクセストークンの有効期限が近づくと自動更新も行います。OAuth2の「クライアント認証情報」フローをサポートするソフトウェアであれば利用可能です。OAuth2クライアントの初期化には、パート2で示した3つの情報（認証URL、クライアントID、クライアントシークレット）が必要です。
以下のいずれかの例を、クライアント認証情報を事前に設定したコマンドラインターミナルで実行してください。
LinuxでのOAuth2🔗
WindowsでのOAuth2🔗
例: Goクライアント🔗
この例では、OAuth2 clientcredentialsパッケージを使用します。
package main
import (
"context"
"fmt"
"io"
"github.com/gobuffalo/helpers/env"
"golang.org/x/oauth2/clientcredentials"
)
func main() {
clientConfig := clientcredentials.Config{
ClientID env.EnvOr("CLIENT_ID", ""),
ClientSecret: env.EnvOr("CLIENT_SECRET", ""),
TokenURL "https://api.ctpx.secureworks.com/auth/api/v2/auth/token",
}
httpClient := clientConfig.Client(context.TODO())
response, err := httpClient.Get("https://api.ctpx.secureworks.com/assets/version")
if err != nil {
// handle error
}
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
fmt.Println(string(body))
}
注意
OAuthライブラリに独自の事前設定済みHTTPクライアントを渡すこともできますが、その場合はクライアントのTransportのみがコピーされ、他の設定は無視されます。これは既知の問題であり、予期しない動作につながる可能性があります。これを回避するには、以下の例のように必要なオプションを明示的にOAuthクライアントに設定してください。
myContext := // your input context
myHttpClient := // your specific HTTP client setup
ctx = context.WithValue(myContext, oauth2.HTTPClient, myHttpClient)
oauthHttpClient := clientConfig.Client(ctx)
// set all other required values here!
oauthHttpClient.Timeout = myHttpClient.Timeout
oauthHttpClient.Jar = myHttpClient.Jar
oauthHttpClient.CheckRedirect = myHttpClient.CheckRedirect
例: Pythonクライアント🔗
この例では、requests-oauthlibパッケージを使用します。実行前にこのパッケージをインストールする必要がある場合があります。XDR Python SDKを使用している場合は、認証を自動で処理します。以下は生のPython例です。
サンプルプログラム:
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session
import os
client_id=os.environ.get('CLIENT_ID')
client_secret=os.environ.get('CLIENT_SECRET')
client = BackendApplicationClient(client_id=client_id)
oauth_client = OAuth2Session(client=client)
token = oauth_client.fetch_token(token_url='https://api.ctpx.secureworks.com/auth/api/v2/auth/token', client_id=client_id, client_secret=client_secret)
print(token)
r = oauth_client.get("https://api.ctpx.secureworks.com/assets/version")
print(r.content)
これをclient_example.pyというファイル名で保存し、実行します。
いずれの例も、パート3で使用したcURLコマンドと同じ結果を返します。
{"tag":"0.1.11","revision":"1332dad18827c3d6e60b801e6b4b44737e8f11f6","timestamp":"2019-10-02T06:01:28Z"}
クライアント認証情報の検索🔗
クライアント認証情報の監査やメタデータの確認が必要な場合は、clientsクエリを利用できます。
また、XDR Python SDKでクライアント認証情報を検索することも可能です。
出力例🔗
[Client(id='c373d68a-fdca-476f-5b48-92ed5804dc53', name='docs-test-client-adcghzxc', client_id='b42USvw1jm5fk3Y2VqoAWSyG4CF47Ek5', roles='tenantAnalyst', tenant_id='xxxxx', created_at='2023-04-17T14:26:44.821551Z', updated_at='2023-04-17T14:26:44.821551Z', created_by='0000', updated_by='0000', environment='production', role_assignments=[ClientRoleAssignment(id='ca5928cf-7481-416a-8c53-1de4197f3593', tenant_id='xxxxx', role_id='a4903f9f-465b-478f-a24e-82fa2e129d2e', role_name='TenantAnalyst', expires_at=None)])]
デバイス認証🔗
デバイス認証は、ノートブックやPython SDKで、CLIプロンプト経由でアプリケーションの利用をデバイスに認可するための認証方式です。
CLI経由でアプリケーションにアクセスする場合、利用中のデバイスはブラウザが推奨インターフェースでないため入力制約があります。そのため、必要に応じてアプリケーションへのアクセスを有効にするためにデバイス認証が必要となる場合があります。
Python SDKにアクセスする際は、以下の手順に従ってください。
- CLIからPython SDKにアクセスする際、プロンプトが表示されたらTaegisのユーザー名（専用認証情報ではありません）を入力します。
- URLが発行されます。URLをブラウザにコピーすると、デバイスコードが画面に表示されます。
注意
デバイスコードに注意してください。この例ではデバイスコードがURLの末尾にありますが、実装によっては別途表示される場合もあります。
- 表示されたデバイスコードが、提供されたURLの末尾と一致していることを確認し、確認を選択します。
ブラウザで以下のメッセージが表示され、操作が成功したことが確認できます。
- 必要に応じてMFAまたはSSOでXDRにログインします。これでCLIインスタンスが定義されたユーザートークンを利用できるように認可されます。
クライアント認証情報の検索🔗
query clients($name: String, $clientIDs: [String] = ["<CLIENT_ID>"], $tenantID: ID, $roleIDs: [ID], $tenantIDs: [ID], $page: Int, $perPage: Int)
{
clients(name: $name, clientIDs: $clientIDs, tenantID: $tenantID, roleIDs: $roleIDs, tenantIDs: $tenantIDs, page: $page, perPage: $perPage)
{
id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment
}
}
クライアントシークレットのリセット🔗
同じクライアントIDを保持したままクライアントシークレットをリセットしたい場合は、rotateClientSecretミューテーションを使用して新しいクライアントシークレットを生成できます。ID入力にはUUIDまたはclient_idのいずれかを指定できます。また、クライアントシークレットも必要です。APIは新しいシークレット作成前に古いシークレットを検証します。
mutation rotateClientSecret($id: ID! = "c373d68a-fdca-476f-5b48-92ed5804dc53", $secret: String = "<CLIENT_SECRET>")
{
rotateClientSecret(id: $id, secret : $secret)
{
client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret
}
}
クライアントシークレットの強制リセット🔗
ユーザーが古いシークレットが無効、または不明な場合でも、既存のクライアントIDに対してforceRotateClientSecretを使用してクライアントシークレットをリフレッシュできます。このAPIは、テナントのTenantAdminユーザー、Secureworks管理者、またはSecureworksオペレーションユーザーのみが呼び出せます。
mutation forceRotateClientSecret($id: ID! = "c373d68a-fdca-476f-5b48-92ed5804dc53")
{
forceRotateClientSecret(id: $id)
{
client { id name client_id roles role_assignments { id tenant_id role_id role_name expires_at } tenant_id created_at updated_at created_by updated_by environment } client_secret
}
}
クライアントの削除🔗
クライアント認証情報の利用が終了したら、deleteClientミューテーションを使用して認証情報を無効化できます。ID入力にはUUIDまたはclient_idのいずれかを指定できます。