Organisation administration · Public
Legacy SSO password migration
Import members from a legacy identity provider, verify them through a temporary SAML service provider, and let them set their first Skyfallen ONE password.
Legacy SSO password migration helps enterprise tenants move directory users into ONE without asking everyone to pick a password during bulk import. ONE acts as a temporary SAML service provider (SP) against your legacy identity provider (IdP). Each imported member signs in once through the legacy IdP, proves they control that account, and then sets a ONE password.
This flow is separate from Configure SAML applications, where ONE is the IdP for your applications. Migration SAML is a short-lived bridge for password onboarding only.
Prerequisites
Configure migration on the Legacy SSO migration tab in IAM → Organisation when Workforce Identity is enabled. Only the primary owner or a member with the wildcard (*) permission can change these settings. Members with tenant:manage alone can review the current configuration on that tab but cannot edit it. The same settings are available in the Skyfallen administration dashboard.
| Requirement | Details |
|---|---|
| Tenant type | Enterprise |
| Workforce Identity | Enabled by Skyfallen |
| Vanity subdomain | Required — migration metadata and ACS URLs are generated from {subdomain}.skyfallen.one |
| Permission | Primary owner or wildcard (*) permission to configure migration in IAM. Members with tenant:manage alone can open the tab and review settings but cannot save changes. |
| Legacy IdP | Must support SAML 2.0 HTTP-Redirect sign-in and HTTP-POST responses to ONE |
What ONE exposes to your legacy IdP
Register ONE on your legacy IdP as a SAML service provider using the values shown on the migration tab.
ONE signs AuthnRequests with redirect binding and expects signed SAML assertions in the POST response. The assertion audience should match the SP Entity ID unless your IdP omits audience restrictions.
| Setting | Value |
|---|---|
| SP Entity ID | https://{subdomain}.skyfallen.one/flows/enterprise/migration/metadata |
| Metadata URL | Same as SP Entity ID |
| ACS URL | https://{subdomain}.skyfallen.one/flows/enterprise/migration/acs |
| Name ID format | Email address |
| Binding | HTTP-POST to the ACS URL |
Configure migration in IAM
- Sign in at iam.skyfallen.one.
- Switch to the enterprise tenant you manage.
- Open IAM → Organisation and switch to the Legacy SSO migration tab. You must be the primary owner or hold the wildcard (
*) permission to save changes. - Turn on Legacy SSO password migration.
- Enter your legacy IdP Entity ID and SSO URL.
- Provide the legacy IdP signing certificate:
- Upload a
.pem,.crt, or.cerfile, or - Paste PEM text directly into the certificate field.
- Upload a
- Confirm the certificate inspector shows the expected subject, issuer, and SHA-256 fingerprint.
- Set the Email attribute name your IdP sends in assertions (
email,mail, oruserPrincipalNameare common). - Enable Request ForceAuthn only if you want the legacy IdP to require fresh authentication on every migration attempt.
- Save changes.
ONE always stores the certificate in PEM format. If you upload a DER certificate, IAM converts it client-side before saving.
Import members for migration
Migration applies only to tenant members who exist in ONE with password_set = false. Import or update members first, then let them complete migration at sign-in.
CSV import
- Open Members → Import in IAM.
- Prepare a CSV with at least email, first name, and last name.
- Leave the password column empty for users who must migrate through legacy SSO.
- Enable Clear passwords for SAML migration when the password column is empty when you are updating existing members and want to force migration again.
- Run the import.
When migration is configured on the tenant, new users created without a password in the CSV are stored with password_set = false automatically.
To clear a single row during import, put clear, __clear__, none, or - in the password column.
Single member edit
On a member edit form, enable Unset password for migration when legacy SSO migration is configured. This clears the member's ONE password and marks them eligible for the migration flow again.
SAPP provisioning
When you provision users through the Skyfallen Account Provisioning Protocol without a password, ONE creates them with password_set = false. Those users follow the same migration path once they are members of a tenant with migration enabled.
Who must migrate
A member enters migration when all of the following are true:
Members who already set a ONE password sign in normally. Members without a password who are not eligible see an error at the password step.
| Check | Reason |
|---|---|
| Legacy SSO migration is enabled and fully configured | Entity ID, SSO URL, and a valid signing certificate must be present |
| The user belongs to the tenant | Migration is tenant-scoped |
password_set is false |
The account has not completed ONE password onboarding |
Migration flow step by step
The flow starts on your vanity enterprise sign-in page at https://{subdomain}.skyfallen.one.
Migration sessions expire after 15 minutes. If the legacy IdP round trip takes longer, the member must start again from the sign-in page.
| Step | What happens |
|---|---|
| 1. Email entry | The member enters their work email. |
| 2. Eligibility check | ONE checks whether the account needs migration and whether migration is configured. |
| 3. Legacy SSO prompt | Instead of a password field, ONE offers Sign in with legacy SSO. |
| 4. AuthnRequest | ONE sends a SAML AuthnRequest to your legacy IdP SSO URL with email NameID policy. |
| 5. Legacy IdP sign-in | The member authenticates with the legacy IdP. |
| 6. ACS POST | The IdP posts a signed SAML response to the ONE ACS URL. |
| 7. Verification | ONE validates issuer, signature, audience, timing, and the configured email attribute. |
| 8. Password setup | On success, ONE redirects the member into the password recovery flow to add a phone number when required, accept terms, and set their ONE password. |
| 9. Completion | After the password is saved, password_set becomes true and the member can sign in with email and password or passkeys going forward. |
Retrigger migration for a member
Use any of these approaches when someone must verify through legacy SSO again:
Retriggering only affects members on tenants with migration enabled. It does not delete the ONE account or membership.
| Method | When to use |
|---|---|
| Member edit → Unset password for migration | One person needs to repeat migration |
| CSV import with an empty password column and Clear passwords for SAML migration | Bulk re-migration after a directory change |
CSV password column set to clear |
Clear a single imported row |
Troubleshooting
Enable application debug mode only in non-production environments if Skyfallen support asks for migration failure codes.
| Symptom | What to check |
|---|---|
| Legacy SSO button never appears | Migration disabled, incomplete configuration, or the user already has password_set = true |
| ACS URL mismatch | IdP configured with a different POST destination than the ACS URL on the migration tab |
| Signature or issuer errors | Wrong IdP certificate, rotated IdP cert not updated in IAM, or incorrect Entity ID |
| Email missing in response | Email attribute name does not match the assertion from your IdP |
| Session expired | Member waited more than 15 minutes — restart from the sign-in page |
| Topic | Article |
|---|---|
| Import members in bulk | Run your organisation in IAM |
| Workforce sign-in experience | Publish apps on the workforce portal |
| SAML apps where ONE is the IdP | Configure SAML applications |