コンテンツにスキップ

ユーザーAPIの利用開始🔗

重要

進める前に、API認証の手順を完了し、動作するclient_idとclient_secretを取得してください。

地域

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に置き換えてください。

XDR ユーザーAPIを使用して、テナントユーザーの招待、更新、無効化、取得が可能です。

テナントへのユーザー招待🔗

パート1: 招待に必要な要件🔗

ユーザーをテナントに招待するには、主に4つの値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

tenant_id: このユーザーを招待する対象テナントのID。

注意

招待リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でユーザーを招待する権限が必要です。

email_address: テナントに招待したいユーザーのメールアドレス。

role_id: 招待するユーザーに割り当てるロールのID。例：テナント管理者（ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068）やテナントアナリスト（a4903f9f-465b-478f-a24e-82fa2e129d2e）など。

パート2: 招待リクエスト🔗

ロールID:

  • テナントアナリスト—a4903f9f-465b-478f-a24e-82fa2e129d2e
  • テナント管理者—ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068
  • テナント監査役—ace1cae4-59fd-4fd1-9500-40077dc529a7
  • テナント対応者—a72dace7-4536-4dbc-947d-015a8eb65f4d
mutation inviteTDRUser($invite: TDRUserInviteInput! = {email: "invitee_email_address", role_id: "invitee_role_id"})
{
    inviteTDRUser(invite: $invite)
    {
        id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified
    }
}

ここで、invitee_email_addressはユーザーのemail_address、invitee_role_idは割り当てるロールのIDであり、パート1で説明されています。

リクエストのボディに含めるgraphqlミューテーションに加え、x-tenant-contextヘッダーを招待先のtenant_idに設定する必要があります。また、access_tokenはAuthorizationヘッダーに設定してください。

cURL🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export EMAIL_ADDRESS="invitee_email_address"
export ROLE_ID="invitee_role"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header "Content-Type: application/json" \
--data '{"query": "mutation { inviteTDRUser(invite:{ email: \"$EMAIL_ADDRESS\" role_id: \"$ROLE_ID\"  }){id email }}"}'

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idはユーザーを招待するテナントのID、invitee_email_addressは招待するユーザーのemail_address、invitee_roleは新規ユーザーに割り当てるrole_idです。いずれもパート1で説明されています。

パート3: 招待レスポンス🔗

招待レスポンス例🔗

{
    "data": {
        "inviteTDRUser": {
            "email": "customer.name@octolabs.io",
            "id": "828bda7c-a9d0-435e-8b70-f099aa55dccb"
        }
    }
}

inviteTDRUserミューテーションのレスポンスには、emailとidフィールドが含まれます。emailフィールドは入力したinvitee_email_addressと一致し、招待が送信されるアドレスです。idフィールドは招待されたユーザーのユーザーIDであり、今後の更新や無効化などで参照できます。

ユーザーの取得🔗

パート1: 取得に必要な要件🔗

ユーザーの詳細を取得するには、以下の3つの値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

user_id: 詳細を取得したいユーザーの一意のID。

tenant_id: 対象ユーザーが所属するテナントのID。

注意

取得リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でユーザーを読み取る権限が必要です。

パート2: 取得リクエスト🔗

既存ユーザーの詳細取得は、users APIへのgraphqlリクエストでtdruserクエリを呼び出して行います。

GraphQL🔗

query tdruser($id: ID! = "user_id", $excludeDeactivatedRoleAssignments: Boolean, $includeMaskedRelatedUsers: Boolean)
{
    tdruser(id: $id, excludeDeactivatedRoleAssignments: $excludeDeactivatedRoleAssignments, includeMaskedRelatedUsers: $includeMaskedRelatedUsers)
    {
        id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified
    }
}

ここで、user_idは取得対象ユーザーのIDです。

リクエストのボディに含めるgraphqlクエリに加え、x-tenant-contextヘッダーを対象ユーザーが所属するtenant_idに設定する必要があります。また、access_tokenはAuthorizationヘッダーに設定してください。

