コンテンツにスキップ

テナントAPIの利用開始🔗

重要

先にAPI認証の手順を完了し、動作するclient_idおよびclient_secretを取得してください。

地域

XDR テナントAPIへアクセスするためのURLは、お客様の環境が展開されているリージョンによって異なります。

  • US1— https://api.tenants.ctpx.secureworks.com/public/query
  • US2— https://api-tenants.delta.taegis.secureworks.com/public/query
  • US3— https://api-tenants.foxtrot.taegis.secureworks.com/public/query
  • EU— https://api-tenants.echo.taegis.secureworks.com/public/query

ここでの例はすべて https://api.tenants.ctpx.secureworks.com/public/query を使用しています。別のリージョンの場合は適切に置き換えてください。

Secureworks® Taegis™ XDR のパブリックテナントAPIを使用して、テナント情報の検索、作成、更新が可能です。

テナントAPIへのアクセス🔗

テナントAPIは、テナントグラフおよびパートナーデータグラフとの連携に使用できます。他のGraphQL APIとは異なり、tenants-apiは通常のAPIとは異なるエントリポイントからアクセスする必要があります（上記のリージョンを参照）。

このAPIには、他のAPIと同様に Authorization : Bearer {token} で認証する必要があります。このAPIへの認可は以下のルールに従います。

  • テナント（Tenant:read）への読み取り権限を持つクライアント/ユーザートークンは、自分のテナント、または関連するパートナー/親テナントへのアクセス権を持っている必要があります。
  • フィルター（例：name、id、labelsなど）を指定しなくても、常にクエリに対して読み取り権限が適用されます。お客様がアクセスできるテナントのみが返されます。
  • Secureworksの担当者やシステムは、サポートが有効な場合、子テナントにアクセスできる場合があります。
  • mutationによる更新には、特別な Tenant:update または Tenant:create 権限が必要です。
  • パートナー/親テナントのTenantAdminであれば、その階層内のすべてのテナントの読み取りおよび更新が可能です。

テナントグラフの概要🔗

ほとんどのqueriesおよびmutationsはTenantオブジェクトを返します。完全なスキーマはGraphQLからイントロスペクトできますが、主な要素は以下の通りです。

# Not all fields listed for brevity

type Tenant {
    # The tenant ID, an int like: 12345
    id: ID!
    # Created and updated times, e.g. : 2022-03-23T15:15:37Z
    created_at: Time
    updated_at: Time
    # The tenant's name
    name: String!
    # A list of labels assigned to this tenant.
    labels: [TenantLabel!]
    # A list of environments indicating where the tenant is enabled at.
    environments: [Environment!]
    # A date when the tenant expires.
    expires_at: Time
    # Contains hierarchy and subscription information.
    partnership: Partnership
    # Either Secureworks support users have access to read this tenant.
    support_enabled: Boolean!
    ...
}

# Partnership contains some important information about this tenant's partner hierarchy.

type Partnership {
    # Indicates the parent tenant id, this is your partner tenant.
    parent: ID
    # If true, indicates that the tenant is a partner (parent)
    is_partner: Boolean!
    # Subscriptions that the partner assigned to the tenant.
    subscriptions: [PartnerSubscription!]
}

テナントのクエリ🔗

query tenants(TenantsQuery!)を使用して、お客様がアクセスできるテナントのリストを取得できます。結果はページネーションメタデータでラップされているため、簡単に結果をスクロールできます。

# Not all fields shown; use query introspection to retrieve the full schema.

