Skip to main content

Mobile service migration process

Applies to

The information in this topic applies to all releases of the SecureAuth Identity Platform that are upgrading from older releases to 21.04 or later.

Summary

SecureAuth has a dedicated microservice that manages everything related to mobile devices. This encompasses data related to push based MFA and time-based one-time passcode (TOTP) MFA.

The move to this microservices applies to the Identity Platform release 21.04 and later. This topic explains how it handles the enrollment data during Identity Platform upgrades, the different migration modes, data mapping, and TOTP settings.

Information in this topic is complementary to upgrade considerations in SecureAuth mobile services for Identity Platform release 21.04 and later.

Definitions

Hard Token

In this use case on the Identity Platform, a hard token is a physical security key that generates a one-time passcode (OTP).

Common examples of hard tokens are one-time password (OTP) key fobs or USB keys like HID hard tokens and RSA SecurID.

OATH Seed

OATH Seed is a string value used with a combination of current time, passcode length and interval to create a unique TOTP. You can only have one OATH Seed value at a time, and if you enroll more than one device with the same seed, they will all generate the same TOTP at that time.

The Identity Platform supports three common OATH Seed formats -- Base32 (32-char), Base64 (28-char), and HEX. The system unifies the formats to Base32.

In the context of this migration, it is important to understand that this relates to mapped data store profile properties. In the legacy SecureAuth IdP data store settings, there is a profile property mapping for the OATH Seed. In the Identity Platform releases 21.04 and later, there is no OATH Seed profile property in the data store configuration in the New Experience. So, the OATH Seed must be converted to OATH Tokens and mapped as such.

OATH Token

OATH Token has the OATH Seed stored inside the token with more information, like the device name, the last time it was used, a time stamp of when it was enrolled, and more. It also includes passcode length and interval information for TOTPs.

In the New Experience, you set the passcode length and interval in the global MFA one-time passcode (OTP) setting. Upon enrollment, the device uses this global OATH Token seed information for all other authentication log ins.

Push Token

A Push Token contains a unique identifier for the mobile app and device combination and knows where to send a push notification for MFA.

TOTP

Time-based one-time passcode (TOTP) is a time-based OTP. It is a static seed, but with a moving factor that time-based instead of a counter-based.

In the New Experience, you set the length of time in which a passcode is valid in the global MFA one-time passcode (OTP) setting.

Identity Platform upgrades and moving enrollment data

After you upgrade to the Identity Platform 21.04 or later, when an existing user first logs in, it triggers a migration to the mobile service. This happens because the mobile service has zero devices for the user.

If the mobile service already has data for an existing user, the only time it triggers the migration is during Migration Mode 2 (two-direction sync).

What you need to know

  • Apply the latest hotfix. Make sure you always have the latest hotfix for your Identity Platform release. We make continuous improvements to the migration process and it is critical that your Identity Platform deployment instance is up to date.

  • What is meant by "migration"? It defines the process of reading the OATH Token and Push Token data from the user's profile. Then, it combines the token data from the same device into one record, and migrates the mobile device to the mobile service.

    If the device ID and name data do not match in the Push Token and the OATH Token, it migrates the data separately. This is not an issue; the user will have two migrated mobile devices on their profile. One will only support TOTP and the other only supports Push methods.

Identity Platform migration modes

SecureAuth Support will work with you to determine the appropriate migration mode for your Identity Platform upgrade to release 21.04 or later. A migration mode is to support user logins to multiple Identity Platform releases at the same time (pre-21.04 and 21.04 or later). These are temporary migration modes until the following use cases are no longer needed, then the migration mode should be turned off.

Migration Mode 1 (one-direction sync)

The following use cases apply in in Migration Mode 1:

  • Saves to on-prem data store. Upon a successful new enrollment in the mobile service, it saves the associated OATH Token and Push Token to the user profile in the on-prem data store.

  • New enrollments in older releases. Allows the use of new enrollments to the mobile service in older Identity Platform releases before 21.04.

  • Deletes data in on-prem data store. When users delete their mobile device on the Self-Service Account Update or Help Desk pages, it will delete the corresponding data in the on-prem data store.