cURL🔗

上記GraphQLクエリで列挙されたすべてのフィールドが取得可能です。このcURL例では、例を簡潔にするためユーザーのemailフィールドのみを取得しています。

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export TARGET_USER_ID="user_id"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header 'Content-Type: application/json' \
--data "{\"query\":\"query{ tdruser(id:\\\"$TARGET_USER_ID\\\"){ email }}\"}"

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idは対象ユーザーのテナントID、user_idは取得したいユーザーのIDです。

ユーザーの更新🔗

パート1: ユーザー更新に必要な要件🔗

ユーザーの詳細を更新するには、以下の3つの値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

user_id: 更新対象（ターゲットユーザー）の一意のID。

tenant_id: 対象ユーザーが所属するテナントのID。

パート2: ユーザー更新リクエスト🔗

ユーザーの更新は、users APIへのgraphqlリクエストでupdateTDRUserミューテーションを呼び出し、更新対象ユーザーのフィールドを_patch_で指定して行います。

注意

更新リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でユーザーを更新する権限が必要です。

ユーザーの詳細を更新するために_patch_で設定可能な変数はいくつかあります。現在_patch_で更新可能なフィールドは以下の通りです。

  • given_name
  • family_name
  • phone_number
  • secondary_phone_number

GraphQL🔗

mutation updateTDRUser($id: ID! = "user_id", $patch: TDRUserUpdateInput! = {phone_number:"+10000000000", secondary_phone_number:"+000000000000"})
{
    updateTDRUser(id: $id, patch: $patch)
    {
        id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified
    }
}

ここで、user_idは更新対象ユーザーのID（パート1で説明）、new_primary_phone_numberおよびnew_secondary_phone_numberはターゲットユーザーの新しい電話番号です。

リクエストのボディに含めるgraphqlミューテーションに加え、x-tenant-contextヘッダーを対象ユーザーが所属するtenant_idに設定する必要があります。また、access_tokenはAuthorizationヘッダーに設定してください。

cURL🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export TARGET_USER_ID="user_id"
export NEW_PRIMARY_PHONE_NUMBER="new_primary_phone"
export NEW_SECONDARY_PHONE_NUMBER="new_secondary_phone"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header 'Content-Type: application/json' \
--data "{\"query\":\"mutation { updateTDRUser(id:\\\"$TARGET_USER_ID\\\", patch:{ phone_number:\\\"$NEW_PRIMARY_PHONE_NUMBER\\\" secondary_phone_number:\\\"$NEW_SECONDARY_PHONE_NUMBER\\\"}) { id }}\"}"

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idは対象ユーザーのテナントID、user_idは更新したいユーザーのID、new_primary_phoneおよびnew_secondary_phoneはユーザーの新しい電話番号です。

このcURLリクエスト例ではユーザーの電話番号を_patch_していますが、必要に応じて上記の他の_patch_フィールドに置き換えることも可能です。

ユーザーアクセスの取り消し🔗

パート1: 取り消しに必要な要件🔗

ユーザーアクセスの取り消しは、ユーザーのロール割り当てを削除することで行います。ユーザーがテナント内でロール割り当てが0になると、そのテナントへのアクセス権がなくなります。すべてのテナントでロール割り当てがない場合、そのアカウントはdeactivatedとしてマークされ、ユーザーはXDRへのログインができなくなります。

ユーザーのロール割り当てを取り消すには、以下の値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

user_id: ロール割り当てを取り消したいユーザー（ターゲットユーザー）の一意のID。

tenant_id: 対象ユーザーが所属し、ロールを取り消す対象となるテナントのID。

role_id: 取り消すロールのID。

パート2: ロール割り当て削除リクエスト🔗

ロール割り当ての削除は、users APIへのgraphqlリクエストでremoveTDRUserRolesミューテーションを呼び出して行います。

注意

ロール削除リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でユーザーを更新する権限が必要です。

