[HowTo] Automate Policy Object Attribute Level Migration for Configuration Management

[Jack Saunders]

This technical guide serves as a howto for SiteMinder SMEs on the migration of specific, granular object Attributes within (e.g., Realms, Rules, User Directories). The process leverages the XPSExport and XPSImport tools to facilitate a controlled "promote" DevOps like workflow (e.g., from Development to Staging/Production.etc), thereby maintaining the integrity of the target Policy Store configuration while minimizing impact to meet corporate change control policy.

The core principle is to avoid full policy store exports / imports, which carry an unacceptable risk of configuration drift and overwriting existing policies. We will detail this method for achieving granular object attribute promotion.

---

Promotion Method: Direct XID-Based Export

This method is ideal for promoting a known, singular object and its direct dependencies, such as a new Realm and its associated Rules.  As always be sure to backup your policy store before making any changes and have a fail back plan in place.

 

Phase I: Source Environment - Object Identification and Export

The promotion workflow requires the unique XID (eXtended ID) of the object to be migrated.

1. XID Identification: Utilize the XPSExplorer utility on the source Policy Server. Navigate through the object hierarchy (e.g., Policies > Domain > Realm) to locate the target object.

2. Retrieve XID: Copy the full XID string (e.g., CA.SM::Realm@06-xxx...) for the object (e.g., MyNewRealm).

3. Granular Export with Promotion Mode: The export command uses the -xo (Export Object) flag, which is modified to define the intended behavior of the subsequent import operation. To only promote a specific attribute or set of attributes for an object we utilize the overlay command option below.

Flag Modifier	Promotion Mode	Function
-xo-overlay	Safe/Standard Update	Adds the object if it is missing, or updates it if it already exists in the target store. (Recommended default)

Command Syntax (Example: Overlay a Realm):

XPSExport MyRealmUpdate.xml -xo-overlay CA.SM::Realm@06-12345678-abcd-ef00... -pass MyPassphrase

Dependency Note: By default, only the object and its direct children (like Rules within a Realm) are exported. Essential external dependencies (e.g., the Agent or Authentication Scheme referenced by the Realm) must already exist in the target environment or be explicitly exported and included in the promotion XML.2.2. Phase II: Target Environment - Validation and Import

Prior to committing any changes, a dry-run validation is mandatory for integrity assurance.

1. Validation Dry-Run: Use the -validate flag. This parses the XML, checks for schema conformity, and validates dependencies without modifying the Policy Store.

2. XPSImport MyRealmUpdate.xml -validate -pass MyPassphrase

• Output Check: A successful validation will yield a summary of "0 Errors". Errors, particularly those reporting "Missing Dependency," indicate that a required object (e.g., a parent Domain, an Agent, or an Auth Scheme) referenced by the object in the XML is absent from the target Policy Store.

3. Execution Commit: Upon successful validation, remove the -validate flag to commit the changes to the database.

4. XPSImport MyRealmUpdate.xml -pass MyPassphrase

• Cache Management: The import tool automatically attempts to notify the Policy Server to flush its cache. However, for major structural changes, a manual smpolicysrv -flush or Policy Server service restart may be required as a standard operational safety measure.

---

Common Use Case - Enterprise Security Policy Changes

The corporate security policy for an authenticated user idle session time out has been decreased globally from 120 minutes to 60 minutes.  You must update SiteMinder application policies to meet this requirement without impacting other policy configurations.

Stage Policy File In Development  

First we must create or prepare the import file (aka stage).

Steps to Stage Policy Override Import File

1. Within cmd prompt or shell, go to <SiteMinderHomeDir> and execute XPSEplorer:

Note: "Realm" is not a root class and cannot be exported, therefore you must export policy domain level objects.

2. Type "113" for Policy Domain Objects

3. Type "s" to search and return all objects

4. Highlight the XID for the specific realm like shown below and copy/paste it for future use with the XPSExport tool.

 

5. Press "q" then Enter key 3 times to exit out of XPSExplorer

6. Export the policy domain object which includes all realm timeout details using the reference command below.  Your export commandexportcommand XID, filename and comment will differ based on your environment.

Note: Comments are great for future reference the what was changed and why.

 

XPSExport ProxyUI_Policy_Domain.xml -xo-o CA.SM::Domain@03-eef82d35-0a19-45a3-9753-f434c8d92fef -comment "Updating Realm Idle Timeouts based on new Security Governance Policy Requirement X"

 

7. We have the exported file, now we need to update the idle timeout(s)

8. Use a text editor on the exported file.  Search for "Idle".

9. You should see this section within the file. 

Note: Value will differ from the example below. Update this value based on number of seconds.  

 

<Property Name="CA.SM::Realm.IdleTimeout">                     <NumberValue>1800</NumberValue>

10. Repeat the search and update for each Realm until all IdleTimeout references have been updated 

11. Save file

Promote Idle Timeouts

12. Import the changes using the XPSimport command.  Example is below.

 

XPSImport ProxyUI_Policy_Domain.xml

Example Output:

Validation Promotion Success

13. Run XPSExplorer

14. Select Realms by Typing "153" and press enter

15. Type "S" to search and return all realms 

Example Output:

16. Type the number to the Realm you need to validate.  In this example it is "1"

17. Output is below and you can see the new IdleTimeout value is updated.

 

---

At this point you can check the policy file into source control and promote your change in your DevOps pipeline.

 

Granular Policy Attribute Migration with REST APIs

In addition to the XPS tool method points above, SiteMinder will be releasing the PATCH method support in our REST interface in 12.9.1 that will enable granular policy changes as well.

Please see the SIteMinder Office Hours recording to see how that will work.

You can find it below, from minute 17:04 to 22:45. 

https://www.gotostage.com/channel/03187cc34b0c465f9a97e3daae008aab/recording/b28325d2735a474089706e263f3f743b/watch

------------------------------
Jack Saunders
Customer Engagement Principal Engineer
------------------------------