Migrating users from email identity to enterprise identity

This guide walks you through migrating existing email/password users to Enterprise SSO connections (such as SAML, Entra ID, or other enterprise connections). This process uses just-in-time (JIT) provisioning to map existing users to their enterprise identities based on matching email addresses. The connection’s Email address trust setting controls how that mapping happens.

What you need

A Kinde account with existing users.
An enterprise app connected in Kinde, see the list of enterprise connections for more information.
Users with email addresses that match exactly their Enterprise Identity (capitalization and structure must match)
A test application in Kinde.

Test the integration with Kinde

Before testing with real users, verify the connection works correctly with a single test user. This helps identify any configuration issues early.

Enable the connection for your test application

In Kinde, go to Settings > Environment > Authentication.
Find your Enterprise Connection and select Configure.
Scroll down to the Applications section.
Toggle the connection ON for your test application. Ideally, this should be an application that is not publicly available.
Select Save.

Choose how existing users are linked

In the same connection configuration, under Provisioning, set Email address trust to Verify, then trust. On their first SSO sign-in, each existing user verifies their email address with a one-time code before Kinde links the enterprise identity to their existing account.

Do not choose Don’t trust for a migration, because Kinde would create a separate user instead of mapping to the existing account. If you use Trust to migrate without verification, first confirm the identity provider meets the conditions in Trusting emails from providers. You can switch from Trust to Verify, then trust during migration; remaining users can still link their accounts after entering a one-time code. Do not switch to Don’t trust until migration is complete (see Complete migration and review email address trust).

Prepare a test user

Identify one existing Kinde user who has an email/password identity.
Verify that this user’s email address in Kinde exactly matches their email address in your identity provider (capitalization and structure must be identical).
Ensure this test user has access to your test application.
Confirm you can access your identity provider’s sign-in logs and Kinde logs for verification purposes.

Test the SSO flow

Open your test application in an incognito/private browser window.
Initiate the SSO login flow:
- If you configured home realm domains, enter the test user’s email address and select Continue. You should be redirected to your identity provider.
- If you didn’t configure home realm domains, select the Sign in with Enterprise or SSO button.
Authenticate with the test user’s identity provider credentials.
After successful authentication, your identity provider should redirect back to Kinde (via the ACS URL).
Kinde should process the SAML response and either:
- Map to the existing Kinde user if the email matches, preserving the user’s profile, roles, and permissions. With Verify, then trust, the user is first asked to enter a one-time code sent to that email address. With Trust, the mapping happens straight away; or
- Create a new Kinde user via JIT provisioning with the SAML attributes if no match exists.
You should be redirected back to your application with a valid authenticated session.

Verify the test was successful

Check the following to confirm everything worked correctly:

In your identity provider:

Go to Sign-in logs and verify the authentication attempt appears.
Confirm the SAML response was sent successfully to Kinde.

In Kinde:

Go to Users and find your test user.
Verify the user’s profile information (name, email) was preserved.
Check that roles and permissions are intact (if applicable).
Review the user’s identity - it should now show the Enterprise Connection identity instead of email/password.

In your application:

Confirm the user can access protected resources.
Verify the session/token is valid.
Test that the user’s profile data is correctly displayed.

Test email/password login (optional):

Attempt to sign in with the test user’s email/password credentials.
If home realm discovery is configured, you should be redirected to your identity provider’s login page instead of the email/password form.

Troubleshooting

If the test doesn’t work:

Disable the Enterprise Connection in Kinde to prevent further issues.
Collect debug information:
- Check your identity provider’s sign-in logs for error messages.
- Review Kinde logs for SAML processing errors.
- Verify the ACS URL in your identity provider matches the one in Kinde.
- Confirm the Entity ID matches in both systems.
Email address format mismatches: Different identity providers may return email addresses in different formats, which can prevent successful user mapping:
- Ensure email addresses match exactly (case-sensitive) between Kinde and your IdP.
- Verify the Email key attribute matches the exact attribute name your IdP uses (e.g., emailaddress, emailAddress, email, or full claim URIs).
- Check your IdP’s SAML response to confirm the exact email format being sent.
Revert the test user back to email/password identity if needed.
Fix any configuration issues and repeat the test.