ロールID:

  • テナントアナリスト—a4903f9f-465b-478f-a24e-82fa2e129d2e
  • テナント管理者—ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068
  • テナント監査役—ace1cae4-59fd-4fd1-9500-40077dc529a7
  • テナント対応者—a72dace7-4536-4dbc-947d-015a8eb65f4d

GraphQL🔗

mutation removeTDRUserRoles($id: ID! = "user_id", $roles: [ID!]! = ["role_id"])
{
    removeTDRUserRoles(id: $id, roles: $roles)
    {
        id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified
    }
}

ここで、user_idは対象ユーザーのID、role_idはユーザーから削除するロールのIDであり、いずれもパート1で説明されています。

リクエストのボディに含めるgraphqlミューテーションに加え、x-tenant-contextヘッダーを対象ユーザーが所属するtenant_idに設定する必要があります。また、access_tokenはAuthorizationヘッダーに設定してください。

cURL🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export TARGET_USER_ID="user_id"
export ROLE_ID="role_id"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header 'Content-Type: application/json' \
--data "{\"query\":\"mutation { removeTDRUserRoles(id:\\\"$TARGET_USER_ID\\\", roles:[\\\"$ROLE_ID\\\"]) {id }}\"}"

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idは対象ユーザーのテナントID、user_idはロールを取り消したいユーザーのID、role_idはユーザーから削除したいロールのIDです。

このcURLリクエスト例ではユーザーの単一ロールを削除していますが、ミューテーションの入力roles配列に複数のロールIDを指定することで、1回のリクエストで複数ロールの削除も可能です。

ユーザーの検索🔗

パート1: 検索に必要な要件🔗

ユーザーを検索するには、以下の2つの値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

tenant_id: ユーザーを検索する対象テナントのID。

注意

取得リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でユーザーを読み取る権限が必要です。

パート2: 検索リクエスト🔗

ユーザー検索は、users APIへのgraphqlリクエストでtdrUsersSearchクエリを呼び出して行います。

GraphQL🔗

query tdrUsersSearch($filters: TDRUsersSearchInput = {tenantStatus="!Deactivated"})
{
    tdrUsersSearch(filters: $filters)
    {
        result_count results { id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified } cursor_pos pageOffset has_next_page total_count
    }
}

ここで、filtersは検索したい条件（例：tenantStatus）を含むフィルターリスト、resultsは取得したい各ユーザーの項目を指定します。

ユーザー検索時に利用可能なフィルターは以下の通りです。

フィルター 例 説明
email email:"test@secureworks.com" フィルター対象のメールアドレス。SQLの'like'マッチングを使用。メールアドレスにはアンダースコアが含まれる場合がありますが、アンダースコアはエスケープされワイルドカードとしては使用されません。
emails emails:["test1@secureworks.com","test2@secureworks.com"] フィルター対象のメールアドレスリスト。emailと同じマッチング方式。
role_IDs role_IDs:["58c0dd7f-a171-4701-931d-d53654d68089", "260f9d74-1a57-48cf-adca-a30778fc3879"] ユーザーに割り当てられているロールID。
tenantStatus tenantStatus:"!Deactivated" ユーザーステータス。'!'で始まる場合はNOTマッチャーを使用。アクティブユーザーのみをリクエストする場合に便利です：'!Deactivated'。
perPage perPage:1 ページネーションのページサイズ。-1（デフォルト）はページネーションなし。
cursorPos cursorPos:"test@secureworks.com" ページネーションの最終カーソル位置。値は結果セットで最後に返されたユーザーのメールアドレス。pageOffsetを使用しない場合のみ利用。
pageOffset pageOffset:1 ページネーションのレコードオフセット。指定するとcursorPosを上書き。

リクエストのボディに含めるgraphqlクエリに加え、x-tenant-contextヘッダーを対象ユーザーが所属するtenant_idに設定する必要があります。また、access_tokenはAuthorizationヘッダーに設定してください。

