Skip to main content
Version: 4.0.1

Native App Cutover (Migration)

Use this guide when you replace a legacy identity provider and need existing native apps already in the stores to keep working: same client_id, discovery / well-known cutover, optional refresh-token import, and parallel sync while old app versions remain installed.

Looking for integration best practices?

For how to build native apps with cidaas (browser login, Custom Tabs / SFSafariViewController, PKCE, refresh-token handling), see Mobile and Native Clients.

Why native cutover is harder than web​

App updates are hard to schedule:

  • Store approval is required before a new build is available
  • Users must install the update; many stay on older versions for weeks

Plan cutover so that hardcoded client configuration and discovery can move to cidaas without forcing every user to update on day one.

Key considerations​

  1. Do you already use authentication in the app?
  2. Is it native (in-app UI) or browser-based?
  3. Does it follow OAuth 2.0 / OIDC?
  4. Does the app load the OpenID discovery (.well-known/openid-configuration) for token, authorization, and JWKS endpoints?

The more of these you can answer with yes, the easier it is to switch client_ids or domains and point traffic to cidaas. If not, expect a longer parallel phase or an app update.

Cutover steps for an OAuth 2.0–based app​

Scenario: Android and iOS apps are already live. They use one hardcoded client_id.

Step 1 — Recreate the same client in cidaas​

  1. Create an application in cidaas with the exact same client_id
  2. Allow the same redirect URIs for that client

Step 2 — Rely on discovery​

Authorization and token endpoints usually change when you switch to cidaas (see your tenant’s discovery document, e.g. https://demo.cidaas.de/.well-known/openid-configuration).

Ideally the app already fetches discovery remotely and caches it for a reasonable period. If endpoints are hardcoded, change the implementation to read authorization_endpoint and token_endpoint from discovery before cutover.

Step 3 — Go-live​

At cutover, either:

  • Change the response of your existing discovery URL to return cidaas well-known data, or
  • Redirect that discovery URL to the cidaas well-known endpoint

Then validate login and token refresh on both platforms.

Refresh token migration​

To keep users signed in after cutover (especially apps that store long-lived tokens), refresh tokens can be migrated into cidaas. Short-lived access tokens are normally not migrated — the app obtains new access tokens from cidaas using the migrated refresh token.

When it helps

  • Apps already use OAuth 2.0 refresh tokens (offline_access / refresh flow)
  • You want to avoid a mass re-login after switching discovery / token endpoints
  • The same client_id continues to be used in the app

Planning notes

  • Migrate users (and passwords if needed) first so the account exists in cidaas
  • Keep the app client_id identical in cidaas
  • Coordinate refresh-token import with cidaas (enablement and payload format depend on the source system; available on request)
  • After cutover, verify that a migrated refresh token can obtain a new access token from the cidaas token endpoint
  • Align refresh-token lifetime and rotation policy in cidaas with your security requirements
tip

Refresh-token migration complements discovery cutover: devices keep a valid refresh token while authorization and token endpoints move to cidaas.

Parallel operation when a hard switch is not possible​

If you cannot cut over discovery or client configuration in one step:

  1. Point web applications to cidaas first
  2. Ship an app update that uses browser-based authentication with PKCE against cidaas (see Mobile and Native Clients)
  3. Keep user data in sync from the legacy system to cidaas during the migration window (see Long-term sync or Bidirectional sync) so users can register or log in in the app and still access other services

Next steps​

  1. Align instance and app config: Instance Setup
  2. Plan user and password import: Migration Overview
  3. Decide sync vs one-time based on volume and go-live style: Migration procedures
  4. Implement secure native login patterns: Mobile and Native Clients
  5. Avoid embedded webviews for login: Why not use webviews in native apps