input TenantsQuery {
    # Start results after this id
    cursorPos: ID
    # How many results to return
    maxResults: Int
    # If provided (and not cursorPos is provided) pageNum allows getting a specific result page (maxResults = per page)
    pageNum: Int
    # optional name (supports wildcard %) or tenant id
    name: String
    # optional ids to return, useful when only a few tenants are needed and ids are known
    ids: [ID!]
    # optional filter for environments
    environmentFilter: TenantEnvironmentFilter
    # optional label filter
    labelFilter: TenantLabelFilter
    # optional partner service (subscription) filter
    withPartnerSubscription: String
    # optional partnership filter
    partnership: PartnershipFilter
    # Return tenants who were created during the specified time range
    createdTimeFilter: TimeFilter
    # Return tenants who were modified during the specified time range
    modifiedTimeFilter: TimeFilter
    # Allows to filter by is_partner flag
    isPartner: Boolean
    # Sets the order for the query results, ID by default
    orderBy: TenantOrderField = Id
    # Sets the order direction for the results, Asc by default
    orderDir: OrderDir = asc
    # optional support selector to find tenants or partners with support enabled
    withSupport: Boolean
}

type TenantResults {
    # The actual query results
    results : [Tenant!]!
    # Indicates the last cursor for cursor based pagination.
    cursorPos : ID
    # Represents the number of records returned.
    count: Int!
    # Indicates if there are more records after the requested page/cursor
    hasMore: Boolean!
    # Represents the total number of records when offset pagination is used (page / per page)
    totalCount: Int
}

tenants-apiへのすべてのリクエストは、以下の形式である必要があります。

  • POST 'https://api.tenants.ctpx.secureworks.com/query'
  • Content-Type: application/json ヘッダー（コンテンツタイプネゴシエーション用）
  • Authorization: Bearer {ACCESS_TOKEN} クライアントおよびユーザー用に取得したアクセストークン

GraphQL🔗

query tenants($tenantsQuery: TenantsQuery! = {maxResults: 10})
{
    tenants(tenantsQuery: $tenantsQuery)
    {
        results { id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot } cursorPos count hasMore totalCount
    }
}

cURL🔗

# Get 10 results from the second page

curl --location --request POST 'https://api.tenants.ctpx.secureworks.com/query' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query tenants ($tenantsQuery: TenantsQuery!) { tenants (tenantsQuery: $tenantsQuery) { count totalCount results { id name created_at support_enabled partnership { subscriptions { id service_id created_at updated_at name description } } labels { name value } } }}","variables":{"tenantsQuery":{"maxResults":10}}}'

{
  "data": {
    "tenants": {
      "count": 10,
      "totalCount": 24834,
      "cursorPos": "aWR8MTAwMTc=",
      "results": [
        {
          "id": "10008"
        }
      ]
    }
  }
}

テナントのページネーション🔗

GraphQL🔗

ページ番号🔗

query tenants($tenantsQuery: TenantsQuery! = {maxResults: 10, pageNum: 2})
{
    tenants(tenantsQuery: $tenantsQuery)
    {
        results { id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot } cursorPos count hasMore totalCount
    }
}

カーソル🔗

query tenants($tenantsQuery: TenantsQuery! = {maxResults: 10, cursor_pos: "aWR8MTAwMzc="})
{
    tenants(tenantsQuery: $tenantsQuery)
    {
        results { id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot } cursorPos count hasMore totalCount
    }
}

ユースケースに応じて、両方のページネーションモードを使い分けることができます。結果のソート順を変更するとカーソルの計算も変わるため、順序を変更した場合は必ず正しい値をcursorPosに渡してください。

テナントのフィルタ🔗

フィルターは組み合わせて使用できます。以下のいずれか（またはすべて）のフィルターが利用可能です。

  • name
  • ids
  • forHierarchies
  • environmentFilter
  • labelFilter
  • withService
  • withServices
  • withPartnerSubscription
  • withPartnerSubscriptions
  • partnership
  • createdTimeFilter
  • modifiedTimeFilter
  • isPartner
  • withSupport
query tenants($tenantsQuery: TenantsQuery! = {maxResults: 10, ids=["xxxxx"], name="%my name%", forHierarchies=["id"], environmentFilter: {name: "echo", enabled: true}, labelFilter: {label_name: "testing"}, withPartnerSubscription: "%", withPartnerSubscription: ["%"], createdTimeFilter: {startTime: "2019-07-04T15:00:22", endTime: "2019-07-06T15:00:22Z"}})
{
    tenants(tenantsQuery: $tenantsQuery)
    {
        results { id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot } cursorPos count hasMore totalCount
    }
}

