Switching identity provider (included in v0.7.0+)
Shoehorn signs people in through one identity provider at a time: Zitadel, Okta, or Microsoft Entra ID. When you switch, the people in your directory don’t move with you on their own. Their accounts, team memberships, roles, and API keys are tied to the identity your old provider gave them. This page is the runbook for carrying them across.
What happens when you switch
Section titled “What happens when you switch”The moment you point Shoehorn at a new provider, every existing person is in one of these states:
| State | What it means | What Shoehorn does |
|---|---|---|
| Linked | The person’s account holds an identity from the new provider | Nothing to do. They sign in as before. |
| Links on next sign-in | The new provider has the same verified email address | While migration mode is on, their first sign-in or the next directory sync links the accounts. |
| Email unverified | The new provider has the same address but hasn’t verified it | Shoehorn refuses to link on its own. You decide. |
| Not in the new provider | No account in the new provider matches | Removed at the next directory sync while migration mode is on, with their team memberships, roles and API keys. Each removal is written to the audit log. |
| New | The new provider has someone Shoehorn hasn’t seen | A fresh account is created when they sign in or sync. |
Until you turn on migration mode, people whose only identity comes from the old provider can’t sign in. They see a plain “this address already belongs to another sign-in identity” message rather than an error page, and nothing about their account changes.
Before you start
Section titled “Before you start”- Make sure the people you want to keep exist in the new provider with the same email address, and that the provider marks those addresses as verified. Zitadel reports this per user. Okta and Entra ID don’t expose it for directory sync, so people from those directories link on their first sign-in instead, when the sign-in token carries the verification claim.
- Migration mode makes a verified email address enough to claim an existing account. Anyone who can create a user in your new provider with a colleague’s address could, in principle, land in that colleague’s account while the window is open. Keep the window short and close it when you’re done.
- You need the tenant admin role, signed in through the product. A personal access token can read the migration state but can’t start it, link, unlink, or remove anyone: those need an admin session or an API key with the
admin:writescope. An API key acts as the person who created it, and that person is who the audit log names. - Okta only: Shoehorn matches directory entries to sign-in identities by the issuer in your Okta configuration. If you sign in through a custom authorization server, set the issuer to that server’s URL, not the org URL, or the directory and the sign-ins won’t line up.
Run the cutover
Section titled “Run the cutover”- Open Admin → Directory → Users. If Shoehorn has noticed the switch, a banner at the top says which provider you came from and how many people are affected. In the list, people who still hold the old provider’s identity show Cannot sign in, and people the new provider doesn’t have show Not in followed by its name.
- Click Start migration. The banner turns orange to show the window is open and says when it closes: migration mode turns itself off 24 hours after you start it, so a forgotten window can’t keep removing people. Start it again if you need longer. Every link made while it’s open is written to the audit log with who opened the window.
- Click Review to open the identity migration screen. The four cards show how many people are linked, not in the new provider, new, or waiting on you.
- Work through the table:
- Email unverified: click Link anyway once you’ve confirmed the person is who the address says. This is your call, and it’s audited under your name.
- Not in the new provider: they’re removed at the next directory sync. The sync runs when Shoehorn starts and every five minutes after that. If someone should keep access, add them to the new provider before that sync runs, and it links them instead.
- The sync has a safety cap. It removes at most 100 people per run, and it refuses to run at all when it would remove more than 10 people or half your users, whichever is larger. A refused run removes nobody, the banner keeps counting, and the log says why. That stops a directory pointed at the wrong organisation or group from emptying your tenant in one pass.
- Linked: nothing to do. Unlink is there if a link was wrong.
- Ask people to sign in. Anyone whose address is verified is linked on the way in.
- When the review shows nothing waiting on you, click Stop migration. The window closes and email addresses stop counting as proof of identity.
The cutover is done when everyone you expect to keep shows as Active on the Users page and the banner is gone.
Removing someone by hand
Section titled “Removing someone by hand”While migration mode is on, the directory sync removes people the new provider doesn’t have, deactivated or not. A deactivated person the new provider still lists stays, and you can remove them one at a time; the trash icon is only offered for deactivated accounts.
- On the Users page or the review screen, click the trash icon on a deactivated row.
- The dialog lists what goes with the account: team memberships, API keys, and the services that name this person as an owner.
- Click Remove user.
Removing deletes the account, its team memberships, roles, and API keys. Services that named the person as an owner keep that name in their manifest until someone edits it, so the dialog lists them for you. If the person should keep access instead, add them to the new provider and link the accounts; that’s almost always the better answer.
What’s recorded
Section titled “What’s recorded”Every step lands in the audit log, so the question “who allowed this” always has an answer:
- Opening and closing migration mode, with who did it.
- Every link, automatic or by hand, with both identities and who authorised it.
- Every unlink and every removal.
- Each person the directory sync removed, with what went with them, and each sync that removed anyone, with how many and which accounts.
Watching the sync
Section titled “Watching the sync”The API exposes four Prometheus counters on /metrics (port 8080) for the directory sync. The first three are labelled by tenant_id and provider:
| Metric | Counts |
|---|---|
shoehorn_identity_migration_reconcile_runs_total |
Sync passes that ran: migration mode on and a complete directory listing |
shoehorn_identity_migration_removed_total |
People a sync removed |
shoehorn_identity_migration_reconcile_failures_total |
Syncs that failed, plus each person a sync couldn’t remove |
shoehorn_identity_migration_reconcile_skipped_total |
Passes a safety check stopped, by reason: empty_snapshot, incomplete_snapshot, window_closed, no_provider, no_opener, too_many_absent, concurrent_run, multiple_providers, no_tenant |
A sync that keeps failing shows up in the failures counter even when nothing is removed. A refused run over the safety cap shows up as too_many_absent.
If you script against the users API
Section titled “If you script against the users API”GET /api/v1/users/{userId} used to answer 404 for someone the new provider doesn’t have. It now returns their Shoehorn record with "providerAbsent": true. A script that read that 404 as “this person is gone” should check the flag instead: the person stays in Shoehorn until a directory sync in migration mode removes them, or you remove them by hand.
If something looks wrong
Section titled “If something looks wrong”- The banner doesn’t appear. Shoehorn shows it when it sees people holding identities from a provider other than the one you configured, or active people the new provider’s directory doesn’t list. Trigger a directory sync or have someone sign in, then reload. The review screen itself is always in the admin sidebar under People & Access, and it offers Start migration even when nothing has been detected.
- The banner talks about people who can’t sign in instead of naming your old provider. People synced by an older version of Shoehorn carry no record of which provider created them, so Shoehorn doesn’t guess. The cutover works the same way; only the name is missing.
- Nobody gets linked. Check that migration mode is on, and that the new provider reports the addresses as verified. Unverified addresses never link on their own.
- Someone was removed who shouldn’t have been. They weren’t in the new provider’s directory by subject, stored identifier, or email address when the sync ran. Add them to the new provider; their next sign-in creates a fresh account. Team memberships have to be added again, which is why the sync only removes anyone while migration mode is on and only from a complete directory listing.
- The counts say the directory couldn’t be read. The new provider’s directory API didn’t answer. Nobody is removed on a failed or partial read, by design. Check the provider’s credentials and try again.
- Nobody is being removed, and the log says the run was refused. The listing would have removed more than the safety cap. Check that the new provider is pointed at the right organisation and group filter. If the listing is right and that many people really have left, remove them from the review screen, or in batches as they’re added to the new provider.
- Migration mode turned itself off. It closes 24 hours after it was opened. Start it again if you’re not done; nothing else changes.