Migrating Dispatch Target From Generic Credentials to Dedicated Entities

Does this guide apply to your project?

This guide applies only to projects that contain a nevisFIDO UAF Instance pattern. If your project does not contain this pattern, you can ignore this page.

Use this guide if you are the integrator responsible for a customer project, whether you work for Nevis or the customer. Nevis ID support can assist with configuration, migration checks, and troubleshooting.

Dispatch target and App Attestation migration

Older nevisFIDO UAF configurations store dispatch targets and iOS App Attestation data as Generic credentials in nevisIDM. The migration creates dedicated entities for this data and associates the dispatch targets with the existing FIDO UAF authenticators. It does not provision new authenticators or require users to register their devices again.

This is a migration within the existing identity store, not a SCIM user migration.

Complete the migration before using a newer release

You must not select or deploy a Nevis ID release newer than nevisid-9.2610.0 until the migration has completed. Configuring the job or completing a dry run is not sufficient: the live migration must have run and migrated the existing data.

For affected projects, migrate with nevisid-9.2610.0 before moving to a newer Nevis ID release:

Release	nevisFIDO behavior	Required action
nevisid-9.2610.0	Continues to use and create Generic credentials. The migration job copies the relevant data to dedicated entities and keeps the Generic credentials.	Manually configure and deploy the migration job, then let it migrate and synchronize the data.
Newer than nevisid-9.2610.0	No longer supports the Generic-credential-based implementation.	Do not use until the migration has completed. Keep the migration job configured to process remaining cases after the upgrade.

Nevis coordinates the availability of newer releases after checking migration status. Do not skip the migration-stage release. For release-specific changes and required actions, see the Nevis ID Changelog.

Before you start

1. Check that the project contains a nevisFIDO UAF Instance pattern.
2. When nevisid-9.2610.0 becomes available in the Nevis ID Release drop-down of the project, select it. This release includes pattern version 9.2611.0.65.
3. Before a live migration, coordinate with Nevis ID support to confirm that a database backup is available and that you can review the migration logs for the target environment.

Selecting the release does not configure the migration job for you. Add and assign the pattern as described below before deploying the project with this release.

Step 1: Configure an initial dry run

An initial dry run is recommended. It discovers and pairs the existing data and checks mandatory fields without changing migration data or saving progress.

1. Add the nevisIDM FIDO UAF Dispatch Target Migration Job pattern to the project.
2. Open the nevisIDM Instance pattern and add the migration job to Additional Settings.
3. Configure the migration job:

Setting	Value	Reason
Client External IDs	100	Nevis ID end users are always in the default nevisIDM client 100. Enter this value explicitly.
Dry Run	enabled	Review the data before performing a live migration. The pattern default is disabled, which performs live writes.
Generic Credential Handling	keep-generic	Leave the Generic credentials usable while nevisFIDO still uses them.
Cron Expression	0 0 2 * * ?, or a schedule for earlier feedback	The default runs once per night at 02:00 in the nevisIDM server time zone. For the dry run, choose a schedule that starts soon after deployment instead of waiting until the next night.
Max Migrations	Leave empty, or agree a limit with Nevis ID support	Empty means no configured migration limit per run. See Migration limit per scheduled run.

Keep the remaining settings at their defaults unless Nevis ID support advises otherwise. See Optional settings.

Keep the Generic credentials

Use keep-generic for this procedure. In nevisid-9.2610.0, nevisFIDO still uses Generic credentials. Disabling or deleting them can interrupt mobile authentication.

Step 2: Deploy and review the dry run

1. Deploy the project to the intended environment.
2. For immediate feedback, start the migration batch job manually in the nevisIDM UI. Open User management > Advanced settings in the management console to access this UI. Alternatively, wait for the next scheduled run to finish.
3. Review the migration logs. The job logger is ch.nevis.idm.batch.jobs.FidoUafDispatchTargetMigrationJob.
4. Investigate reported problems with Nevis ID support before starting the live migration. Repeat the dry run after resolving them.

Manual execution requires permission to execute batch jobs, respects the configured Dry Run setting, and leaves the recurring schedule in place. Deployment alone activates the schedule; it does not immediately execute the job.