cURL🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header 'Content-Type: application/json' \
--data '{"query":"query {tdrUsersSearch(filters:{tenantStatus:\"!Deactivated\"}) {result_count cursor_pos has_next_page total_count results {id user_id status email last_login}}}"}'

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idはユーザー一覧を取得するテナントのIDです。

指定ロールを持つテナントユーザーの検索cURL例🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export ROLE_ID="role_id"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header 'Content-Type: application/json' \
--data "{\"query\":\"query { tdrUsersSearch(filters:{tenantStatus:\\\"\!Deactivated\\\",role_IDs:[\\\"$ROLE_ID\\\"]}) {result_count cursor_pos has_next_page total_count results { id user_id status email last_login } }}\"}"

ここで、your_access_tokenはお客様のベアラーaccess_token、tenant_idはユーザー一覧を取得するテナントのID、role_idはフィルター対象のロールIDです。

事前認証済みユーザーの登録🔗

新しいUsers APIにより、パートナーは標準の招待プロセスや登録通知メールを経ずに、自身のテナントに新規ユーザーを追加できるようになりました。

パート1: ユーザー登録要件🔗

  • パートナーまたは割り当て先子テナントで有効なSSO接続が必要
  • ユーザーのメールドメインはSSO接続と一致している必要あり
  • パートナーおよびそのテナントのみ利用可能（Secureworksテナントは対象外）
  • 新規テナント管理者ユーザーは標準の招待プロセスが必要で、このAPIでは利用できません

ユーザーをテナントに登録するには、主に4つの値が必要です。

access_token: API認証の手順に従って取得したXDRアクセストークン。

tenant_id: このユーザーを登録する対象テナントのID。

注意

登録リクエストに使用するaccess_tokenには、対象テナント（tenant_id）内でcreatePreRegisteredUserユーザーを作成する権限が必要です。テナント管理者ロールにはこの権限があります。

email_address: テナントに登録したいユーザーのメールアドレス。

role_id: 登録ユーザーに割り当てるロールのID。例：テナント監査役（ace1cae4-59fd-4fd1-9500-40077dc529a7）やテナントアナリスト（a4903f9f-465b-478f-a24e-82fa2e129d2e）など。

パート2: ユーザー登録リクエスト🔗

パートナーユーザー登録GraphQLミューテーション例🔗

mutation registerPartnerUser($registrationInput: PartnerRegistrationInput! = {email: "user_email_address", role_id: "user_role_id", role_expires_at: "role_expiration_time", language: "user_preferred_lang", given_name: "user_first_name", family_name: "user_last_name", phone_number: "user_phone_number", timezone: "user_timezone"})
{
    registerPartnerUser(registrationInput: $registrationInput)
    {
        id id_uuid user_id user_id_v1 created_at updated_at created_by updated_by last_login invited_date registered_date deactivated_date status status_localized email email_normalized family_name given_name phone_number phone_extension secondary_phone_number secondary_phone_extension roles tenants { id } tenants_v2 { id role } accessible_tenants { id name name_normalized enabled allow_response_actions actions_approver expires_at environments { name enabled } labels { id tenant_id name value } services { id name description } is_partner parent } role_assignments { id tenant_id role_id deactivated role_name role_display_name expires_at created_at updated_at allowed_environments } environments eula { date version } timezone tenant_status tenant_status_localized entitlement_channel allowed_entitlement_channels masked community_role is_scwx is_partner preferred_language pre_verified
    }
}

cURL🔗

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="tenant_id"
export EMAIL_ADDRESS="user_email_address"
export ROLE_ID="user_role"
curl --request POST \
--url https://api.ctpx.secureworks.com/graphql \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "x-tenant-context: $TENANT_ID" \
--header "Content-Type: application/json" \
--data "{\"query\":\"mutation { registerPartnerUser(registrationInput:{ email: \\\"$EMAIL_ADDRESS\\\" role_id: \\\"$ROLE_ID\\\"  }){id email }}\"}"

ミューテーション内のオプションフィールドは、必要に応じてregistrationInputフィールドに追加できます。