Authenticate Remote Agent with Workload Identity Federation

Supported in:

This document describes how to configure keyless authentication for Google SecOps Remote Agents using Workload Identity Federation (WIF). Workload Identity Federation eliminates the need to download, manage, and store long-lived service account JSON key files on remote agent host environments.

With Workload Identity Federation, Remote Agents running on external cloud providers, on-premises infrastructure, Kubernetes clusters, or CI/CD pipelines use short-lived federated Google Cloud access tokens derived from their external identity provider.

Before you begin

Before configuring Workload Identity Federation, verify the following prerequisites:

  • Minimum Remote Agent version 2.6.2 or later.
  • The user configuring Workload Identity Federation must have the required IAM permissions in Google Cloud to create and manage Workload Identity Pools (roles/iam.workloadIdentityPoolAdmin) and Service Accounts (roles/iam.serviceAccountAdmin).
  • A dedicated Service Account created in Google Cloud with the Chronicle SOAR Remote Agent role (roles/chronicle.soarAgent). For steps to create a service account, see Create a service account.
  • Access to your external Identity Provider (AWS, Azure, Active Directory/ADFS, Kubernetes, CI/CD pipeline, X.509 CA, or custom OIDC/SAML provider).

Step 1: Create a Workload Identity Pool and Provider

In Google Cloud, Workload Identity Pools manage external identities, while Workload Identity Providers define the connection parameters between your external IdP and Google Cloud.

  1. In Google Cloud console, go to the Workload Identity Pools page. Go to Workload Identity Pools
  2. Click Create Pool.
  3. Enter a Name and Description for the pool (for example, soar-remote-agent-pool).
  4. Click Continue.
  5. In the Add a provider to pool section, select your provider type and enter the provider connection details (such as AWS Account ID or OIDC Issuer and Audience) from your provider's guide above.
  6. In the Configure attribute mappings section, map claims from your external token (such as google.subject=assertion.sub) to Google Cloud IAM attributes as specified in your provider's guide.
  7. Click Save.

Step 2: Grant Service Account Impersonation Permissions

Allow external identities in your Workload Identity Pool to impersonate your Remote Agent Service Account.

  1. In Google Cloud console, go to the Service Accounts page.
  2. Select your Remote Agent Service Account.
  3. Click the Principals with access tab.
  4. Click Grant access.
  5. In the New principals field, enter the principal identifier corresponding to your Workload Identity Pool: 
    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
  6. In the Select a role list, select Workload Identity User (roles/iam.workloadIdentityUser).
  7. Click Save.

Step 3: Download or generate External Account Credentials (agent-key.json)

On the Remote Agent host machine, obtain an external account credential configuration file named agent-key.json using one of the following options.

Option A: Download from Google Cloud console (Recommended)

  1. In Google Cloud console, go to the Workload Identity Pools page.
  2. Select your Workload Identity Pool and click Grant access.
  3. In the Grant access panel, select Grant access using service account impersonation.
  4. In the Select service account list, select your Remote Agent Service Account.
  5. In the Select principals (identities that can access the service account) section, specify which identities can access the service account (such as selecting an attribute name and value).
  6. Click Save.
  7. In the Configure your application window:
    • Select your Workload Identity Provider.
    • In the OIDC ID token path field, enter the exact file path where your external token is mounted or stored (for Kubernetes projected tokens, this must match the mountPath + path defined in your pod manifest, such as /var/run/secrets/tokens/gcp-kms-token).
    • Set Format type to Text (raw JWT string). Do not select JSON for standard token files.
    • Click Download config and save the file as agent-key.json (or rename the downloaded file to agent-key.json).
  8. Transfer the agent-key.json file to your Remote Agent host machine.

Option B: Generate using gcloud CLI

Run the gcloud iam workload-identity-pools create-cred-config command to generate the credential configuration file:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --output-file=agent-key.json \
    --credential-source-file=/var/run/secrets/tokens/gcp-kms-token

Sample Configuration File Reference

For reference, the generated agent-key.json file contains a structure similar to the following:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "/var/run/secrets/tokens/gcp-kms-token"
  },
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken"
}

Step 4: Map Service Account in Google SecOps

Before deploying the Remote Agent, authorize the Service Account email address within Google SecOps:

  1. Go to SOAR Settings > Advanced > Group Mapping.
  2. Click add Add.
  3. In the Add Role dialog, enter the full service account email address in the IAM Role / IdP group field.
  4. Select the appropriate Environments that the remote agent will manage.
  5. Click Add.

Step 5: Deploy or Update Remote Agent Authentication

Podman

To configure Remote Agent authentication on Podman, follow these steps:

  1. List running Podman containers: 
    podman ps
  2. Enter your agent's container ID: 
    CONTAINER_ID

  3. Use the following command to copy the credential configuration file to the dedicated path in the container:

    podman cp PATH_TO_AGENT_KEY/agent-key.json CONTAINER_ID:/opt/SiemplifyAgent/agent-key.json

  4. Use the following command to change the owner of the credential configuration file in the container:

    podman exec -u 0 CONTAINER_ID chown siemplify_agent:siemplify_agent /opt/SiemplifyAgent/agent-key.json
  5. Run the following command to apply the changes: 
    podman restart CONTAINER_ID

Docker

To configure Remote Agent authentication on Docker, follow these steps:

  1. List running Docker containers: 
    docker ps
  2. Enter your agent's container ID: 
    CONTAINER_ID

  3. Use the following command to copy the credential configuration file to the dedicated path in the container:

    docker cp PATH_TO_AGENT_KEY/agent-key.json CONTAINER_ID:/opt/SiemplifyAgent/agent-key.json

  4. Use the following command to change the owner of the credential configuration file in the container:

    docker exec -u 0 CONTAINER_ID chown siemplify_agent:siemplify_agent /opt/SiemplifyAgent/agent-key.json
  5. Run the following command to apply the changes: 
    docker restart CONTAINER_ID

Installer

To configure Remote Agent authentication on CentOS/RHEL, follow these steps:

  1. Move the credential configuration file to the expected path:

    mv PATH_TO_AGENT_KEY/agent-key.json /opt/SiemplifyAgent/agent-key.json

  2. Use the following command to change the owner of the credential configuration file:

    chown siemplify_agent:siemplify_agent /opt/SiemplifyAgent/agent-key.json
  3. Run the following command to restart the agent service: 
    supervisorctl restart siemplify_agent

Need more help? Get answers from Community members and Google SecOps professionals.