Prisma Access Tenant-to-Tenant Configuration Migration#

Migrate configurations between Prisma Access tenants (TSGs) via the Strata Cloud Manager API.

Overview#

This skill helps you export configurations from a source tenant and import them into a target tenant. It handles naming conflicts, reference resolution, and dependency ordering.

For detailed API call reference, see migration-workflow.md.

Migration Compatibility Matrix#

Based on real-world migration testing, here is what can and cannot be migrated directly via SCM API:

Directly Migratable (API fully supported)#

ResourceNotesTagsNo issuesAddress ObjectsIP netmask, FQDN, IP range, IP wildcard all supportedAddress GroupsStatic and dynamic; referenced addresses must exist firstService ObjectsNo issuesService GroupsNo issuesApplication FiltersNo issuesApplication GroupsNo issuesExternal Dynamic Lists (EDL)No issuesHIP ObjectsNo issuesHIP ProfilesNo issuesFile Blocking ProfilesNo issuesProfile GroupsSupported, but referenced sub-profiles must exist firstSecurity Rules (most)Simple rules migrate directlyNAT RulesNo issuesDecryption Rules (most)Simple rules migrate directly

Not Directly Migratable (require manual handling)#

ResourceIssueWorkaroundURL Filtering ProfilesService Account returns Access deniedGrant additional API permissions, or recreate manually in SCM consoleData Filtering ProfilesService Account returns Access deniedSame as aboveAI Security ProfilesService Account returns Access deniedSame as aboveCustom URL CategoriesAPI returns 0 results or Access deniedRecreate manually in SCM console before migrating rules that reference themProfile Groups with inaccessible refsReferences URL Filtering / Data Filtering / AI Security profiles that can't be exportedMigrate with invalid references stripped; add them back manually after creating the sub-profiles in the target tenantRules referencing missing objectsSecurity/Decryption rules fail with INVALID_REFERENCECreate the missing referenced objects first, then retry the ruleapp-tagging rulesNested object arrays cause Invalid Request PayloadRecreate manually in SCM consoleCross-folder name conflictsRules with same name in All or Prisma Access folder cause UNIQUEIN_ERRORSkip — these are typically system-preset rules already present in the target

Key Lessons#

1. Dependency order is critical: Tags → Addresses → Groups → Services → File Blocking Profiles → URL/Data/AI Profiles → Profile Groups → Rules
2. Service Account permissions are the biggest blocker: URL Filtering, Data Filtering, and AI Security profile APIs require elevated permissions that default Service Accounts may not have
3. Conflict detection must check ALL folders: Rules exist across Shared, All, Prisma Access, Mobile Users folders — checking only Shared misses conflicts
4. Profile Groups can be partially migrated: Strip invalid references, import the group, then manually add the missing references later
5. System-preset objects should be skipped: Both tenants share identical predefined objects (best-practice profiles, default EDLs, default HIP objects)
6. Fields to strip before import: id, created, last_modified, snippet, override_loc, override_type, override_id, rule_uuid, folder, policy_type, position (position goes in the query parameter instead)

Prerequisites#

Set the following environment variables:

bash

# Source tenant credentials
export SRC_SCM_CLIENT_ID="source-client-id"
export SRC_SCM_CLIENT_SECRET="source-client-secret"
export SRC_SCM_TSG_ID="source-tsg-id"

# Target tenant credentials
export DST_SCM_CLIENT_ID="target-client-id"
export DST_SCM_CLIENT_SECRET="target-client-secret"
export DST_SCM_TSG_ID="target-tsg-id"

Migration Workflow#

Step 1: Export from Source Tenant#

Authenticate and export all configuration objects from the source tenant via SCM API:

text

GET https://api.sase.paloaltonetworks.com/sse/config/v1/{resource}?folder={folder}&limit=200

Export objects in dependency order. Handle pagination with offset when total exceeds limit.

Step 2: Conflict Detection#

Before importing, check the target tenant for conflicts across all folders ( Shared, All, Prisma Access, Mobile Users, Remote Networks):

• Name conflicts: objects with the same name — typically skip (system presets)
• Reference conflicts: objects referencing things not in the target — need to create dependencies first or strip invalid references
• Cross-folder conflicts: rules in All folder that block creation in Shared — skip these

For each conflict, present the user with options:

• Skip: do not import (recommended for system presets)
• Overwrite: replace the target object with the source object
• Rename: import with a prefix/suffix (e.g., migrated- prefix)
• Strip references: import without invalid references, fix manually later

Step 3: Transform and Import#

For each object:

1. Remove source-tenant-specific fields ( id, created, last_modified, snippet, override_loc, override_type, override_id, rule_uuid)
2. Remove folder and policy_type from the body (folder goes in query param)
3. For rules: remove position from body (goes in query param as &position=pre or &position=post)
4. For Profile Groups with invalid references: strip the unavailable sub-profile references
5. POST to the target tenant API

text

POST https://api.sase.paloaltonetworks.com/sse/config/v1/{resource}?folder={folder}

Step 4: Validation#

After import:

1. List all imported objects and verify counts match source
2. Check for broken references
3. Run a candidate config push to validate (without committing)

text

POST https://api.sase.paloaltonetworks.com/sse/config/v1/config-versions/candidate:push

Step 5: Commit (User-Confirmed)#

Only commit after user explicitly confirms:

text

POST https://api.sase.paloaltonetworks.com/sse/config/v1/config-versions/running:push

Usage Examples#

text

/prisma-access:prisma-migrate

Interactive mode: prompts for source and target tenant details.

text

/prisma-access:prisma-migrate 1234567890 0987654321

Migrate from TSG 1234567890 to TSG 0987654321.

Safety Guardrails#

• Dry-run by default: always show what would be imported before making changes
• No auto-commit: never commit configuration without explicit user confirmation
• Rollback guidance: provide instructions to undo changes if needed
• Rate limiting: respect SCM API rate limits (avoid bulk API flooding)
• Skip system presets: automatically skip predefined objects that exist in both tenants