ProAuth Documentation

Appearance

Version v3.3.0

Prepare option collections for an upgrade ​

Older YAML importers could create duplicate options when name lookup stopped at the first result page. The corrected importer reads every page and preserves normal create-or-update behavior. The OptionOwnerUniqueness database migration prevents duplicate names within each tenant, identity provider, or MFA instance, including concurrent creation.

Before rollout ​

Run the read-only script for your database against the ProAuth database:

The scripts return owner type, owner ID, option name, option ID, and duplicate count. They do not return values or credentials. An empty result means no duplicate keys were found at that time. Names are compared after trimming spaces and converting to uppercase using the database's rules.

Complete this check and any recovery before starting the schema deployment job. Pause configuration imports and administrative option changes during the final check and schema deployment so old clients cannot recreate duplicates between the two. Authentication traffic does not need to be deliberately stopped for the preflight. Schema changes and index creation still acquire database locks; measure the migration against a production-sized copy and budget for its execution in your rollout.

The migration never deletes options or chooses a surviving value. If duplicates remain, it fails with a diagnostic before changing the schema; repair the records and rerun the deployment job. Preflight is a deployment prerequisite, not an automatic repair.

Recover an affected collection ​

  1. Back up the database and record the affected owner and option IDs. Restrict access to any exports containing secret values.
  2. Read each reported option through the management API or administration UI. Compare actual values securely, including generated credential settings and their relationships. Do not treat redacted values as proof of equality.
  3. Select the existing record whose ID and value should remain. For conflicting values, have the configuration owner choose the intended value. Retain referenced IDs and the matching ScimToken/ScimTokenId pair; do not regenerate credentials merely to repair duplication.
  4. Delete only the reviewed redundant records using the management v2 API, supplying each record's observed ETag in If-Match. If a record changes, stop and review it again. Do not refresh the ETag and blindly retry a deletion.
  5. Rerun the preflight and verify option readback and affected integrations. For SCIM, verify a read with the existing credential and rejection of an invalid credential.
  6. Deploy the schema and corrected CLI, then rerun the original manifest. Existing unambiguous options retain their IDs. Remove obsolete duplicate IDs from manifests that explicitly named them.

Import behavior after the fix ​

A missing option is created; a single matching option is updated. Existing settings absent from the manifest are retained. Generated SCIM credentials are not rotated by reconciliation. Explicitly supplying a new secret value still changes it; a newly generated placeholder value is not an unchanged credential.

Matching is scoped to the exact owner. An explicit ID belonging to another owner, or an ID disagreeing with the existing name match, causes an error. Renaming an option through YAML by changing the name attached to an existing ID is rejected; use an intentional management operation instead.

Before writing an owner's options, the importer reads all pages and checks for duplicate names. Identical and conflicting duplicate records both stop that owner's option processing, with record IDs in the diagnostic and no secret values. A failed page is not interpreted as an absent option.

A simultaneous create is accepted only when the winner has the intended value and, if specified, the intended ID. Conflicting creates and stale updates stop rather than overwrite concurrent changes. Imports are not transactions across the whole file: earlier resources and the current parent may already have been updated. Resolve the reported issue and rerun the manifest.