For more information on troubleshooting SSO issues, see Troubleshoot SSO issues.

Pilot roll-out

Once you’ve successfully tested with a single user, expand testing to a small group of representative users:

Select several test users from different departments or teams.
Test across different browser configurations (Chrome, Firefox, Safari, Edge).
Have each test user complete the SSO login flow.
Monitor both Kinde and your identity provider’s logs for any errors or mapping problems.
Verify each user’s profile, roles, and permissions are preserved correctly.
Document any issues encountered and resolve them before proceeding to full migration.

Enable the connection for live applications

After successful pilot testing, enable the Enterprise Connection for your production applications:

In Kinde, go to Settings > Environment > Authentication.
Find your Enterprise Connection and select Configure.
Scroll down to the Applications section.
Toggle the connection ON for each production application that should use this Enterprise Connection.
Select Save.

Complete migration and review email address trust

If you used Verify, then trust, there is nothing to switch off. Every migrated user proved ownership of their email address with a one-time code, and any future sign-in that matches an existing account will be asked for a code in the same way.

If you used Trust, move to a stricter option once all existing users for that Enterprise Connection have signed in successfully at least once:

In Kinde, go to Settings > Environment > Authentication.
Find your Enterprise Connection and select Configure.
Under Provisioning, find the Email address trust option.
Choose Verify, then trust so future matches require a one-time code, or Don’t trust if you never want accounts combined on email address.
Select Save.

Post-migration checks and housekeeping

After completing the migration:

Audit logs:

Review Kinde logs for any unknown or failed sign-ins.
Check your identity provider’s sign-in logs for authentication issues.
Verify all expected users have successfully migrated.

Security:

Revoke or rotate any signing certificates if needed per your security policy.
Confirm that email/password login is disabled for migrated accounts (if desired).

User verification:

Spot-check user profiles to ensure data integrity.
Verify roles and permissions are correctly maintained.

Expected outcome (success criteria & what to look for)

Primary success criteria:

User can initiate SSO login from the application and is redirected to your identity provider.
Your identity provider accepts credentials and returns a successful SAML response to Kinde (redirect to ACS URL).
Kinde either:
- Maps the incoming SAML emailaddress to the existing Kinde user (after the user enters a one-time code with Verify, then trust, or straight away with Trust), preserving profile and permissions; or
- Creates a new Kinde user via JIT provisioning with the SAML attributes if no match exists.
The user is redirected back to the application with a valid authenticated session and can access resources according to their preserved permissions.
Your identity provider’s sign-in logs show the successful authentication; Kinde logs show either the mapped existing user sign-in or creation of the user from the enterprise connection.
After migration completion and verification, email/password login can be disabled for migrated accounts. If you used Trust, Email address trust can be changed to Verify, then trust or Don’t trust.

Items to be aware of

Identity removal

At the moment when a user has been given an Enterprise Connection identity, their existing identity is removed from their profile at the same time.

Email capitalization issue

Users created in Kinde before March 2025 may experience an email capitalization mismatch that prevents proper syncing between their Kinde profile and Enterprise Connection identity.

This affects users created in Kinde before March 2025, regardless of whether they were originally created with email authentication or an Enterprise Connection. The email address stored in the Enterprise Connection may have incorrect capitalization that doesn’t match their existing Kinde profile, preventing automatic syncing during migration.

To resolve:

Delete the affected user in Kinde.
Have the user log in via their enterprise SSO.
Kinde will automatically create their enterprise identity with the correct email capitalization matching your identity provider.

Customer IdP setup

Your customers’ IdP setups will be different from each other, we would recommend:

Organising a time with them to agree to when the change will happen
Flag with Kinde when this will happen, so we can be on hand to help
Be on a call with them at the point of change to ensure they can authenticate in.

Doing this will mean that when there are nuances between IdP setups, they can be identified and addressed swiftly.

We would recommend, starting with a customer with a smaller user base first.