PingAM Config Promoter

Compare the configuration of two self-hosted PingAM (7.x/8.x) environments in VS Code, review the differences down to single attributes, and promote what you choose from a source environment to a target environment (for example dev → test → prod).

PingOne Advanced Identity Cloud is not supported. Verified against PingAM 7.5.1; AM 8.x is supported by design (attributes the target AM does not have are left out of a promotion and listed) but has not been tested against a live instance yet.

Install

From the VS Code Marketplace:

ext install BostonIdentity.pingam-config-promoter

Or download the .vsix from the releases and run Extensions: Install from VSIX….

What it compares

Script UUIDs differ between environments. Scripts are matched by name when their UUIDs differ, references to scripts are compared by the script they point to (shown as @script:<name>), and on promotion references are rewritten to the target's script UUIDs.

Getting started

1. Open the PingAM Promoter view in the Activity Bar and add an environment: the AM URL including the context path (for example https://am.example.com/am) and either an admin username and password or a pasted SSO token. Credentials are stored in the OS keychain, never in settings.
2. Use Test Connection on each environment.
3. The Promotion Workbench opens the first time the sidebar is shown. You can also open it from the view's title bar, or with Open in Promotion Workbench on a realm.
4. Pick the source and target environment and realm, then press Compare.

Using the Workbench

• Navigation on the left follows the realm menu of the AM admin console: Applications (OAuth 2.0 Clients), Authentication (Settings), Scripts (by script type), Services (OAuth2 Provider, Session, Validation, ...). Only menus with supported objects appear. Each entry shows changed / total.
• Status cards: modified, only in source, only in target, identical. Click one to filter.
• Search matches names, client ids, display names, script types and changed field names.
• Expand a row to see each changed field: the target's current value and the value after promotion. Diff opens the full diff in an editor.
• Select what to promote. Selecting a client or the provider selects the scripts it needs. For the provider, pick single attributes or whole sections in the expanded row.
• Dry run shows the plan without writing. Promote opens a review dialog: the objects to write in order, the env variables that will be substituted, client secrets, and, for a protected target, a field where you type the environment name.
• (Global configuration) in the realm picker compares environment-wide configuration instead of a realm: global services (with the realm defaults they hold), server defaults, each server's own overrides, sites, global secret stores and their label → alias mappings, and scripting engines. It is compared only, never promoted. Servers pair by URL, so map the host with an env variable. The password encryption key and every password attribute are never read.
• Compare: … Choose… below the environment pickers limits what is fetched and compared, by the same AM menus the result shows (a whole menu such as Applications, or one entry such as OAuth 2.0 Clients, one script type or one realm service). Scripts used by the compared objects are always included; circles of trust bring their entity providers. Re-compares and promotions keep the same scope, and a partial result says so.
• Clone… on an OAuth2 Client or SAML entity provider row creates a new object in the same environment from it. Clients get a new client id and, if confidential, the secret you enter (the original's is never copied). Hosted entities get a new entity ID, meta alias per role and secret label identifier. Remote entities are copied whole under a new entity ID, including the original partner's metadata (endpoints and certificates then still point to that partner until you change them), or created from a new partner's metadata (paste or load a file) with only the original's extended configuration copied. Every value is prefilled; everything except the entity ID or client id can be changed in AM afterwards. The dialog previews the body before writing; the clone is backed up as not existing before and logged, so Roll back can delete it.
• History & Rollback lists every promotion, clone, dry run and rollback. Roll back restores the backup taken right before that promotion.
• Saved compares (top of the History tab): every compare saves the configuration it fetched from both environments under promote/compares/, one file per object in the export layout, with a summary.json (AM versions, a hash per side, status counts). A compare that finds both sides unchanged since the previous saved one does not save again; it only updates that entry's "seen" count. So the folder grows only when configuration changes, and any object can be diffed between two points in time with the Explorer's Select for Compare. Turn it off with the setting pingamPromoter.compareHistory.

Is the data up to date?

Yes. Every Compare and Re-compare fetches the current configuration from both AMs; the extension does not cache configuration.

• Promote re-compares before building the plan, so the review dialog always reflects the target as it is now, and re-compares again afterwards to verify that what was written now matches.
• Diff editors show the compare they were opened from. After a re-compare, open the diff again to see newer data.
• Read-only documents opened from the Environments tree are cached by VS Code while the tab is open; close and reopen them to refresh.
• Only the AM session token is kept in memory between calls, so you are not logged in for every request.

Env variable mapping

Some values must differ per environment, such as the host in a redirect URI. Without a mapping they show up as differences and promoting copies the source's value into the target. A mapping tells the extension which values in each environment stand for the same thing.

Each environment has one file, named after the environment, of "NAME": "value" pairs:

// promote/env-vars/DEV.json
{ "APP_HOST": "app.dev.example.com", "API_HOST": "api.dev.example.com" }

// promote/env-vars/TEST.json
{ "APP_HOST": "app.test.example.com", "API_HOST": "api.test.example.com" }

Use Env variables in the Workbench to open or create the file.

How values are replaced

• Compare: on each side, every occurrence of that environment's value is replaced with {{NAME}}, then the two sides are compared. https://app.dev.example.com/callback and https://app.test.example.com/callback both become https://{{APP_HOST}}/callback and compare as identical. The rest of the field is still compared: a different path is still a difference.
• Promote: {{NAME}} is replaced with the target file's value before writing.
• Names pair the two files. APP_HOST in DEV.json corresponds to APP_HOST in TEST.json. Names use letters, digits and _; values must not be empty.
• Part of a string matches, not only a whole value: a host inside a URL is replaced.
• Not inside a longer word: a value is not replaced when a letter or digit touches it on either side. With "ENV": "dev", /realms/dev/ and app-dev match, device and devonly do not.
• Case-sensitive: app.DEV.example.com does not match app.dev.example.com.
• Longer values first: if both app.dev.example.com and dev.example.com are defined, the longer one wins.
• Every string is checked: OAuth2 Provider attributes, OAuth2 Client fields and script bodies. Numbers and booleans are not.
• A missing target variable blocks promotion: if an object being promoted uses {{PARTNER_HOST}} and the target's file does not define it, nothing is written.

The Workbench header shows how many variables each side has. Hover over it to see how many objects each variable was found in. A variable found in no object is marked ⚠: usually its value is wrong, for example in a different letter case.

Mapping replaces values. It does not exclude fields from the compare or from promotion.

Safety

• Backups: the target version of every object is saved before each write, to promote/backups/<env>/<timestamp>/.
• Full backups: Back up in the History tab (or Back Up Environment (Full) on an environment) saves every promotable object of every realm, one folder per realm. Restore any of them from the History tab; nothing is preselected.
• Never deletes by default: objects that exist only in the target are never deleted. A rollback can delete objects a promotion created only when you tick them.
• Protected environments: promoting into an environment marked protected requires typing its name.
• Client secrets: AM never returns them. Updated clients keep the target's secret unless you choose to set a new one. New confidential clients get the secret you enter in the review dialog; if you leave it blank, set it in AM afterwards. Secrets are not logged or backed up. Use https:// URLs: over http:// secrets travel in plain text.
• Passwords in realm services: attributes that AM's schema marks as passwords are never read, compared or promoted, and null values are never sent, so the target's value is kept.
• Provider hashSalt: the extension never reads it, so it is not compared, shown, exported, backed up or promoted. It seeds pairwise subject ids and must stay environment-specific.
• Promotion log: promote/promotion-log.jsonl records who promoted what, when, from where to where, and the outcome.

Running the tests

• npm run test:unit: model tests in plain Node.
• npm test: every test inside a real VS Code instance (downloaded on first run). Set PINGAM_IT_URL, PINGAM_IT_USER and PINGAM_IT_PASSWORD to also run the integration tests against that AM. They promote, clone, back up and roll back in realms /dev and /test, and undo their own changes, so point them at a test instance only.

Files the extension writes

All files go under promote/ in the first workspace folder (or the extension's own storage when no folder is open):

Known limitations

• Not compared yet: authentication trees (journeys), nodes, policies, agents, identity stores, realm secret mappings. Whether a script is used by an auth tree or a social IdP is not checked.
• Global configuration and realm sub-configurations (for example social IdP instances) are compared only, not promoted.
• An attribute whose meaning changed between AM versions is not detected; only attributes the target AM does not have are left out.
• Browser-based SSO login is not supported; paste an SSO token instead.