Migration Mode 2 (two-direction sync)

The following use cases apply in in Migration Mode 2:

  • All of Migration Mode 1. Migration Mode 2 includes all of Migration Mode 1 plus the following list items.

  • Synchronizes on-prem data. Each time a user logs in to an application, it synchronizes the user profile data using the on-prem data store as the source.

    But, it will not synchronize the user profile data if the OATH Token property is not mapped to any profile property. For example. the OATH Token property is not mapped to an LDAP directory attribute like jpegPhoto or registeredAddress.

    • 1. Compare device data. First, it will compare the on-prem mobile device data with the data collected in the mobile service. Any mobile device data that no longer exists in the on-prem data store from an older Identity Platform version is considered stray data. This stray data gets deleted from the mobile service.

      For the migration to work properly, it requires the OATH Token and uses the persistent OATH Token ID for data comparison.

      Having non-persistent data results in redoing the migration at every log in. This also affects API integrations.

      A use case example for non-persistent data is when an OATH Seed gets converted to OATH Token and saves the mobile device data to the mobile service. But, the OATH Token property is not properly mapped or set to Writable in the on-prem data store. So, the migration continues to happen again in the migration process because the data doesn't exist in the on-prem data store for the comparison.

    • 2. Add data to mobile service. Then, per standard migration logic, it adds all the remaining data to the mobile service.

Data mapping

This section provides some guidelines around data mapping in the Identity Platform if you are a new customer or upgrading to Identity Platform 21.04 or later.

  • New customers. While optional, as a new customer on the Identity Platform release 21.04 or later, you should at least set up an on-prem data store mapping to the OATH Token profile property.

    During enrollment, it saves a copy of TOTP device and uses the data as a fallback in case the mobile service is unreachable or is throwing errors.

  • Upgrade customers. As a current customer who upgraded to the Identity Platform release 21.04 or later if you were only using the OATH Seed property, you should add a new profile mapping for OATH Token so that the OATH Seed can be converted and saved.

  • Push Token property. To migrate data from older Identity Platform releases, it uses the Push Token property to maintain synchronization with the migration modes. Once the migration mode is no longer in use, the Push Token property gets deprecated.

  • OATH Seed conversion. If you were on a product version between 9.1 and 20.06, using OATH Seed enrollments AND had OATH Token mapped to use the automatic seed to token conversion to support Login for Endpoints, it will prioritize the OATH Token in the migration. It will ignore a matching OATH Seed property.

    This is a use case where the Push Token is always expected not to combine with the OATH Token during migration.

TOTP length and interval settings

This section explains how we determine which passcode length and change interval data to use for TOTPs.

  • Migrate TOTP settings (version 9.1 or later). OATH Tokens enrolled in product versions 9.1 or later will have the seed length and interval embedded in the token data. The migration process uses this data.

  • Migrate TOTP settings (versions before 9.1). OATH Tokens enrolled in product versions before 9.1 will not have the seed length and interval embedded in the token data. It uses the same migration settings as described in the next list item for OATH Seed enrollments.

  • OATH Seed enrollments. OATH Seed enrollments not yet converted to a token will pull the seed length and interval values from the application realm in the Advanced Settings (formerly Classic Experience) on the MFA tab.

  • New device enrollments. All new mobile device enrollments use the passcode length and interval set in the global MFA one-time passcode (OTP) setting set in the New Experience.

  • Hard Token new enrollments. For Hard Token new enrollments, the only supported option is to use the hard token enrollment button on the Self-Service or Help Desk pages.

    Instead of using the global length and interval TOTP setting configured in the New Experience for device enrollment, you can set a different length and interval for Hard Tokens. To use a different length and interval for Hard Token enrollments, it requires you to be on the Identity Platform release 21.04 with hotfix 10+ or 22.02 with hotfix 4+.

    Use the following new appsettings in the web.config file to override the global settings for Hard Token enrollments:

    hidPassCodeDefaultLength

    hidPassCodeDefaultInterval

In this section: