Seamless API Domain Transition for Mobile Clients

In the past, changes to the domain used during initial enrollment could force all users to re-enroll. This would create a major operational burden and a frustrating experience for customers. We've built a solution to prevent that from happening.

Credential bindings and device enrollments are often tied to the domain used during registration. A simple domain change could invalidate your existing FIDO/WebAuthn credentials, tokens, or signatures. Our backend services also validate origin headers or DNS-linked identifiers, adding to the complexity.

Our mobile client will now dynamically transition to the new domain without impacting your experience or requiring re-enrollment. Here's how this controlled migration process works:

• Smart Detection: When your mobile client makes a GetUpdates request using the existing (old) domain (e.g., when you swipe down on the main screen of the app or re-enter it), it will automatically detect if a new domain is being advertised.

• Secure Updates: If a new domain is found, your client will continue to use the old domain to securely fetch updated license metadata and new server certificate pins.

• Trial Run: Using the new domain and the updated certificate pins, your client will perform a quick, non-persistent test call. This ensures everything is connected correctly and securely.

• Seamless Switch: If the test is successful, the new domain and certificate pins will be securely saved on your device, and your device will be marked as successfully migrated.

• Server Notification: Your mobile client will then report the successful domain transition to our server, including a new fqdn field for better operational visibility and analytics.

Ensure that both the old and new domains are reachable and correctly pinned to facilitate a seamless switchover.

Steps to Change FQDN:

1. Access the Administration Console

   • Log in with appropriate administrative privileges.

2. Navigate to Configuration Settings

   • Go to: Settings → General → DMZ

3. Modify the Websec URL

   • Locate the websecUrl field.

   • Replace the current value with the new FQDN you wish to test

4. Save and Apply Changes

   • Ensure the changes are committed and propagated to the configuration service used by mobile clients.

5. Go to DMZ.json and modify also here the new dmzUrl.

6. Add the PIN certificate in admin, for the new FQDN.

7. Observe Device Behavior

   • On the next GetUpdates call, the mobile client should:

     • Detect the FQDN change

     • Fetch updated license and certificate pins

     • Attempt connectivity validation against the new domain

     • Persist changes only after successful validation

Keeping an Eye on Progress:

We're adding new observability features so we can track the migration progress. This will allow us to monitor devices using the new domain and ensure a smooth transition for everyone.
There is a newly introduced field fqdn that will be made available via Elastic.

• Phone Dashboard can use this attribute to:

  • Filter devices using the new domain

  • Track migration progress