テナントのソート🔗

結果は以下のいずれかでソートできます。

  • Id
  • Name
  • CreatedAt
  • UpdatedAt

GraphQL🔗

query tenants($tenantsQuery: TenantsQuery! = {maxResults: 10, createdTimeFilter: {startTime: "2019-07-04T15:00:22", endTime: "2019-07-06T15:00:22Z"}, orderBy: CreatedAt, orderDir: desc})
{
    tenants(tenantsQuery: $tenantsQuery)
    {
        results { id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot } cursorPos count hasMore totalCount
    }
}

テナントの作成🔗

mutation createTenant(TenantCreateInput!)は、いくつかの制限のもとでパートナー上にテナントを作成します。

  • アクセス権のないパートナー（親テナント）上に子テナントを作成することはできません。
  • 新しいパートナーテナントを作成することはできません（Secureworksユーザーで適切なロールを持っている場合を除く）。
mutation createTenant($newTenant: TenantCreateInput! = {name: "New Tenant Name", partnerTenantID: "xxxxx", labels: {name: "partner_only_label_name", value: "label_value", owner_partner_tenant_id: "xxxxx"}, environments: ["echo", "pilot"]})
{
    createTenant(newTenant: $newTenant)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https://api.tenants.ctpx.secureworks.com/query' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation createTenant($newTenant: TenantCreateInput!) { createTenant (newTenant: $newTenant) {idpartnership {parent}environments {nameenabled}labels {namevalueowner_partner_tenant_id } } }","variables":{"newTenant":{"name":"New tenant name","partnerTenantID":"xxxxx","labels":[{"name":"partner_only_label_name","value":"label_value","owner_partner_tenant_id":"xxxxx"}],"environments":["echo","pilot"]}}}'

注意事項🔗

  • partnerTenantIDは親のパートナーテナントIDです。名前の通り、そのテナント（TenantAdminとして）へのアクセス権が必要です。
  • labelsのオーディエンスはowner_parent_tenant_idで制限できます。上記の例では、partner_only_label_nameはテナントxxxxxにアクセスできるトークンのみが閲覧可能です。現時点ではラベルの所有権は親テナントのみに設定できます。
  • environmentsは、この子テナントを有効化したい環境のリストを設定できます。この例では新しいテナントがechoとpilotで有効化されています。

テナント名の変更🔗

テナント名を変更するには、mutation updateTenant(TenantUpdateInput)を使用します。

GraphQL🔗

mutation updateTenant($tenantID: ID! = "xxxxx", $tenantUpdate: TenantUpdateInput! = {name: "Updated Tenant Name"})
{
    updateTenant(tenantID: $tenantID, tenantUpdate: $tenantUpdate)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https://api.tenants.ctpx.secureworks.com/query' \
--header 'Authorization: Bearer { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation updateTenant($tenantID: ID!, $updateInput: TenantUpdateInput!) { updateTenant (tenantID: $tenantID, tenantUpdate: $updateInput) { id name partnership { parent is_partner } environments { name enabled } labels { name value owner_partner_tenant_id } }}","variables":{"tenantID":xxxxx,"updateInput":{"name":"new tenant name"}}}'

テナント環境の管理🔗

テナント作成時には、少なくとも1つの環境で有効化されます。環境を変更するには、mutation updateTenant(TenantUpdateInput)を使用します。

GraphQL🔗

mutation updateTenant($tenantID: ID! = "xxxxx", $tenantUpdate: TenantUpdateInput! = {environments: [{name: "echo", enabled: false}, {name: "delta", enabled: true}]})
{
    updateTenant(tenantID: $tenantID, tenantUpdate: $tenantUpdate)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation updateTenant($tenantID: ID!, $updateInput: TenantUpdateInput!) { updateTenant (tenantID: $tenantID, tenantUpdate: $updateInput) { id name environments { name enabled } } }","variables":{"tenantID":xxxxx,"updateInput":{"environments":[{"name":"echo","enabled":true},{"name":"delta","enabled":false}]}}}'

ヒント

1回のリクエストで複数の環境を有効化・無効化できます。テナントは、少なくとも1つの環境で有効化されていればアクティブとみなされます。

テナントの無効化🔗

テナントを無効化するには、すべての環境で無効化するか、単にフィールド "disable" : true を設定します。どちらの方法でも同じ結果となります。

GraphQL🔗

mutation updateTenant($tenantID: ID! = "xxxxx", $tenantUpdate: TenantUpdateInput! = {disable: true})
{
    updateTenant(tenantID: $tenantID, tenantUpdate: $tenantUpdate)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS _TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation updateTenant($tenantID: ID!, $updateInput: TenantUpdateInput!) { updateTenant (tenantID: $tenantID, tenantUpdate: $updateInput) { id name enabled expires_at environments { name enabled } } }","variables":{"tenantID":xxxxx,"updateInput":{"disable":true,"clearExpiration":true}}}'

テナントの有効期限管理🔗

有効期限が設定されたテナントは、60日後に自動的に無効化されます。有効期限はmutation updateTenant(TenantUpdateInput)で変更できます。

GraphQL🔗

mutation updateTenant($tenantID: ID! = "xxxxx", $tenantUpdate: TenantUpdateInput! = {expiresAt: "2023-12-31T00:00:00Z"})
{
    updateTenant(tenantID: $tenantID, tenantUpdate: $tenantUpdate)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

有効期限のクリア🔗

GraphQL🔗

mutation updateTenant($tenantID: ID! = "xxxxx", $tenantUpdate: TenantUpdateInput! = {clearExpiration: true})
{
    updateTenant(tenantID: $tenantID, tenantUpdate: $tenantUpdate)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS _TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation updateTenant($tenantID: ID!, $updateInput: TenantUpdateInput!) { updateTenant (tenantID: $tenantID, tenantUpdate: $updateInput) { id name enabled expires_at environments { name enabled } } }","variables":{"tenantID":xxxxx,"updateInput":{"expiresAt":"2022-09-09T14:30:34Z"}}}'

テナントラベルの管理🔗

以下のミューテーションを使用して、テナント内のラベルを作成、更新、削除できます。

  • createTenantLabel(label_id ID!, label_input ID!: InputTenantLabel!): TenantLabel!、InputTenantLabel.owner_parent_tenant_idでラベルのオーディエンスを設定可能
  • updateTenantLabel(label_id ID!, tenant_id ID!, label_input: InputTenantLabel!): TenantLabel!
  • deleteTenantLabel(label_id: ID!, tenant_id: ID!): TenantLabel!

注意

一部のラベルは制限されており、変更や削除ができません。制限されたラベルを変更しようとすると、テナントAPIが通知します。

テナントラベルの作成🔗

所有するテナントに新しいラベルを作成するには：

GraphQL🔗

mutation createTenantLabel($tenant_id: ID! = "xxxxx", $label_input: InputTenantLabel! = {name: "test", value: "value"})
{
    createTenantLabel(tenant_id: $tenant_id, label_input: $label_input)
    {
        id tenant_id name value owner_partner_tenant_id
    }
}

cURL🔗

curl --location --request POST 'https://api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation createTenantLabel ($tenant_id: ID!, $label_input: InputTenantLabel!) { createTenantLabel (tenant_id: $tenant_id, label_input: $label_input) { id name value owner_partner_tenant_id } } ","variables":{"tenant_id":xxxxx,"label_input":{"value":"value","name":"test"}}}'

パートナーサブスクリプションの管理🔗

以下のミューテーションを使用して、利用可能なパートナーサブスクリプションおよび子テナントへのサブスクリプション割り当てを管理できます。

  • createSubscription(input: NewSubscription!): Service! で、子テナントに割り当て可能なサブスクリプションを作成
  • updateSubscription(input: SubscriptionUpdate!): Service! で、アクセス権のあるサブスクリプションの名称変更
  • deleteSubscription(id: ID!): Service! で、割り当てられていないサブスクリプションを削除（既に割り当てられている場合はエラー）
  • assignSubscription(tenant_id: ID!, subscription_id: ID!): Tenant! で、パートナー子テナントにサブスクリプションを設定
  • unassignSubscription(tenant_id: ID!, subscription_id: ID!): Tenant! で、パートナー子テナントからサブスクリプションを削除

GraphQL🔗

mutation assignSubscription($tenant_id: ID! = "xxxxx", $subscription_id: ID! = "1cb04358-0e00-4ffb-abc8-14ccbc7b42b0")
{
    assignSubscription(tenant_id: $tenant_id, subscription_id: $subscription_id)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL🔗

curl --location --request POST 'https://api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation($tenant_id: ID!, $subscription_id: ID!) { assignSubscription(tenant_id: $tenant_id, subscription_id: $subscription_id) { id } }","variables":{"tenant_id":"xxxxx","subscription_id":"1cb04358-0e00-4ffb-abc8-14ccbc7b42b0"}}'

注意事項🔗

  • subscription_idはサブスクリプション作成時に返されます。返されたid値がサブスクリプション割り当てIDであり、サブスクリプションの割り当て解除に使用できます。

Secureworksサポートの許可🔗

tenants-apiを使用して、以下のミューテーションでパートナー子テナントのサポートを有効化または無効化できます。

  • enableTenantSupport(tenantID: ID!): Tenant!
  • disableTenantSupport(tenantID: ID!): Tenant!

GraphQL🔗

mutation enableTenantSupport($tenantID: ID! = "xxxxx")
{
    enableTenantSupport(tenantID: $tenantID)
    {
        id created_at updated_at enabled name name_normalized domain domain_normalized description allow_response_actions actions_approver labels { id tenant_id name value owner_partner_tenant_id } environments { id created_at updated_at tenant_id name enabled } services { id created_at updated_at name description owner_tenant_id } expires_at partnership { parent is_partner subscriptions { id service_id name description created_at updated_at } child_tenants } support_enabled enabled_in_production enabled_in_pilot
    }
}

cURL サポート無効化🔗

テナントのサポートを無効化するには：

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: Bearer { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { disableTenantSupport (tenantID : \"xxxxx\") { id support_enabled } }","variables":{}}'

シングルサインオン接続の設定🔗

Taegis プラットフォームへの認証用にサードパーティIDプロバイダーを設定する場合、テナントAPIで行います。サポートされているのはSAMLプロバイダーのみで、本ガイドではプロバイダー設定に必要な手順を説明します。このSAML通信のシナリオでは、Taegis プラットフォームがサービスプロバイダーとなります。

GraphQL🔗

mutation createSSOConnection($newConnection: NewSSOConnectionInput!)
{
    createSSOConnection(newConnection: $newConnection)
    {
        id name type status externalName environment externalID tenantID updatedAt createdAt certName expiresAt notBefore issuer subject domains testers ssoConnectionParameters { postBackURL entityID metadataURL callbackURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signingCert signInEndpoint } azureADConnectionConfiguration { clientID clientSecret domain } }
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--header 'X-Tenant-Context: { TENANT_ID} ' \
--data '{"query":" mutation ($name: String!, $type: SSOConnectionType!, $domains: [String!]!, $testers: [String!]) { createSSOConnection(newConnection: { name: $name, type: $type, domains: $domains, testers: $testers }) { id name type status externalName externalID environment domains testers ssoConnectionParameters { postBackURL entityID metadataURL callbackURL } expiresAt createdAt updatedAt } }","variables":{"name": " { NEW_CONNECTION_NAME } ", "type": "saml", "domains": [" { EMAIL_DOMAIN1 } "], "testers": [" { TESTER1@EMAIL_DOMAIN1} "]}}'

注意事項🔗

  • 入力

    • name — 作成するSSO接続の名称。必須
    • type — 接続タイプ。samlである必要があります。必須
    • domains — この接続で認証を行うメールドメインのリスト。必須
    • testers — この接続のアーリーアダプターとなるテスターのリスト。任意

  • 出力

    • id — 接続の内部ID
    • type — 作成された接続タイプ。samlである必要があります。
    • createdAt — 接続が作成された日時
    • updatedAt — 最終更新日時
    • externalName — 接続の外部名（自動生成）
    • externalID — 接続の外部ID（自動生成）
    • domains — この接続を利用するメールドメインのリスト
    • testers — この接続をテストしているユーザーのリスト
    • status — この接続のステータス。現段階ではDraftである必要があります。他にTesting、Enabled、Disabledが選択可能です。
    • ssoConnectionParameters
      • postBackURL — IDプロバイダー側で設定するために使用。SAMLアサーションを受け取るコールバック（assertion consumer serviceとも呼ばれる）
      • entityID — IDプロバイダーに対するTaegis接続の識別子

postBackURLおよびentityIDは、次のステップに進む前にSAML IDプロバイダー側で設定されていることが一般的です。

SSO構成の取得🔗

getSSOConnectionConfigクエリは、SAMLサービスプロバイダー（Taegis）に必要な情報を取得します。このステップは、設定内容が正しいことを事前確認するために通常実施されます。

GraphQL🔗

query getSSOConnectionConfig($metadataURL: String = "metadata_url", $cert: String)
{
    getSSOConnectionConfig(metadataURL: $metadataURL, cert: $cert)
    {
        ssoConnectionConfiguration { samlConnectionConfiguration { signingCert signInEndpoint } azureADConnectionConfiguration { clientID clientSecret domain } } expiresAt notBefore issuer subject
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--header 'X-Tenant-Context: { TENANT_ID} ' \
--data '{"query":"query ($metadataURL: String, $cert: String) { getSSOConnectionConfig (metadataURL: $metadataURL, cert: $cert) { expiresAt notBefore issuer subject ssoConnectionConfiguration { samlConnectionConfiguration { signInEndpoint signingCert } } } }","variables":{"metadataURL": "{ METADATA_URL }"}}'

注意事項🔗

入力🔗
  • metadataURLはIDプロバイダーのメタデータURLを指定します。これは任意で、certとは排他的です。
  • certはIDプロバイダーの署名証明書です。他のデータが利用可能な場合は必須ではなく、利便性のために提供されています。これは任意で、metadataURLとは排他的です。
出力🔗
  • expiresAt — 署名証明書の有効期限
  • notBefore — 署名証明書の有効開始日
  • issuer — 署名証明書の発行者
  • subject — 署名証明書の発行対象
  • ssoConnectionConfiguration
    • samlConnectionConfigurationはmetadataURLが指定された場合に返されます。
      • signInEndpointは、TaegisがSSOユーザー認証のために呼び出すエンドポイント
      • signingCertは、メタデータURLから抽出されたIDプロバイダーの署名証明書

初期SSO接続構成の完了🔗

初期接続構成を完了するには、IDプロバイダーのメタデータURL、または署名証明書とサインインエンドポイントの組み合わせが必要です。正常に完了すると、接続のステータスはTestingに移行します。

GraphQL🔗

mutation updateSSOConnection($updatedConnection: UpdateSSOConnectionInput! = {id: "connection_id", connectionConfiguration: {samlConfiguration: {metadataURL: "metadata_url", signingCertName: "certificate_name", signingCert: "certificate", signInEndpoint: "sign_in_endpoint"}}})
{
    updateSSOConnection(updatedConnection: $updatedConnection)
    {
        id name type status externalName environment externalID tenantID updatedAt createdAt certName expiresAt notBefore issuer subject domains testers ssoConnectionParameters { postBackURL entityID metadataURL callbackURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signingCert signInEndpoint } azureADConnectionConfiguration { clientID clientSecret domain } }
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--header 'X-Tenant-Context: { TENANT_ID} ' \
--data '{"query":"mutation ($id: ID!, $signingCert: String, $signInEndpoint: String, $metadataURL: String, $certName: String) { updateSSOConnection ( updatedConnection: { id: $id, samlConfiguration: { metadataURL: $metadataURL, signingCert: $signingCert, signInEndpoint: $signInEndpoint, signingCertName: $certName } } ) { id name externalName externalID createdAt updatedAt type status domains testers certName notBefore expiresAt issuer subject ssoConnectionParameters { postBackURL entityID metadataURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signInEndpoint signingCert } } }}","variables":{"id": " { CONNECTION_ID } ", "metadataURL": " { METADATA_URL } ", "certName": "issuer.pem"}}'

注意事項🔗

入力🔗
  • id — 接続の内部ID。必須
  • samlConfiguration
    • metadataURL — IDプロバイダーの構成をダウンロードできるURL。任意。指定した場合、signingCert入力は無視されます。
    • signingCert — IDプロバイダーの署名証明書。任意。指定し、かつmetadataURLがない場合はsignInEndpointも指定が必要です。
    • signInEndpoint — SSOユーザー認証に使用するURL。任意ですが、signingCertを使用する場合は必須です。
    • signingCertName — 署名証明書のファイル名。過去に使用した証明書の識別用であり、ユーザーのローカルファイルシステムから証明書を取得するためには使用しません。任意
出力🔗
  • id — 接続の内部ID
  • name — 接続名
  • externalName — TaegisがSSO認証処理で使用する外部名
  • externalID — TaegisがSSO認証処理で使用する外部ID
  • createdAt — 接続作成日時
  • updatedAt — 最終更新日時
  • type — SSO接続タイプ。現在サポートされているのはSAMLのみ
  • status — 接続ステータス。リクエストが正常に完了するとTestingに移行
  • domains — この接続で認証するメールドメイン
  • testers — テスターのリスト
  • cerName — 更新リクエストで指定された場合、証明書ファイル名
  • notBefore — 署名証明書の有効開始日時
  • expiresAt — 署名証明書の有効期限
  • issuer — 署名証明書の発行者
  • subject — 署名証明書の発行対象
  • ssoConnectionParameters — サービスプロバイダー（Taegis）のSAML属性
    • postBackURL — IDプロバイダーからSAMLアサーションレスポンスを受け取るエンドポイント
    • entityID — Taegis SAMLエンティティの識別子
    • metadataURL — IDプロバイダーが今後TaegisのSAML構成をダウンロードするために使用できるURL（更新が必要な場合）
  • ssoConnectionIDPConfig — IDプロバイダーの構成
    • samlConnectionConfiguration
      • signInEndpoint — TaegisがSSOユーザー認証のために使用するエンドポイント
      • signingCert — IDプロバイダーの署名証明書

SSO接続の更新🔗

テストが完了したら、SSO接続をEnabledステータスにして、登録済みメールドメインで利用可能にする必要があります。他の属性（例：有効期限が近い場合の新しい署名証明書など）も調整が必要な場合があります。

GraphQL🔗

mutation updateSSOConnection($updatedConnection: UpdateSSOConnectionInput! = {id: "connection_id", status: "Enabled"})
{
    updateSSOConnection(updatedConnection: $updatedConnection)
    {
        id name type status externalName environment externalID tenantID updatedAt createdAt certName expiresAt notBefore issuer subject domains testers ssoConnectionParameters { postBackURL entityID metadataURL callbackURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signingCert signInEndpoint } azureADConnectionConfiguration { clientID clientSecret domain } }
    }
}

cURL🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--header 'X-Tenant-Context: { TENANT_ID} ' \
--data '{"query":" mutation ($id: ID!, $addTesters: [String!], $removeTesters: [String!], $addDomains: [String!], $removeDomains: [String!], $status: SSOConnectionStatus, $signingCert: String, $signInEndpoint: String, $metadataURL: String, $certName: String) { updateSSOConnection(updatedConnection: { id: $id, connectionConfiguration: { samlConfiguration: { signingCert: $signingCert, signInEndpoint: $signInEndpoint } } }) { id name type status externalName externalID environment domains testers expiresAt createdAt updatedAt ssoConnectionParameters { postBackURL entityID metadataURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signInEndpoint signingCert } } } }","variables":{"id": " { CONNECTION_ID } ", "status": "Enabled"}}'

注意事項🔗

入力🔗
  • id — 接続の内部ID。必須
  • status — 接続のステータスを更新。Enabled、Disabled、Testingが有効。任意
  • addTesters — 新たに追加するテスターの文字列配列。任意
  • removeTesters — 削除するテスターの文字列配列。任意
  • addDomains — 追加するメールドメインの文字列配列。任意
  • removeDomains — 削除するメールドメインの文字列配列。任意
  • samlConfiguration
    • metadataURL — IDプロバイダーの構成をダウンロードできるURL。指定した場合、signingCert入力は無視されます。任意
    • signingCert — IDプロバイダーの署名証明書。指定し、かつmetadataURLがない場合はsignInEndpointも指定が必要です。任意
    • signInEndpoint — SSOユーザー認証に使用するURL。任意ですが、signingCertを使用する場合は必須です。
    • signingCertName — 署名証明書のファイル名。過去に使用した証明書の識別用であり、ユーザーのローカルファイルシステムから証明書を取得するためには使用しません。任意
出力🔗
  • id — 接続の内部ID
  • name — 接続名
  • externalName — TaegisがSSO認証処理で使用する外部名
  • externalID — TaegisがSSO認証処理で使用する外部ID
  • createdAt — 接続作成日時
  • updatedAt — 最終更新日時
  • type — SSO接続タイプ。現在サポートされているのはSAMLのみ
  • status — 接続ステータス。リクエストが正常に完了するとTestingに移行
  • domains — この接続で認証するメールドメイン
  • testers — テスターのリスト
  • cerName — 更新リクエストで指定された場合、証明書ファイル名
  • notBefore — 署名証明書の有効開始日時
  • expiresAt — 署名証明書の有効期限
  • issuer — 署名証明書の発行者
  • subject — 署名証明書の発行対象
  • ssoConnectionParameters — サービスプロバイダー（Taegis）のSAML属性
    • postBackURL — IDプロバイダーからSAMLアサーションレスポンスを受け取るエンドポイント
    • entityID — Taegis SAMLエンティティの識別子
    • metadataURL — IDプロバイダーが今後TaegisのSAML構成をダウンロードするために使用できるURL（更新が必要な場合）
  • ssoConnectionIDPConfig — IDプロバイダーの構成
    • samlConnectionConfiguration
      • signInEndpoint — TaegisがSSOユーザー認証のために使用するエンドポイント
      • signingCert — IDプロバイダーの署名証明書

SSO接続の削除🔗

GraphQL🔗

mutation deleteSSOConnection($connectionID: ID! = "connection_id")
{
    deleteSSOConnection(connectionID: $connectionID)
    {
        id name type status externalName environment externalID tenantID updatedAt createdAt certName expiresAt notBefore issuer subject domains testers ssoConnectionParameters { postBackURL entityID metadataURL callbackURL } ssoConnectionIDPConfig { samlConnectionConfiguration { signingCert signInEndpoint } azureADConnectionConfiguration { clientID clientSecret domain } }
    }
}

cURL SSO構成削除例🔗

curl --location --request POST 'https:// api.tenants.ctpx.secureworks.com/public/query' \
--header 'Authorization: { ACCESS_TOKEN }' \
--header 'Content-Type: application/json' \
--header 'X-Tenant-Context: { TENANT_ID} ' \
--data '{"query":"mutation ($connectionID: ID!) { deleteSSOConnection(connectionID: $connectionID) { id name type status externalName externalID domains testers } }","variables":{"connectionID": " { CONNECTION_ID } "}}'

注意事項🔗

入力🔗
  • connectionID — 接続の内部ID。必須
出力🔗
  • id — 接続の内部ID
  • name — 接続名
  • type — SSO接続タイプ。現在サポートされているのはSAMLのみ
  • status — 接続ステータス。リクエストが正常に完了するとTestingに移行
  • externalName — TaegisがSSO認証処理で使用する外部名
  • externalID — TaegisがSSO認証処理で使用する外部ID
  • domains — この接続で認証するメールドメイン
  • testers — テスターのリスト