For repeated feedback, especially during the dry run, you can also temporarily change Cron Expression. For example, 0 0/15 * * * ? schedules a run every 15 minutes. This starts runs at quarter-hour boundaries, not 15 minutes after deployment. Confirm the effective server time zone with Nevis ID support if needed, review the results before the next run, and choose an interval appropriate for the workload.

Typical findings include missing or duplicate device IDs, dispatch targets without a matching FIDO UAF authenticator, and App Attestation data that cannot be paired with a dispatch target. Do not delete credentials merely to clear these findings.

If Max Migrations limits the dry run, it may not inspect all users. A dry run does not save progress, so repeating it does not continue from the previous run. Coordinate a complete review with Nevis ID support.

Limits of a dry run

A dry run does not create, update, assign, disable, or delete entities. It cannot prove that all live writes will succeed. Review the results of live runs as well.

Step 3: Start the live migration

1. Change Dry Run to disabled.
2. Keep Client External IDs set to 100 and Generic Credential Handling set to keep-generic.
3. If you changed Cron Expression for the dry run, set it to the desired ongoing schedule, for example the default nightly schedule 0 0 2 * * ?.
4. Deploy the project again.
5. Start the job manually or wait for the next scheduled run to finish.
6. Review the migration logs.
7. Contact Nevis ID support about skipped or failed records.

The job migrates in the background while nevisFIDO continues to use the Generic credentials. If a live run is limited, subsequent scheduled runs continue from the saved progress. After a complete pass through the users of client 100, the job performs incremental synchronization to pick up later changes.

Keep the job configured. New registrations in nevisid-9.2610.0 still create Generic credentials, so a single migration run is not sufficient to keep the dedicated entities synchronized.

Do not change Job Identity or set the advanced progress fields during normal operation. The job maintains its progress; changing the identity or overriding progress can cause data to be processed again.

Step 4: Inspect users and prepare for a newer release

To inspect individual users:

1. In the management console, select the environment you deployed to.
2. Open User management > Advanced settings.
3. In the embedded nevisIDM administration interface, inspect users and their mobile authentication data in default client 100. Nevis ID support can help interpret the migrated data.

Generic credentials remain present with keep-generic. Their presence alone does not mean that migration failed. Checking individual users also does not establish that the entire migration is complete.

Continue reviewing scheduled runs and resolve reported problems with Nevis ID support. Migration is a prerequisite for upgrading beyond nevisid-9.2610.0; Nevis coordinates the availability of the next release after checking migration status. The integrator decides when to select and deploy an available release.

Step 5: Keep the job after upgrading

1. Only after the migration has completed, select a release newer than nevisid-9.2610.0.
2. Confirm that the migration job remains assigned to the nevisIDM Instance.
3. Confirm that Dry Run is set to disabled so that remaining cases can be migrated.
4. Deploy the project with the migration job.

Remaining cases can fail mobile authentication temporarily

Newer releases no longer support the Generic-credential-based implementation. A device whose data has not yet been migrated can fail mobile authentication until a successful job run processes it.

The remaining workload is expected to be small, but recovery time depends on the schedule, processing limits, and successful execution. With the default nightly schedule, an affected device may have to wait until the next scheduled run. Contact Nevis ID support if failures persist.

Do not remove the job after the upgrade or switch it to a credential-deletion mode as part of this procedure.

Optional settings

You do not need to configure every advanced field for a normal migration.

Setting	Default	Guidance
Threads	1	Retain this conservative starting point. Coordinate increases with Nevis ID support because they increase database load.
Migration Batch Size	50	Number of dispatch targets processed in a batch, not a whole-run limit.
Tool Page Size	1000	Number of users discovered per page. Retain the default.
Job Identity	Generated stable identity	Leave unset. Do not change the job identity during migration.
Last Migrated User IDs, Previous Complete Run Started, Current Run Started	Empty	Leave unset. These fields are for transferring progress, not normal operation.

Migration limit per scheduled run

Max Migrations limits the migration workload of each execution. It counts dispatch targets, not users or individual FIDO UAF credentials; one user can have several dispatch targets.

• Leave it empty for no configured migration limit.
• Set a positive number to spread a large migration across scheduled runs. Live runs resume from saved progress.

This is not a lifetime migration limit, a deletion setting, or a time limit. There is no universal safe value for every installation. If you need a limit, agree it with Nevis ID support and allow enough scheduled runs to complete the migration.