Migrating Dispatch Target From Generic Credentials to Dedicated Entities
In nevisIDM and nevisFIDO 9.2605.x we introduced a new data model for dispatch targets.
The new data model allows to assign dedicated entities to dispatch targets instead of using generic credentials.
In nevisFIDO 9.2605.x, the setting credential-repository.use-dedicated-entities selects the data model. In nevisAdmin 4, it is the Credential Management API property of the nevisFIDO instance pattern (generic or dedicated). From the November 2026 release (nevisFIDO 9.2611), nevisFIDO supports only the dedicated entities, and the setting is removed. See the breaking changes in the nevisFIDO release notes for the removal of the setting.
This migration guide describes how to migrate existing dispatch targets and app attestations from the old data model to the new one.
nevisFIDO 9.2611 no longer reads dispatch targets and iOS App Attestation credentials stored as generic credentials. Dispatch targets that were not migrated are not found, so out-of-band operations can no longer reach the affected devices.
Do not deploy the new (November 2026, 9.2611) nevisFIDO before the migration is finished, that is, before the final sync after the switch is complete for every client and all errors are resolved. Upgrading earlier makes the not yet migrated dispatch targets and App Attestations unusable.
Upgrade in this order:
- Migrate the generic credentials with the standalone tool or the batch job, while nevisFIDO still runs 9.2605.x.
- While nevisFIDO still uses the generic credentials, run the last sync in sync (incremental) mode with
--prune-orphans/pruneOrphans. It removes the dispatch targets and App Attestations that nevisFIDO already deleted from the generic credentials. See the warning below. - Switch nevisFIDO 9.2605.x to the dedicated entities (
credential-repository.use-dedicated-entities: true), then run the final sync (without prune orphans). - Only now, when the migration is finished, upgrade nevisFIDO to 9.2611 and remove
credential-repository.use-dedicated-entitiesfrom the configuration. If the setting is stillfalse, nevisFIDO 9.2611 logs an error and does not start. If it istrue, nevisFIDO logs a warning and starts.
--prune-orphans / pruneOrphans deletes every dedicated DispatchTarget and App Attestation that has no corresponding generic credential. Once nevisFIDO uses the dedicated entities, every dispatch target and App Attestation it creates is such an entity, so the option would delete all new dispatch targets and App Attestations created after the switch, and out-of-band operations stop working for those devices. The deletion cannot be undone except by restoring the database backup.
- Only run it on a system where nevisFIDO has not yet been switched to the dedicated entities (
credential-repository.use-dedicated-entitiesis stillfalse, in nevisAdmin 4: Credential Management API = generic). - Never run it after the switch, never leave it enabled in a job or schedule that continues past the switch, and never run it on a system that already uses the dedicated entities, for example a new installation or a nevisFIDO 9.2611.
- Run it with
--dry-run/dryRunfirst and check what would be deleted.
Step-by-step guide
There are two ways to run the migration. Choose one:
- Standalone migration tool (JAR): choose it if you want to minimize the number of deployments and accept that the configuration takes more time (keystore, truststore, command-line options).
- nevisIDM batch job: choose it if you want a more easily configurable solution and accept that it requires three deployments.
Read the logs and the report of every run before you continue with the next step. Dry runs and real runs report skipped and failed entities (for example missing or duplicate device IDs and orphan generic credentials) that you have to resolve before the migration can be complete.
Save the report file to a mounted persistent volume. Otherwise the report is lost when the pod is restarted or rescheduled.
Option 1: Standalone tool (fewest deployments)
nevisFIDO keeps running with the old data model while the tool migrates the data. Only one change of the nevisFIDO configuration is needed, at the end.
- Create a database backup.
- Download the migration tool from Nevis Portal.
- Prepare the certificates: a client certificate for the tool, trusted by nevisIDM, and a truststore for the tool if nevisIDM uses a private CA.
- Run the tool with
--dry-run. Read the log and the report, and resolve the reported problems. - Note the current time (in UTC if the nevisIDM server runs in UTC, see Time zone of the modified-after time; for example with
date -u +%Y-%m-%dT%H:%M:%SZ) and run the first migration with--gc-handling keep-generic. The noted time is the start of the sync window: everything that changes after it must be picked up by the later runs. - Read the log and the report. If you limited the run with
--max-migrations, the log ends withlast processed userId = <id>. - Run the tool again with
--after-user-id <id>(see Resuming a limited run) and repeat until the tool does not stop at the limit anymore. - When the first migration has processed every user, the data is migrated up to the time noted in step 5. Keep it in sync with sync sweeps: start a sweep with
--modified-after <time noted in step 5>(without--after-user-id) and note its start time. If you limit the sweep, resume each client with its last processed user ID and the same--modified-afteruntil the sweep has gone through all users of every client. Start the next sweep with the noted start time of the previous sweep as--modified-after, again without--after-user-id. - When the runs report nothing new to migrate, the data is in sync. Before the switch, run the last sync sweep in sync mode with
--prune-orphans:--gc-handling keep-generic --modified-after <start time of the previous complete sweep> --prune-orphans, first with--dry-runand then for real. It removes the dispatch targets and App Attestations that were deleted by nevisFIDO while it used the generic credentials (see Phase 5.1). Read the log and the report, and make sure that the sweep is complete for every client. nevisFIDO must still use the generic credentials, see the warning above. - To switch nevisFIDO to the dedicated entities, set
credential-repository.use-dedicated-entitiestotruein nevisFIDO (in nevisAdmin 4: Credential Management API = dedicated) and restart nevisFIDO. - After all nevisFIDO instances have switched, run a final sync sweep without
--prune-orphans:--modified-after <start time of the previous complete sweep>, without--after-user-id. It migrates the credentials that were created or changed until nevisFIDO switched. If you limit the run, resume each client with--after-user-idand the same--modified-afteruntil the sweep is complete for every client. Read the log and the report of every run and resolve all errors before the cleanup. - Optionally, remove the migrated generic credentials with
--gc-handling delete-only-if-already-exists(first with--dry-run).
See Migration with the standalone tool for the options and examples.
Option 2: Batch job (three deployments)
The batch job migrates in the background and then keeps the dedicated entities in sync with the old data, while nevisFIDO still uses the old data model. nevisFIDO is switched to the dedicated entities on a day of your choice.
The batch job can run on a separate nevisIDM instance that uses the same database. With a shared database job store, Quartz can execute the job on any scheduler instance in the cluster, so adding an instance alone does not keep the migration load away from the instances that serve the traffic. See Deployment requirements in a cluster.
Deployment 1: dry run
- Create a database backup.
- Add the batch job (pattern nevisIDM FIDO UAF Dispatch Target Migration Job) to the nevisIDM instance. Set
Dry Runtotrue,Max Migrationsto a value higher than the number of FIDO UAF authenticators (so that the dry run goes through all users in one run, or leave it empty),Report Fileto a path on a mounted persistent volume, andCron Expressionso that the job starts shortly after the deployment instead of waiting for the next 02:00. - Deploy and wait for the run to finish. Read the log and the report to find errors, and resolve the reported problems. Repeat the dry run until the report contains only the expected entries.
Deployment 2: migration and sync
- Change the job configuration:
Dry Runtofalse,Generic Credential Handlingtokeep-genericandMax Migrationsto a value that suits your installation (or leave it empty). Set the cron expression to the schedule you want the sync to run with. Deploy. - Let the first migration run through. If
Max Migrationslimits the runs, the job continues after the last processed user in every run. Read the log and the report of every run. The first migration is finished when a run has gone through all users of every client. - Keep the job deployed. From now on every run is a sync run: it migrates the credentials that were created or changed since the start of the previous complete run. Keep reading the log and the report.
Before the switch: remove deleted dispatch targets
- While nevisFIDO still uses the generic credentials, deploy the job with
pruneOrphansset totrue(the nevisAdmin 4 pattern does not offer it, configure the job manually as described in Built-in job types). First run it withdryRunset totrueand check the report, then withdryRunset tofalse. Let it run until a sync sweep has gone through all users of every client, because the orphan removal runs at the end of a complete sweep. It removes the dispatch targets and App Attestations that nevisFIDO already deleted from the generic credentials (see Phase 5.1). - Deploy the job again without
pruneOrphansbefore you switch nevisFIDO.
Never leave pruneOrphans enabled after the switch: the job would delete all dispatch targets and App Attestations that nevisFIDO creates with the dedicated entities. See the warning at the top of this guide.
Day of the switch
- To switch nevisFIDO to the dedicated entities, set
credential-repository.use-dedicated-entitiestotruein nevisFIDO (in nevisAdmin 4: Credential Management API = dedicated) and deploy nevisFIDO. - Wait until a sync sweep that started after all nevisFIDO instances had switched has completed for every client. This is the final sync, it migrates the credentials that were created or changed until the switch. A sweep that was already in progress at the time of the switch does not count. If
Max Migrationslimits the runs, a sweep consists of several runs: keep the job deployed through all of them. Shorten the cron interval in advance if you do not want to wait. Read the log and the report of every run and resolve all errors before you remove the job.
Deployment 3: remove the batch job
- Remove the batch job pattern from the nevisIDM instance and deploy.
If you also want to remove the migrated generic credentials, deploy the job with delete-only-if-already-exists (first with Dry Run), let it run once, read the log and the report, and then remove the job.
See Migration with the batch job and Deployment requirements in a cluster for the details.
Migration approaches
There are two ways to run the migration. Both execute the same migration pipeline (see Migration pipeline), so the results and the report categories are identical.
| Standalone migration tool (JAR) | nevisIDM batch job | |
|---|---|---|
| How it runs | Command-line tool (dispatch-target-migration-tool-<version>.jar) started manually | FidoUafDispatchTargetMigrationJob scheduled inside nevisIDM, or the nevisAdmin 4 pattern nevisIDM FIDO UAF Dispatch Target Migration Job |
| Communication with nevisIDM | REST and SCIM API, needs authentication and permissions | In-process, no REST calls, no extra credentials or permissions |
| Default generic credential handling | disable-generic | keep-generic |
| Default parallelism | 8 threads | 1 thread |
| Progress tracking | Manual, with --after-user-id and --modified-after | Automatic, stored per client in the job; resumes after a limited run and processes only modified users after a complete run |
| Typical use | One-off migration, full control over each run, canary rollout per client | Hands-off migration in the background, large installations, nevisAdmin 4 managed deployments |
Choose the standalone tool if you want to run and review each step by hand. Choose the batch job if you want nevisIDM to migrate in the background in limited runs and catch up with later changes automatically. In nevisIDM and nevisFIDO 9.2605.x, we introduced dedicated entities for dispatch targets and iOS App Attestation data that were previously stored as generic credentials. The nevisFIDO configuration determines which data model is used. This guide describes how to migrate existing data to the new model.
For Nevis ID projects, follow the Nevis ID migration guide instead.
The migration process should be considered irreversible. It is recommended to take a backup of the database before starting the migration,
Depending on the configuration of the migration tool old Generic Credential based dispatch targets will be deleted during the migration process,
Even if they are not deleted, depending on the configuration they maybe set to disabled and cannot be used anymore.
Reactivation of old dispatch targets is heavily discouraged, since the possibility of data drift after migration cannot be ruled out.
Migration and sync modes
The migration runs in one of the following modes. The mode is determined by the options of the tool (or by the progress of the batch job), see the table below.
| Mode | Standalone tool | Batch job | Purpose |
|---|---|---|---|
| Migration (full) | no --modified-after | first run of a client, until all of its users are processed | Migrates every user that has Dispatch Target or App Attestation generic credentials. |
| Sync (incremental) | --modified-after <time> | automatic, after a complete run of a client | Migrates only the changes made since the previous run. |
| Cleanup | --gc-handling delete-only-if-already-exists | gcHandling = delete-only-if-already-exists | Deletes the generic credentials that have been migrated already. |
| Dry run | --dry-run | dryRun = true | Simulates any of the modes above without changing data. |
Migration mode
Migration mode processes all users of the client that have Dispatch Target or App Attestation generic credentials. For each of them it creates the dedicated DispatchTarget (and AppAttestation) entities and assigns them to the FIDO UAF authenticators.
- A FIDO UAF authenticator that already has a
DispatchTargetis not touched. The existing entity is not changed, because the migration cannot tell whether it was created by a previous migration run or by something else. - A large client can be migrated in several runs. Limit a run with
--max-migrations(maxMigrations) and continue after the last processed user with--after-user-id. The batch job does this automatically. Continuing a run does not change the mode, it is still a migration. - The start time of the first migration is the reference time of the sync: everything that changes after it has to be picked up by sync runs.
Sync mode
Sync mode keeps the dedicated entities up to date while the old data model is still in use, for example while nevisFIDO still creates and modifies generic credentials. It is selected with --modified-after in the standalone tool, and the batch job switches to it by itself after it has gone through all users of a client.
- Only the users whose Dispatch Target or App Attestation generic credential was modified at or after the given time are processed. This is cheap compared to a full run.
- New generic credentials are migrated as in migration mode.
- If the FIDO UAF authenticator already has a
DispatchTarget, it is updated in place from the changed source generic credential, instead of being skipped. So changes of the old data are carried over, and nothing is created twice. - Use the start time of the previous sweep (not its end time) as the new
--modified-after, so that the changes made during that sweep are not missed. If a sweep consists of several limited runs, the start time of its first run counts, and all of its runs use the same--modified-after. The batch job stores this time per client itself. - A sync run can be limited and continued the same way as a migration run.
- If the source generic credentials are disabled by the migration (
disable-generic), they count as modified, so the next sync run selects them again. A disabled source generic credential never updates an activeDispatchTarget: the already migrated entity is left unchanged. Disabling an already disabled generic credential does not change it again, so the repeated sync runs converge and select nothing more.
Cleanup mode
Cleanup mode does not create anything. For every generic credential it checks that the dedicated entities created by a previous migration exist and match the generic credential, and only then deletes the generic credential. Use it as the last step, when nevisFIDO uses the dedicated entities and the migration is verified. Generic credentials without a matching dedicated entity (for example because their authenticator is not migrated yet) are reported as ORPHAN_DISPATCH_TARGET and are not deleted. An authenticator that has a DispatchTarget but no matching generic credential is reported as MAPPING_VALIDATION_FAILED. --max-migrations does not apply to this mode.
Dry run
In a dry run the discovery and the pairing of the credentials are executed. The following steps (creation, validation, assignment, disabling, deletion) are only logged, not executed. The checks of the mandatory fields are still executed and reported. The report is written as for a real run, so a dry run shows which problems would occur. The batch job does not store progress in a dry run.
Migration pipeline
The pipeline is the same in every mode, see Migration and sync modes. The steps that behave differently in sync mode are marked with Sync mode.
Phase 1 — Discover users and classify generic credentials
Steps:
- One SCIM filter discovers the users with Dispatch Target generic credentials (
fidouaf_name PR) or App Attestation generic credentials (ios_app_attestation_public_key PR) - The discovered users are processed; each user's generic credentials are fetched once via the Core API
- Generic credentials are classified: those with
fidouaf_name→ Dispatch Target list; those withios_app_attestation_public_key→ App Attestation list - Each generic credential's
stateNamefield is validated: onlyactiveanddisabledare expected - The users are discovered in ascending order of their numeric user ID, in pages (
--tool-page-size/toolPageSize). Each page goes through all the phases. The user ID where the run stopped is the cursor for resuming (--after-user-id) - Sync mode: the SCIM filter is extended with
credentials.meta.lastModified GE '<modified-after time>', so only the users with a recently modified generic credential are discovered. The condition is not scoped to the Dispatch Target or App Attestation credential, so a user whose other credential was modified can be selected too. This only selects more users, no changed user is missed
Possible errors:
USER_CREDENTIALS_LOAD_FAILED— HTTP error fetching a user's generic credentialsUNEXPECTED_CREDENTIAL_STATE— generic credentialstateNameis notactiveordisabled; the credential is skipped
Phase 2 — Pair Dispatch Target generic credentials with App Attestation generic credentials
Steps:
- Dispatch Target generic credentials without
fidouaf_device_idare filtered out - Dispatch Target generic credentials whose
fidouaf_device_idis shared by another Dispatch Target generic credential of the same user are filtered out (the device ID is ambiguous and pairing cannot be determined) - App Attestation generic credentials are indexed by
ios_app_attestation_device_id - Each remaining Dispatch Target generic credential is paired with an App Attestation generic credential by matching device IDs
Possible errors:
MISSING_DEVICE_ID— Dispatch Target generic credential has nofidouaf_device_idDUPLICATE_DEVICE_ID— two or more Dispatch Target generic credentials of the same user share the samefidouaf_device_id; all of them are skipped because pairing is ambiguousUNPAIRED_APP_ATTESTATION— App Attestation generic credential has no matching Dispatch Target generic credential by device ID
Phase 3 — Pair FIDO UAF authenticators with Dispatch Target generic credentials
Steps:
- FIDO UAF authenticators already linked to a DispatchTarget:
- Migration mode: skipped silently. The existing
DispatchTargetis not touched, and the matching generic credential is not reported as orphan - Sync mode: the authenticator is paired with the discovered (modified) Dispatch Target generic credential as below, and the existing
DispatchTargetis updated from it in Phase 5
- Migration mode: skipped silently. The existing
- Pairing strategy (in order, also in cleanup mode):
- Explicit
dispatchTargetExtIdfield on the FIDO UAF authenticator - Fallback: matching
deviceIdbetween the FIDO UAF authenticator and the Dispatch Target generic credential
- Explicit
Possible errors:
FIDO_AUTHENTICATORS_LOAD_FAILED— HTTP/IO error fetching a user's FIDO UAF authenticatorsMAPPING_VALIDATION_FAILED(cleanup mode only) — FIDO UAF authenticator has a linked DispatchTarget but no matching Dispatch Target generic credential was found, or the extId of its DispatchTarget is unknown
Phase 4 — Report orphan Dispatch Target generic credentials
Steps:
- Dispatch Target generic credentials not matched to any FIDO UAF authenticator are identified and reported
- Sync mode: orphan checks apply to the Dispatch Target generic credentials of the users selected in Phase 1
Possible errors:
ORPHAN_DISPATCH_TARGET— Dispatch Target generic credential has no matching FIDO UAF authenticator
Phase 5 — Create DispatchTargets and assign FIDO UAF authenticators
The behaviour of this phase is controlled by --gc-handling for the standalone tool and by gcHandling for the batch job (default: disable-generic for the tool, keep-generic for the batch job).
Per group of FIDO UAF authenticators sharing a Dispatch Target generic credential, the tool sends one item to the create-or-update endpoint of nevisIDM (bulk-sync). nevisIDM does everything in one write transaction:
- Creates the
DispatchTargetfrom the Dispatch Target generic credential, with thestateof the source generic credential. If aDispatchTargetalready exists for the user and the device ID, it is updated in place instead (sync mode only, see Sync mode) - If a paired App Attestation generic credential exists, creates the
AppAttestationof the DispatchTarget - Assigns the DispatchTarget to the (first) FIDO UAF authenticator of the group
- Handles the source generic credentials according to the generic credential handling (see below)
There is no validation of the created entities in this phase, the transaction is rolled back if any step fails. Any further FIDO UAF authenticator of the group is assigned to the new DispatchTarget afterwards, one by one.
In migration mode only authenticators without a DispatchTarget reach this phase, so everything is created. In sync mode the already migrated ones are updated too.
A user can own several DispatchTargets (one per device). --max-migrations / maxMigrations counts DispatchTargets and a user is always migrated completely. The users that did not fit into the limit are processed in the next run.
The migrations are sent to nevisIDM in batches (--migration-batch-size / migrationBatchSize, default 50, at most 100). If any item of a batch fails, the whole batch is rolled back and its items are retried one by one, so only the failing items are reported.
Possible errors:
DISPATCH_TARGET_CREATE_FAILED— a mandatory field of the Dispatch Target generic credential is missing (identification,signingKey,appId,name), or nevisIDM rejected the item, for example because of a duplicate name or identification. This is the category of every failure inside the transaction; the group is skipped, nothing is changed, and the source generic credentials are untouchedAPP_ATTESTATION_CREATE_FAILED— a mandatory field of the App Attestation generic credential is missing (receipt,publicKey,identification). The DispatchTarget is still migrated, but without the App Attestation, and the App Attestation generic credential is left untouched (not disabled or deleted)ASSIGNMENT_FAILED— an exception while assigning an additional FIDO UAF authenticator of the group
disable-generic (default for the tool — staged workflow)
After the creation and the assignment, nevisIDM disables the source Dispatch Target generic credential (stateName becomes disabled) and, if the App Attestation was migrated, the paired App Attestation generic credential. Disabling an already disabled generic credential changes nothing.
delete-generic
After the creation and the assignment, nevisIDM deletes the source Dispatch Target generic credential and, if the App Attestation was migrated, the paired App Attestation generic credential.
keep-generic (default for the batch job)
The source Dispatch Target and App Attestation generic credentials are left completely untouched. Use this if the generic credentials must keep working, or if they are cleaned up separately later with delete-only-if-already-exists.
delete-only-if-already-exists (cleanup mode)
Used after a previous disable-generic or keep-generic run to remove generic credentials that have already been migrated. The user discovery of Phase 1 is the same, so it can be narrowed with --modified-after. --max-migrations does not apply. The pipeline validates and deletes the migrated source credentials per item (the standalone tool uses the REST API, the batch job runs in-process):
Steps:
- Find FIDO UAF authenticators that already have a linked
DispatchTargetand pair them with Dispatch Target generic credentials (bydispatchTargetExtId, then bydeviceId) - Validate that the existing
DispatchTargetentity matches the Dispatch Target generic credential - If an App Attestation generic credential is present, validate the existing
AppAttestationentity - Delete the source Dispatch Target generic credential
- If the Dispatch Target generic credential was deleted successfully and a paired App Attestation generic credential exists, delete the App Attestation generic credential
Possible errors:
ORPHAN_DISPATCH_TARGET— Dispatch Target generic credential has no matching FIDO UAF authenticator with a linked DispatchTarget. This includes generic credentials whose authenticator is not migrated yet. They are not deletedMAPPING_VALIDATION_FAILED— see Phase 3DISPATCH_TARGET_VALIDATION_FAILED— fetched entity fields do not match the source generic credentialAPP_ATTESTATION_VALIDATION_FAILED— fetched App Attestation fields do not match the source generic credentialGENERIC_CREDENTIAL_DELETE_FAILED— exception deleting the source generic credential; the App Attestation generic credential is not deleted if the Dispatch Target generic credential deletion failed
Phase 5.1: Remove orphaned DispatchTargets and App Attestations
This phase is off by default. Run it as the last sync before nevisFIDO is switched to the dedicated entities, in sync (incremental) mode: it needs a complete sweep with keep-generic and --modified-after (batch job: a sync run after the first complete run). Enable it with --prune-orphans for the standalone tool or pruneOrphans for the batch job. It only runs in sync mode (keep-generic with --modified-after / a previous complete sweep), after the whole client was swept. It removes the dedicated entities whose source generic credential no longer exists on the user, for example because nevisFIDO deleted the dispatch target while it still used the old data model:
- nevisIDM pairs every
DispatchTargetwith its source Dispatch Target generic credential by device ID. A generic credential in any state counts as existing, alsodisabled. ADispatchTargetwithout a device ID cannot be paired and is left alone. - A
DispatchTargetwithout a source generic credential is deleted, together with its App Attestation. Its FIDO UAF authenticators are unassigned. - If the source Dispatch Target generic credential still exists but the App Attestation generic credential is gone, only the App Attestation is deleted.
The phase scans at most 1000 users per call and runs until all users that have a DispatchTarget were scanned. It is not limited by --max-migrations / maxMigrations.
This phase deletes every dedicated DispatchTarget and App Attestation that has no corresponding generic credential. After nevisFIDO is switched to the dedicated entities, all dispatch targets and App Attestations it creates have no generic credential, so this phase would delete them all.
Only run it on a system that is not yet switched to the dedicated entities, and do not run it again after the switch. Run it with --dry-run / dryRun first to see what would be deleted.
Possible errors:
DISPATCH_TARGET_DELETE_FAILED: an exception while deleting an orphanedDispatchTarget. The phase continues.APP_ATTESTATION_DELETE_FAILED: an exception while deleting an orphaned App Attestation. The phase continues.ORPHAN_SCAN_FAILED: the orphan query, or the removal of the orphans of a page, failed. The phase stops, the other results of the run are kept.
In simulation mode (--dry-run / dryRun) all steps are logged but not executed.
Error and failure categories
All skipped and failed entities are written to a CSV report. The standalone tool uses a timestamped filename by default. The batch job writes a report only when reportFile is configured. Each run overwrites an explicitly configured report path, so save or collect that file before the next run.
| Category | Phase | Mode | Entity type referenced by entityExtId | Trigger |
|---|---|---|---|---|
USER_CREDENTIALS_LOAD_FAILED | 1 | all | user ¹ | HTTP error fetching a user's generic credentials |
UNEXPECTED_CREDENTIAL_STATE | 1 | all | generic credential | Generic credential stateName (API response field) is not active or disabled |
MISSING_DEVICE_ID | 2 | all | Dispatch Target generic credential | Dispatch Target generic credential has no fidouaf_device_id |
DUPLICATE_DEVICE_ID | 2 | all | Dispatch Target generic credential | Two or more Dispatch Target generic credentials of the same user share the same fidouaf_device_id; all are skipped because pairing is ambiguous |
UNPAIRED_APP_ATTESTATION | 2 | all | App Attestation generic credential | App Attestation generic credential has no matching Dispatch Target generic credential by device ID |
FIDO_AUTHENTICATORS_LOAD_FAILED | 3 | all | user ¹ | HTTP/IO error fetching a user's FIDO UAF authenticators |
MAPPING_VALIDATION_FAILED | 3 ² | cleanup | FIDO UAF authenticator, or Dispatch Target generic credential ³ | FIDO UAF authenticator has a linked DispatchTarget but no matching Dispatch Target generic credential was found, or the extId of its DispatchTarget is unknown |
ORPHAN_DISPATCH_TARGET | 4 | all | Dispatch Target generic credential | Dispatch Target generic credential has no matching FIDO UAF authenticator (in cleanup mode: with a linked DispatchTarget) |
DISPATCH_TARGET_CREATE_FAILED | 5 | migration, sync | Dispatch Target generic credential | Mandatory field missing (identification, signingKey, appId, name), or nevisIDM rejected the bulk-sync item (any exception, for example duplicate name or identification). Also reported in a dry run for missing fields |
APP_ATTESTATION_CREATE_FAILED | 5 | migration, sync | App Attestation generic credential | Mandatory field missing (receipt, publicKey, identification); the DispatchTarget is migrated without App Attestation and the App Attestation generic credential is left untouched |
ASSIGNMENT_FAILED | 5 | migration, sync | FIDO UAF authenticator | Exception while assigning an additional FIDO UAF authenticator of a group to the new DispatchTarget |
DISPATCH_TARGET_VALIDATION_FAILED | 5 | cleanup | Dispatch Target generic credential | Fetched entity fields do not match the source generic credential; the generic credential is not deleted |
APP_ATTESTATION_VALIDATION_FAILED | 5 | cleanup | App Attestation generic credential | Fetched App Attestation entity fields do not match the source generic credential; the generic credential is not deleted |
GENERIC_CREDENTIAL_DELETE_FAILED | 5 | cleanup | generic credential | Exception deleting the source generic credential; the App Attestation generic credential is not deleted if the Dispatch Target generic credential deletion failed |
DISPATCH_TARGET_DELETE_FAILED | 5.1 | sync | DispatchTarget | Exception while deleting an orphaned DispatchTarget (--prune-orphans / pruneOrphans) |
APP_ATTESTATION_DELETE_FAILED | 5.1 | sync | DispatchTarget | Exception while deleting an orphaned App Attestation (--prune-orphans / pruneOrphans) |
ORPHAN_SCAN_FAILED | 5.1 | sync | client (value: last user ID scanned) | The orphan query or the removal of the orphans of a page failed; the phase stops, the other results of the run are kept |
¹ For user-level failures entityExtId duplicates userExtId — there is no finer-grained entity to reference.
² In cleanup mode (delete-only-if-already-exists) this check happens during Phase 3 pairing.
³ The authenticator if it has no matching generic credential, the generic credential if the extId of the assigned DispatchTarget is unknown.
Migration with the standalone tool
CLI options reference
| Option | Required | Default | Description |
|---|---|---|---|
--base-url / -b | yes | — | nevisIDM base URL, e.g. https://idm.example.com/nevisidm/api |
--client-ext-id / -c | yes | — | Client extId(s) to migrate; comma-separated or repeated |
--scim-query-page-size | no | 200 | Number of records fetched per SCIM request. --page-size is a deprecated alias for this option. |
--tool-page-size | no | 0 (unbounded) | Maximum number of users discovered before one full migration pass is run and discovery continues where it left off. Bounds the memory usage for very large clients. |
--threads | no | 8 | Number of worker threads issuing REST calls concurrently. Use 1 for sequential processing. A higher value speeds up large migrations but increases the load on nevisIDM. |
--migration-batch-size | no | 50 | Number of migrations sent to nevisIDM in one request (maximum 100, 1 disables batching). |
--dry-run | no | false | Simulate without executing any API writes (creation, validation, assignment, deletion are all logged but not executed) |
--report-file | no | auto | Path for the CSV report (migration-report-<timestamp>.csv, or simulation-report-<timestamp>.csv with --dry-run, if omitted) |
--gc-handling | no | disable-generic | Generic credential handling after migration: disable-generic (disable source generic credential; App Attestation generic credential disabled only if Dispatch Target generic credential disable succeeded), delete-generic (delete source generic credential; same conditional applies), keep-generic (leave source generic credentials untouched), delete-only-if-already-exists (cleanup: validate existing mapping and delete generic credentials) |
--modified-after | no | — | Only discover users who have a generic credential modified at or after this time (ISO-8601, e.g. 2026-09-01T00:00:00Z). Changes to other credential types can also select a user. Enables incremental re-runs. The time is interpreted in the time zone of the nevisIDM server, see Time zone of the modified-after time. |
--max-migrations | no | unlimited | Maximum number of DispatchTargets migrated in the whole run (ignored in delete-only-if-already-exists mode). The remaining ones are not attempted; re-run to continue. |
--after-user-id | no | — | Resume discovery after this numeric user ID instead of starting from the beginning. Each run logs the last processed user ID. |
--prune-orphans | no | false | Enables Phase 5.1: a keep-generic run with --modified-after finishes by deleting the DispatchTargets and App Attestations whose source generic credential no longer exists. |
--request-timeout-seconds | no | 300 | Timeout of every single HTTP call |
--keystore | cert auth | — | Path to client PKCS12/JKS keystore |
--keystore-password | no | — | Keystore password. Env var: IDM_MIGRATION_KEYSTORE_PASSWORD. Prompted interactively if absent. |
--keystore-type | no | PKCS12 | PKCS12 or JKS |
--truststore | no | — | Path to truststore for server certificate verification |
--truststore-password | no | — | Truststore password. Env var: IDM_MIGRATION_TRUSTSTORE_PASSWORD. Prompted if truststore is configured and absent. |
--truststore-type | no | PKCS12 | PKCS12 or JKS |
--username / -u | basic auth | — | Username for Basic Auth (testing only). The user must not belong to any migrated client. |
--password / -p | no | — | Basic Auth password. Env var: IDM_MIGRATION_BASIC_AUTH_PASSWORD. Prompted interactively if absent. |
--bearer | bearer auth | — | Selects Bearer token authentication |
--bearer-token / -t | no | — | Bearer token sent as Authorization: Bearer <token>. Env var: IDM_MIGRATION_BEARER_TOKEN. Prompted interactively if absent. |
Time zone of the modified-after time
The standalone tool sends the --modified-after time to nevisIDM as a SCIM filter without a time zone offset, and nevisIDM interprets it in the time zone of the server it runs on. The Z suffix is not converted, so the value must be the time in the time zone of the nevisIDM server, even though it is written with Z.
- If the nevisIDM server runs in UTC (the common case for containerized deployments), use UTC times, for example from
date -u +%Y-%m-%dT%H:%M:%SZ. - If it does not, query the time zone of the server with the system REST service,
GET /core/<version>/system/timezone(the<version>is the version of the nevisIDM Core REST API, v1.16 or later), and note the local time of that time zone instead, for example withTZ=<time zone> date +%Y-%m-%dT%H:%M:%SZ.
The batch job is not affected: it handles its progress times itself, independent of the time zone of the server.
Preparation
- Download the migration tool from Nevis Portal and extract it to a directory. Java 25 or later is required to run it.
- Create a database backup before starting the migration.
- Decide how to handle the source generic credentials (
--gc-handling). To verify the result before removing any data, migrate withkeep-genericordisable-genericfirst and clean up later withdelete-only-if-already-exists. - Prepare the certificates (see below).
Prepare the certificates
The tool authenticates against the nevisIDM REST API with a client certificate (two-way TLS). Two stores are involved:
| Store | Purpose | CLI options |
|---|---|---|
| Keystore | Contains the client certificate with its private key and the CA chain. It is presented to nevisIDM. | --keystore, --keystore-password, --keystore-type |
| Truststore | Contains the CA certificate that signed the TLS certificate of nevisIDM. Needed only if nevisIDM uses a private CA. If omitted, the trust anchors of the JVM are used. | --truststore, --truststore-password, --truststore-type |
- Obtain a client certificate that identifies a technical nevisIDM user and that nevisIDM trusts. nevisIDM must be configured for two-way TLS and its truststore (
server.tls.truststore) must contain the CA of the client certificate. See Configuring certificate login (2-way TLS) for accessing nevisIDM. - Build the PKCS12 keystore from the certificate, the private key and the CA certificate:
openssl pkcs12 -export \
-in client-certificate.pem \
-inkey client-key.pem \
-certfile ca.pem \
-out keystore.p12 \
-name migration \
-passout pass:keystorepassword
- If nevisIDM uses a private CA, import the CA certificate into a truststore:
keytool -importcert \
-file ca.pem \
-keystore truststore.p12 \
-storetype PKCS12 \
-storepass truststorepassword \
-alias nevisidm-ca \
-noprompt
- Pass the stores to the tool with
--keystoreand--truststore. Passwords can be given with--keystore-passwordand--truststore-password, with theIDM_MIGRATION_KEYSTORE_PASSWORDandIDM_MIGRATION_TRUSTSTORE_PASSWORDenvironment variables, or entered when prompted.
Migration steps
1. Dry run
java -jar dispatch-target-migration-tool-<version>.jar --base-url https://yourdomain.com/nevisidm/api \
--keystore /home/youruser/nevis/nevisidm/dispatchtargetmigration/keystore.p12 \
--truststore /home/youruser/nevis/nevisidm/dispatchtargetmigration/truststore.p12 \
--client-ext-id 100,yourClient \
--report-file /home/youruser/nevis/nevisidm/dispatchtargetmigration/migration_report.csv \
--dry-run
Read the log and the report. Investigate and resolve the errors and unexpected results before proceeding. --report-file should point to a persistent location.
2. First migration
Note the current time (see Time zone of the modified-after time), for example on a server running in UTC:
date -u +%Y-%m-%dT%H:%M:%SZ
This is the start time of the first migration, T0. Run the tool again without --dry-run and set --gc-handling keep-generic explicitly, because the default (disable-generic) would disable the credentials that nevisFIDO still uses. nevisFIDO does not have to be stopped. Read the log and the report.
For large clients limit the size of the run with --max-migrations (maximum number of migrations in the whole run) and, to bound the memory usage, --tool-page-size.
3. Resuming a limited run
If the run was limited with --max-migrations and the limit was reached, users are left. The tool processes the users in ascending order of their numeric user ID, so the next run can continue after the last processed user:
- Find the user ID where the run stopped. The tool logs it at the end of the run for every client:
Client 'yourClient': last processed userId = 123456 (pass as --after-user-id to resume from here).
If you do not have the log, look up the user ID with the SCIM API. For the external ID of the last processed user (for example the last user in the log or in the report) call:
GET /scim/v1/{client}/Users?filter=externalId EQ '<userExtId>'
The id field of the returned resource is the user ID. The tool itself discovers the users with the SCIM sorting sortBy=id and the filter id GT <userId>.
- Run the tool again with the same options and
--after-user-id 123456. - Repeat until a run finishes without reaching the limit.
T0stays the reference time of the whole sweep. Do not use the time of the last run.
--after-user-id is per run and the same value applies to every client of the run. If you migrate several clients in one run, resume client by client.
4. Keep the data in sync
After a complete sweep the data is migrated up to T0. Since the users and their devices keep registering, run the tool repeatedly to process only what changed since the previous sweep. Use --modified-after with the noted start time:
java -jar dispatch-target-migration-tool-<version>.jar --base-url https://yourdomain.com/nevisidm/api \
... \
--client-ext-id 100,yourClient \
--modified-after 2026-11-01T08:00:00Z
- The value is an ISO-8601 time. The
Zsuffix is only the required format: the tool does not convert the time, and the nevisIDM server interprets it in its own time zone. See Time zone of the modified-after time. - The tool selects the users whose Dispatch Target or App Attestation generic credential was modified at or after this time. Use the start time of the previous sweep (not its end time), so that nothing changed during that sweep is missed.
- If a sync sweep is limited with
--max-migrations, resume it with--after-user-idand the same--modified-afteruntil it has gone through all users. Do not move--modified-afterto the start time of a continuation run, because changes to users that were already processed in this sweep would be missed. - Note the start time of the first run of every sweep. Use it as
--modified-afterof the next sweep, and start that sweep without--after-user-id. - In a run with
--modified-afterthe tool updates the already migrated DispatchTargets in place from their changed source generic credentials, instead of creating them again. Without--modified-after(also with--after-user-idonly) already migrated entries are left untouched. Generic credentials disabled by the tool itself (disable-generic) are selected again because disabling changes their modification time, but a disabled source generic credential never updates an active DispatchTarget.
5. Remove deleted dispatch targets (prune orphans)
When the incremental runs have nothing left to migrate, run the last sync sweep before the switch in sync mode with --prune-orphans. It removes the DispatchTargets and App Attestations whose generic credential was already deleted by nevisFIDO (see Phase 5.1). Run it with --dry-run first, check the report, then run it for real:
java -jar dispatch-target-migration-tool-<version>.jar --base-url https://yourdomain.com/nevisidm/api \
... \
--client-ext-id 100,yourClient \
--gc-handling keep-generic \
--modified-after 2026-11-01T08:00:00Z \
--prune-orphans
Only run --prune-orphans while nevisFIDO still uses the generic credentials. It deletes every dedicated DispatchTarget and App Attestation without a corresponding generic credential, so after the switch it would delete all new dispatch targets and App Attestations created by nevisFIDO. Do not use it in the final sync (step 7) or any run after the switch.
6. Switch nevisFIDO to the dedicated entities
When the last sync sweep with --prune-orphans is complete for every client, the data is in sync. To switch nevisFIDO to the dedicated entities, set credential-repository.use-dedicated-entities to true in nevisFIDO (in nevisAdmin 4: Credential Management API = dedicated) and restart nevisFIDO.
7. Final sync
Run it without --prune-orphans. After all nevisFIDO instances have switched, run a complete sync sweep with --modified-after set to the start time of the last complete sweep before the switch, and without --after-user-id. It migrates the credentials that nevisFIDO created or changed with the old data model until the switch. If you limit the sweep with --max-migrations, resume every client with --after-user-id and the same --modified-after until the sweep has gone through all users of every client. Read the log and the report of every run, and make sure that there are no errors left. Do not start the cleanup before the final sweep is complete.
8. Cleanup (optional)
Remove the migrated generic credentials by running the tool with --gc-handling delete-only-if-already-exists. Run it with --dry-run first. The tool validates that the dedicated entities match the generic credentials before it deletes them.
Migration with the batch job
The FidoUafDispatchTargetMigrationJob batch job runs the migration inside nevisIDM, without REST calls. See FidoUaf DispatchTarget Migration Job for the configuration fields. The job works per client:
- If a run is limited (for example by
maxMigrations), the next run continues after the last processed user. - After a sweep has gone through all users of a client, the next sweep processes only the users modified since the start of the first run of the completed sweep.
- In dry-run mode no progress is stored, so a dry run does not influence later runs.
The job uses the same gcHandling values as the standalone tool, but its default is keep-generic, so nothing is disabled or deleted unless you configure it.
Configuring the job with nevisAdmin 4
pruneOrphansThe pruneOrphans job parameter deletes every dedicated DispatchTarget and App Attestation that has no corresponding generic credential. A batch job runs on a schedule, so if pruneOrphans stays enabled after nevisFIDO is switched to the dedicated entities, the next run deletes all dispatch targets and App Attestations that nevisFIDO created since the switch.
- Enable it only while nevisFIDO still uses the generic credentials, and first with
dryRunset totrue. - Deploy the job again without
pruneOrphansbefore you switch nevisFIDO. - Never enable it on a system that already uses the dedicated entities.
In nevisAdmin 4 the job is configured with the pattern nevisIDM FIDO UAF Dispatch Target Migration Job (category Identity Management / Add-ons, marked Experimental).
- Create the pattern and add it to the
Additional Settingsof thenevisIDM Instancepattern. - Make sure that
Batch Job Storeof thenevisIDM Instanceisdb(see Deployment requirements in a cluster). - Deploy the project.
The pattern generates a Quartz job (ch.nevis.idm.batch.jobs.FidoUafDispatchTargetMigrationJob, group BatchGroup) and a cron trigger into /var/opt/nevisidm/idm/conf/batch.xml of the nevisIDM instance. The job and the trigger are named after the job identity (FidoUafDispatchTargetMigration and FidoUafDispatchTargetMigration_Trigger by default).
| Pattern property | Job parameter | Default | Description |
|---|---|---|---|
| Client External IDs | clientExtIds | — (required) | Comma-separated list of the external IDs of the clients to migrate, for example client1,client2. The clients are processed in the given order. Whitespace around the IDs is ignored and at least one client is required. |
| Cron Expression | cron trigger | 0 0 2 * * ? | When the job runs (every day at 02:00 by default). Quartz syntax with 6 or 7 fields. The pattern checks the number of fields, the range of the numeric values and that exactly one of day-of-month and day-of-week is ?. |
| Dry Run | dryRun | false | If true, the job only reports what it would migrate and does not change any data. No progress is stored, so a dry run does not influence the later runs. |
| Generic Credential Handling | gcHandling | keep-generic | What happens to the source generic credential: keep-generic, disable-generic, delete-generic or delete-only-if-already-exists (see Migration pipeline). |
| Threads | threads | 1 | Number of threads used to migrate in parallel. Whole number from 1 to 64. |
| Migration Batch Size | migrationBatchSize | 50 | Number of DispatchTargets migrated per batch. Whole number, at least 1. |
| Tool Page Size | toolPageSize | 1000 | Number of users discovered per page. 0 disables paging. Whole number, at least 0. |
| Max Migrations | maxMigrations | not limited | Maximum number of DispatchTargets migrated per run, summed over all clients. Further runs continue where the previous one stopped. Whole number, at least 1. |
| Report File | reportFile | — | Path of a CSV file on the nevisIDM host that the skipped and orphaned records of each run are written to. The parent directory must exist and be writable by the nevisIDM user. The file is overwritten at every run, so with a daily schedule collect it before the next run. If not set, only a summary is logged. Example: /var/opt/nevisidm/idm/log/fido-dispatch-migration-report.csv. |
The pattern shows an information message when Dry Run is false and Generic Credential Handling is delete-generic or delete-only-if-already-exists: the generic credentials are deleted on the first scheduled run, and again from the start if the Job Identity is changed. Run with Dry Run first and review the report.
The pattern does not offer the pruneOrphans parameter, and it must only be used before nevisFIDO is switched to the dedicated entities (see the warning at the top of this guide). To remove orphaned DispatchTargets with the batch job (see Phase 5.1), configure the job manually as described in Built-in job types, or use the standalone tool with --prune-orphans.
Advanced settings
These properties are not needed for a normal migration.
| Pattern property | Description |
|---|---|
| Job Identity | Overrides the name that identifies the job and its trigger in the Quartz scheduler. By default the identity is the fixed value FidoUafDispatchTargetMigration, independent of the display name of the pattern, so it stays the same if the pattern is renamed or deleted and recreated. Set it only to run more than one migration job on the same nevisIDM instance. Each job needs a distinct identity, nevisAdmin 4 rejects duplicates (also against other batch job patterns). The progress is stored per job identity, so changing the identity after the deployment creates a new job that starts from the beginning. The previous job is not removed automatically. |
| Last Migrated User IDs | Comma-separated clientExtId=userId pairs that set the migration cursor (the last migrated user ID) per client, for example client1=12345,client2=67890. Clients without an entry start from the beginning. |
| Previous Complete Run Started | Comma-separated clientExtId=timestamp pairs that set when the last complete migration run started, per client. The timestamp is in epoch milliseconds, for example client1=1767225600000. This is the time the sync mode continues from. |
| Current Run Started | Comma-separated clientExtId=timestamp pairs (epoch milliseconds) that set when the migration run currently in progress started, per client. |
Only clients listed in Client External IDs are allowed in the progress properties, and the entries must have the format clientExtId=<number>.
The progress properties are written to the Quartz job at every nevisIDM startup and replace the progress stored in the job store. Use them only to transfer the progress, for example to a job with a new Job Identity or to another environment, and remove them afterwards. Otherwise every restart resets the progress to the configured value. If they are not set, nevisAdmin 4 does not generate them, and the job keeps its own progress.
Starting the job from existing progress
The advanced progress properties of the pattern (Last Migrated User IDs, Previous Complete Run Started, Current Run Started) set the progress that the job normally keeps itself. Use them if the job should not start from the beginning, for example:
- The first migration was done with the standalone tool. Set
Previous Complete Run Startedto the start time (T0) of the tool's complete sweep, as epoch milliseconds per client, for exampleclient1=1767225600000. The job then starts directly in sync mode, as if the tool had been run with--modified-after, and does not go through all users again. Use the start time of the sweep, not its end time. Convert the UTC time, for example withdate -u -d 2026-11-01T08:00:00Z +%s%3N. - The first migration is only partly done. Set
Last Migrated User IDsto thelast processed userIdof the tool's last run (or of the job in another environment), so that the job continues after that user. SetCurrent Run Startedto the start time of that sweep, so that the sweep is later promoted to the sync time correctly. - The job is recreated. Changing the
Job Identitycreates a new job without progress. Copy the progress of the old job to the new one with these properties.
Only clients listed in Client External IDs may appear in the properties, and the format is clientExtId=<number>.
The properties are written to the job at every nevisIDM startup and replace the progress stored in the job store. If you leave them set, a restart of nevisIDM resets the progress to the configured value, so the job processes the changes since that time again. Remove the properties in the next deployment after the job has taken over the progress. A dry run does not store progress, so it cannot be used to prepare them.
Migration steps (batch job)
- Create a database backup.
- Dry run. Deploy the job with
Dry Runenabled andMax Migrationshigher than the number of FIDO UAF authenticators (or not set), so that all users are processed in one run. Set the cron expression close to the deployment time. Read the log ofch.nevis.idm.batch.jobs.FidoUafDispatchTargetMigrationJoband the report, and resolve the reported problems. - Migration. Deploy the job again with
Dry Rundisabled andkeep-generic. SetMax Migrationsif the runs should be limited. Read the log and the report after every run until the job has gone through all users of every client. - Sync. Keep the job deployed. Later runs process only the users modified since the previous complete run.
- Prune orphans. Before the switch, while nevisFIDO still uses the generic credentials, run the job with
pruneOrphansenabled (first withdryRun) until a sync sweep has gone through all users of every client, then deploy again withoutpruneOrphans. The pattern does not offer it, so configure it manually. Never leave it enabled after the switch, it would delete all dispatch targets and App Attestations that nevisFIDO creates with the dedicated entities. - Switch. On the day of your choice, set
credential-repository.use-dedicated-entitiestotruein nevisFIDO (in nevisAdmin 4: Credential Management API = dedicated). The final sync is the first complete sweep (all runs, for every client) that started after all nevisFIDO instances had switched. Read the log and the report of every run of it. - Remove. Deploy again without the batch job pattern.
Deployment requirements in a cluster
These requirements apply if nevisIDM runs with more than one instance (for example several replicas in Kubernetes).
Batch job
- Use the database job store. Set
Batch Job Storeof thenevisIDM Instancepattern todb(the default). The Quartz scheduler of nevisIDM then runs clustered, and a job is executed by only one instance at a time. Withramevery replica has its own scheduler: the job would run on all replicas in parallel and the progress would be lost at every restart. Useramonly with a single replica. - Keep the job identity unique and stable. The progress (last processed user, run timestamps) is stored in the job store per job identity. Changing
Job Identityafter the deployment creates a new job that starts from the beginning, and the old job is not removed. Two migration jobs on the same instance need different identities. - Do not leave the progress parameters set. The values of
Last Migrated User IDs,Previous Complete Run StartedandCurrent Run Startedare written to the job store at every nevisIDM startup, so a rolling update or a restart of a replica would reset the progress. - Plan the report file.
Report Fileis written on the instance that runs the job, which can be any replica, and the file is lost with the container unless the directory is on a persistent volume. Mount a writable volume at the same path on every replica, or omitReport Fileand use the summary in the log. The file is overwritten at every run, so a scheduled sync run replaces the report of the previous run: read or copy it after every run. - A separate instance is possible. The job can run on a separate nevisIDM instance that uses the same database (and the same
Batch Job Storesetting). With a shared database job store, Quartz can fire the job on any cluster member, so a separate instance alone does not isolate the migration load from the instances that serve the traffic. The instance needs access to the database and a persistent volume for the report file. - Plan the load. The job runs on one replica, but it writes to the shared database. Increase
Threadscarefully, and run large migrations outside of peak hours (adjustCron Expression) and in limited runs (Max Migrations). - Database and version. All replicas must run the same nevisIDM version (9.2605.x or later) so that every replica knows the new data model. Create a database backup before the first non-dry run.
Standalone tool
- Run the tool outside of the cluster (or in a separate job or pod) and point
--base-urlto the load-balanced URL of nevisIDM. No change of the nevisIDM deployment is needed. - The tool authenticates against the nevisIDM REST API. The endpoint used must accept the chosen authentication method (client certificate, bearer token or, for testing only, Basic Auth).
- Do not run the tool and the batch job on the same client at the same time.
- Every replica serves the requests, so the load is distributed. Choose
--threadsaccording to the number of replicas.
nevisFIDO
nevisFIDO 9.2605.x uses the old or the new data model according to credential-repository.use-dedicated-entities. nevisFIDO 9.2611 and later always use the new data model. Switch it to the new entities only after the migration has gone through all users, and restart all nevisFIDO instances.
Permissions
This section applies to the standalone tool. The batch job runs inside nevisIDM and needs no permissions.
Generally we advise to have a ClientRoot or Root user for the migration, since they have permissions to access all required API endpoints and perform all necessary operations. If such a user is not available, here are the list of the endpoints that the user needs to have access to, and the required permissions for each endpoint (please check our API documentation for the exact permissions required for each endpoint):
| Method | Path | Purpose |
|---|---|---|
GET | /scim/v1/{client}/Users?filter=... | Discover users with matching generic credential properties |
POST | /core/v1/clients/{client}/generic-credentials/bulk-query | Fetch the generic credentials of up to 100 users |
POST | /core/v1/clients/{client}/fido-authenticators/bulk-query | Fetch the FIDO UAF authenticators of up to 100 users |
POST | /core/v1/{client}/fido-dispatch-target-migrations/bulk-sync | Create or update up to 100 DispatchTargets (and App Attestations), assign them to FIDO UAF authenticators and disable, delete or keep the source generic credentials. Needs CredentialModify, DispatchTargetModify, CredentialCreate or DispatchTargetCreate, and CredentialDelete for delete-generic |
POST | /core/v1/{client}/users/{user}/fido-authenticators/{fido}/dispatch-target/{dt} | Assign the DispatchTarget to the additional FIDO UAF authenticators of a group |
PATCH | /core/v1/{client}/users/{user}/fido-authenticators/{fido} | Update a FIDO UAF authenticator during the assignment of the additional authenticators |
Only for the cleanup mode (delete-only-if-already-exists):
| Method | Path | Purpose |
|---|---|---|
GET | /core/v1/{client}/users/{user}/dispatch-targets/{dt} | Validate the existing DispatchTarget entity |
GET | /core/v1/{client}/users/{user}/dispatch-targets/{dt}/app-attestation | Validate the existing App Attestation entity |
DELETE | /core/v1/{client}/users/{user}/generic-credentials/{gc} | Delete the source generic credential |