# Frequently Asked Questions on SOAR migration

Supported in:

Get answers to common questions about the SOAR migration process. Find solutions to frequent issues and best practices for a successful transition.

### Migration scope and impact

**Q: How do I know if my migration was successful?**

Your environment is fully migrated when **CloudIAM Enabled** is active and Cloud Logging records zero customer-actionable legacy SOAR API calls for 30 consecutive days. Verify each stage as follows:

1. **Check platform and Identity and Access Management (IAM) status** : go to **SOAR Settings** \> **License Management** and check the text next to the system version number:
   - **After Stage 1** : **Google.com** appears next to the system version number.
   - **After Stage 2 IAM migration** : both **Google.com** and **CloudIAM Enabled** appear next to the system version number.
2. **Confirm zero legacy API calls in Cloud Logging**:

   1. Verify that SOAR operational logs (`resource.labels.namespace_name="chronicle-soar"`) are flowing to Cloud Logging in your Google Cloud project. Log export is enabled automatically for unified Google Security Operations instances and configured using a **Logs Writer** service account for SOAR standalone instances; see [Collect SOAR platform logs](https://docs.cloud.google.com/chronicle/docs/secops/collect-secops-soar-logs.md.txt). All legacy API deprecation warnings (`labels.auth_deprecation="true"`) are emitted here as `WARNING`-severity operational logs rather than in Cloud Audit Logs, and only customer-actionable warnings (`labels.actionable_by="Customer"`) are exported to your Google Cloud project (internal Google UI and system calls are filtered out automatically).
   2. In the Google Cloud console, go to **Logging** \> **Logs Explorer** , set the time range to **30 days**, and run the following query:

          resource.labels.namespace_name="chronicle-soar"
          labels.auth_deprecation="true"

   3. Confirm that the query returns zero log entries over 30 consecutive days, as shown in the following example:

      ![Logs Explorer showing zero results for the auth_deprecation query.](https://docs.cloud.google.com/static/chronicle/images/soar/migration-explorer-confirm-zero-logs-authdeprecationtrue.png) **Figure 1.** Logs Explorer showing zero legacy API deprecation log entries.

      If entries appear, run the following queries in **Logs Explorer** and inspect the emitted fields to identify components that still call legacy `siemplify-soar.com` endpoints:
      - **Outdated Content Hub (out-of-the-box) integrations**:

          resource.labels.namespace_name="chronicle-soar"
          labels.auth_deprecation="true"
          labels.is_system="true"
          labels.is_custom="false"

      Check `labels.integration_name`, `labels.integration_version`, `labels.latest_integration_version`, and the triggering component (`labels.action_name`, `labels.connector_name`, `labels.job_name`, `labels.playbook_name`) to find Content Hub packages to update.
      - **Custom Python code making manual HTTP calls**:

          resource.labels.namespace_name="chronicle-soar"
          labels.auth_deprecation="true"
          labels.is_custom="true"

      Check `labels.integration_name`, `labels.action_name`, `labels.connector_name`, `labels.job_name`, and `labels.playbook_name` to locate custom scripts.
      - **External scripts and third-party tools calling legacy APIs directly (`AppKey`)**:

          resource.labels.namespace_name="chronicle-soar"
          labels.auth_deprecation="true"
          labels.is_system="false"

      Check `labels.app_key` (the legacy API key identifier), `labels.via_xlb` (`"true"` for external ingress), and the called HTTP route in `textPayload` (`Deprecated direct AppKey authentication detected (Route: ROUTE).`), as shown in the following example:


      ![Logs Explorer showing active legacy API key deprecation logs.](https://docs.cloud.google.com/static/chronicle/images/soar/migration-verify-zeromatcheswith-deprecationtrue.png) **Figure 2.** Expanded deprecation log entry showing the `app_key` label and HTTP route.

      <br />

      - **Remote Agent attribution (`labels.is_remote="true"`)** : Indicates legacy calls from code running on a Remote Agent. First, upgrade the Remote Agent to version `2.6.2` or later and migrate it to service account authentication (see [Migrate remote agent authentication infrastructure](https://docs.cloud.google.com/chronicle/docs/soar/working-with-remote-agents/migrate-remote-agent-to-google.md.txt)). Once the Remote Agent is upgraded and configured with a Google Cloud service account, the agent's own control-plane polling uses OAuth 2.0; full component label attribution for Remote Agent SDK calls is being released in stages across production. If entries continue after migrating the agent, check for outdated integrations or custom code running on that agent.

      > [!TIP]
      > **Tip:** While migrating, you can also select **System Notifications** in Google SecOps or query the `GET /api/external/v1/logging/non-1p-api-usage` summary endpoint to review remaining legacy API calls by category. For details, see [Audit remaining legacy API usage](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/api-migration-guide.md.txt#audit-legacy-api-usage).

3. **Verify Remote Agents and webhooks**: if your environment uses Remote Agents or incoming webhooks, confirm they work on the new infrastructure:

   - **Remote Agents** : go to **SOAR Settings** \> **Advanced** \> **Remote Agents** and confirm each migrated agent reports **Live** status.
   - **Webhooks** : send a test event to each updated regional `: ingest` webhook URL and confirm that Google SecOps ingests the alert.

**Q: Why is this migration necessary?**

We're modernizing the SOAR infrastructure by migrating to Google Cloud.
This critical upgrade provides key benefits, including enhanced reliability,
improved security, greater compliance, and more granular access control. It also gives
access to Agentic AI capabilities through Model Context Protocol (MCP) integration.

The migration provides the following:

- Enhances SOAR's reliability and monitoring capabilities by utilizing Google's best-in-class API layer. This layer provides a leading API solution with advanced features for quota management, auditing, and observability.
- Unlocks Role-Based Access Control (RBAC) for features and data throughout the entire platform.
- Provides higher compliance functionality, such as VPC Service Controls, Data Residency, and Customer-Managed Encryption Keys (CMEK).

**Q: What's the scope of the migration?**

The migration involves the following components:

- Migrating SOAR project to a customer owned Google Cloud project.
- Migrating SOAR authentication and permissions to Google Cloud IAM.
- Migrating SOAR APIs to Chronicle API.
- Migrating remote agents authentication infrastructure.

**Q: What are the immediate changes after the migration?**

Immediately following the migration, you'll experience several key changes:

- **GCP Project Ownership**: Your SOAR project will migrate from Google's ownership to your customer-owned Google Cloud project.
- **Authentication** :
  - Unified SecOps customers: No change. Authentication will continue to be managed by Google Cloud IAM.
  - SOAR Standalone customers: Authentication will now be managed by Google Cloud IAM. For users using SAML, this means adopting Workforce Identity Federation, and the SAML configuration will no longer be stored and managed within the SOAR system itself, leading to stronger security controls.
- **RBAC**: User permissions will become more granular and managed using IAM. Environments and SOC roles will continue to be managed within the SOAR module using Identity Provider (IdP) groups.
- **Audit Logging** : Audit logs will be more detailed and managed within **Cloud Audit Logs**.
- **New URL (SOAR only)**: SOAR standalone users will receive a new URL (new domain) for accessing SOAR.

**Q: How are customers / partners being notified of this migration?**

An in-product pop up is displayed for all customers and partners which includes
the migration date and a link to a form to fill out. They will be prompted to confirm their migration date and time slot.

**Q: Will our infrastructure costs change as a result of SOAR being bound to our Google Cloud project?**

No, your costs won't be impacted. You shouldn't experience any change
on the frontend. No new resources will run in your project, so there are no associated costs.

**Q: How do we connect our project to SOAR?**

Google will migrate your SOAR project to your Google Cloud project.
If you are a Unified SecOps customer, we already have your Google Cloud project ID.
If you are a SOAR standalone customer, you will need to share your Google Cloud project ID with us.

**Q: For customers who already have a Google SecOps deployment, should we use the same project ID as SIEM, or do we need a separate project?**

For a unified Google SecOps deployment (one SIEM, one SOAR), you
should use the existing Google Cloud project ID associated with your SIEM.
This allows for unified management of administrative flows, such as RBAC and logs.

**Q: For Google SecOps instances with special considerations such as VPC Service Controls (VPC-SC), what steps are needed?**

To enable the migration, you'll need to define both Ingress and Egress rules within your VPC-SC policy.
If your Google Cloud Project has VPC SC, contact the Support team for detailed guidance on these specific rules.

There are two API features that are not supported using VPC-SC:

- Webhooks
- Playbook Approval links

**Q: How can I check that the migration has been successful?**

Check for successful completion by going to **SOAR Settings \> License Management** .
After Stage 1, it will say **Google.com** after the system version number.
After Stage 2 migration of SOAR permissions to IAM roles , it will say both **Google.com** and **CloudIAM Enabled** after the system version number.

### Downtime and continuity

**Q: Is there any downtime during the migration, and what is its impact?**

Yes. The expected downtime is as follows:

- Up to 2 hours for SOAR standalone customers.
- Up to 1.5 hours for Google SecOps customers.

During this period, you won't be able to sign in to the platform. SOAR services (including ingestion, playbooks, jobs)
will be paused but SIEM services will continue running in the background.

**Q: Will data generated during the downtime be automatically ingested once SOAR services resume?**

Yes. Once the system is back online, ingestion and playbooks will resume and
process any alerts that were generated or ingested during the downtime.

**Q: What happens to playbooks that are running when downtime begins?**

The playbook service will be turned off before the migration begins, some running playbooks
may fail and will either need to be restarted manually or will resume after the migration is complete.

**Q: Is there a rollback or contingency plan if something goes wrong during the migration?**

Yes. The migration process keeps your existing SOAR instance fully intact (though turned off).
If the migration process doesn't complete successfully, we can switch
back to your existing instance and remove the new one.
This rollback process takes up to 30 minutes. We'll perform extensive testing and
close monitoring, with on-call staff on standby to ensure successful migration.

If you experience access issues after migration, you likely have an incorrect authentication setup. You will need to coordinate with your Identity, IDP, or Google Cloud administrator to use the [troubleshooting guide](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/soar-pre-validation.md.txt) for identification and resolution. If the problem persists or if it is unrelated to access, open a [Support ticket](https://console.cloud.google.com/support) to document the concern and monitor its resolution.

**Q: When and in what order can I migrate to the Chronicle API endpoints?**

Once your instance has completed [Stage 1 of the migration](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/migrate-to-gcp.md.txt#check-migration) (**Google.com** appears in **SOAR Settings** \> **License Management** ), the Chronicle API endpoints are active and you can migrate components---including external API scripts, Remote Agents, Content Hub integrations, webhooks, and IAM permissions---in **any order** at your own pace, even before clicking **Enable IAM** . Until **March 31, 2027** , legacy `siemplify-soar.com` API endpoints and `AppKey` authentication continue to operate in parallel with the Chronicle API with zero downtime.

To migrate an external script or custom integration to the Chronicle API:

1. **Grant IAM permissions and map in Group Mapping** : Grant your service account or Workload Identity Federation principal the required predefined Chronicle IAM role---or run the [SOAR IAM migration script](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/migrate-soar-permissions-iam.md.txt) first if you want to generate custom IAM roles from your existing SOAR permission groups---and map the account in **SOAR Settings** \> **Advanced** \> **Group Mapping** . Clicking **Enable IAM** also updates the Google SecOps UI to display the updated `chronicle.googleapis.com` URLs on the **Webhooks** page.
2. **Update your endpoints and authentication** : Update your external scripts and custom integrations to call the corresponding [Chronicle API endpoints](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/api-migration-guide.md.txt) using OAuth 2.0 authentication.

> [!NOTE]
> **Note:** Out-of-the-box commercial integrations in Content Hub and standard built-in `Siemplify` SDK methods require no code changes; update outdated commercial packages in Content Hub before March 31, 2027 (see [Out-of-the-box Content Hub integrations](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/api-migration-guide.md.txt#ootb-integrations)). For manual HTTP requests constructed inside SOAR custom Python code (`siemplify.API_ROOT` and `siemplify.api_key`), self-service migration support targets mid-November 2026 (see [Migrate custom API calls to the Chronicle API](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/api-migration-guide.md.txt#migrate-custom-api-calls)).

### Authentication and permissions

**Q: How do I migrate my SOAR permission groups and permissions?**

You will use a migration script in your Google Cloud console to
migrate existing permission groups to IAM custom roles.
The script also assigns custom roles to users (for Cloud Identity customers)
or to IdP groups (for Workforce Identity Federation customers).

**Q: What if I prefer not to migrate custom permission groups and only use predefined roles?**

You can opt out of the automated migration and manually map IdP groups to
Cloud IAM roles instead.

**Q: We're a SOAR standalone customer with a custom SAML provider with manual authentication. If we change this to IdP groups for IdP mapping, what's the impact on existing user accounts?**

Assuming your existing users match one of the groups and permissions are mapped correctly,
there shouldn't be any impact on your pre-existing user accounts.
However, if users aren't mapped to groups, they won't be able to sign in.
If permissions are mapped differently, users will receive new permissions based on the new mapping.

**Q: Are there specific prerequisites for MSSPs using multiple identity providers?**

Customers who have configured multiple identity providers on the
SOAR external authentication page, should define Workforce Identity Federation for
authentication and create a separate Workforce Pool for each provider.
Each provider is associated with a different subdomain. For more information, read [MSSP migration guide](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/migrate-soar-mssp-instance.md.txt).

**Q: How do I authenticate to the Chronicle API?**

Follow the instructions in [Authenticate to Chronicle API](https://docs.cloud.google.com/chronicle/docs/reference/authentication.md.txt).

**Q: What are the new IPs required to access the new SOAR API?**

It's not required to allowlist any IP addresses to access Chronicle API. Optionally, you can allow list the range of IP addresses indicated in [Google Services IP ranges](https://www.gstatic.com/ipranges/goog.json) and [Google Cloud resources IP ranges](https://www.gstatic.com/ipranges/cloud.json).

### Logging and monitoring

**Q: We completed the first stage of migration, but we don't see SOAR events in Cloud Audit Logs.**

- **SOAR operational logs** (playbook, Python, ETL, and `labels.auth_deprecation="true"` warnings under `resource.labels.namespace_name="chronicle-soar"`) are available in Logging after **Stage 1** (**Google.com** ) is complete. For setup and query instructions, see [Collect SOAR platform logs](https://docs.cloud.google.com/chronicle/docs/secops/collect-secops-soar-logs.md.txt).
- **Cloud Audit Logs (`cloudaudit.googleapis.com`)** : After completing **Stage 1** , audit logs remain stored on the **Audit** page in the SOAR platform. SOAR user and API audit events become available in Cloud Audit Logs in your Google Cloud project after completing **Stage 2** (once you enable Google Cloud IAM and migrate API calls to `chronicle.googleapis.com`). Until **March 31, 2027** , any calls still using legacy `siemplify-soar.com` endpoints remain recorded on the internal SOAR **Audit** page and emit `labels.auth_deprecation="true"` warning logs in Logging.

**Q: Will customers sending SOAR data to a Managed BigQuery (BQ) instance still be able to access this BigQuery data after the migration?**

Yes. The existing managed BigQuery will continue working.

### Logistics and support

**Q: Can I choose a different time slot for the migration?**

No. Migrating outside of the suggested time slots isn't possible.

**Q: Will we receive real-time status updates during the migration?**

You'll receive an email notification at both the start and end of the migration process.

**Q: Who should we contact if an issue arises post-migration?**

If you experience access issues after migration, the authentication setup is likely incorrect.
You will need to coordinate with your Identity, IDP, or Google Cloud administrator to use the [troubleshooting guide](https://docs.cloud.google.com/chronicle/docs/soar/admin-tasks/advanced/soar-pre-validation.md.txt) for identification and resolution. If the problem persists or if it is unrelated to access, open a [Support ticket](https://console.cloud.google.com/support) to document the concern and monitor its resolution.

## Migrate SOAR permissions groups to IAM

The following section addresses common issues encountered during and after migrating permissions to IAM.

### Migration tool and script issues

**Q: Why can't I see or load the migration script in the Google Cloud console?**

There are two possible reasons for this:

- **Missing permissions** : The migration tool requires your user account to have sufficient permissions in both the Google Cloud and the Google SecOps instance. Make sure you're logged in with an account that has the required IAM roles in Google Cloud and is also a recognized user in Google SecOps SOAR. Using different accounts for Google Cloud and SOAR can cause authorization failures. If you have the required permissions and still cannot load the migration script, open a [Support ticket](https://console.cloud.google.com/support).

- **SIEM doesn't use Cloud IAM** : If you are a Google SecOps unified customer, make sure that you are using IAM to manage roles and permissions for the SIEM side of the platform. For more information, refer to [legacy RBAC to Feature RBAC migration guide](https://docs.cloud.google.com/chronicle/docs/administration/migrate-from-legacy-rbac-to-feature-rbac.md.txt).

**Q I'm getting an error while trying to run the migration scripts. What should I do?**

- **Error - "Group does not exist"** : When using the `add-iam-policy-binding commands`, make sure you are using the full group email address (for example, `your-group@example.com`) for the `--member` flag, not just the short group name.

- **Errors related to pre-existing roles** : Conflicts may occur when binding to a principal which already has conditional bindings. To resolve this, rerun the script and make sure to select **None** instead of **Specify a new condition**.

### Access issues post migration

**Q: Why am I getting a "403 Forbidden" error when trying to access certain pages or features (such as Playbooks or IDE) after the IAM migration?**

A 403 error after migration might indicate that the Google Cloud IAM role assigned to your user is missing permissions required by the SOAR side of the Google SecOps platform. This is common if you are using custom IAM roles.

Check the [Google SecOps roles and permissions](https://docs.cloud.google.com/iam/docs/roles-permissions/chronicle.md.txt). Make sure that your custom IAM role includes all the permissions needed to access the required SOAR features.

Optionally, examine your browser's developer tools to identify specific API calls returning a 403 error. The response payload documents the missing permission, and a notification banner also appears within the interface detailing the required access.

If none of these solutions help, open a [Support ticket](https://console.cloud.google.com/support).

### Permissions and roles

**Q: I performed the IAM migration manually without using the provided tool, and now I have permission issues. How can I fix this?**

Manual IAM migration can sometimes result in missing necessary permissions for SOAR roles. We highly recommend using the provided migration script to ensure all required permissions are set up correctly. If you still plan to perform manual migration, carefully review [Google SecOps IAM permissions](https://docs.cloud.google.com/iam/docs/roles-permissions/chronicle.md.txt) to create the custom roles with the needed permissions.

**Q: Some users seem to have more permissions in SOAR than expected after migration. Why is this happening?**

This can happen if users or groups were already assigned to predefined Chronicle broad Google Cloud roles before the migration.
After you complete the migration, Chronicle predefined roles (such as `chronicle.apiAdmin`) will automatically include SOAR permissions. For example, the Chronicle API Admin role will now include SOAR Admin permissions.

To ensure least-privilege access, follow these steps:

1. Review your predefined roles in [IAM Roles](https://console.cloud.google.com/iam-admin/roles) page, including Chronicle API Admin, to identify all assigned principals (users and groups).
2. Confirm that only users requiring SOAR permissions are assigned to these roles.
3. To limit SOAR access for specific principals, remove them from the predefined roles and assign them to a custom role that explicitly excludes SOAR administrator permissions.

**Q: The migration was successful but I can still see the Permissions Groups column in the Group Mapping page. Why?**

After a successful migration, the **Permissions Groups** column is still displayed in the **Group Mapping** page for backwards compatibility. Don't delete these assignments. The column will be removed by March 31, 2027 without any customer impact.

### Best practices

- **Use the Migration script**: Whenever possible, use the official migration script in Google Cloud to handle the transition from SOAR permission groups to IAM roles.
- **Review IAM Permissions**: Familiarize yourself with the required Google Cloud IAM permissions for different SOAR functions and roles.
- **Test Thoroughly**: After migration, test access for different user roles and personas to ensure everything works as expected.
- **Contact Support** : For any persistent errors or unexpected behavior, contact [Support](https://console.cloud.google.com/support) and provide as much detail as possible.

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)