Moving off legacy sign-in
From the legacy API, portal and system accounts to OAuth 2.0 and OpenID Connect
What "legacy" means
Orion still serves the platform OAuth and OpenID Connect replaced: the /legacy API (password sign-in,
session keys, registration, sign-in actions), the legacy sign-in portal (/Federation/Login?appId=…), system
accounts that sign their calls with an application's public and secret keys, and agents that fetch a key from
VerifyIdentity on every call. Everything it does has an OAuth or OpenID Connect equivalent. Nobody's
account, password or second factors change when an application moves: only how the application asks Orion.
| Surface | What it is | Replaced by |
|---|---|---|
| The legacy login API | legacy/api/Authentication/User/Login: an email and password, or a directory token, exchanged for a session key. | The authorization code flow with PKCE (/oauth/{org}/authorize), through the SDK's OAuthFederated filter. |
| The legacy sign-in portal | /Federation/Login?appId=…: Orion's legacy sign-in pages, which hand the session key back to the application as orion_key. | The same SDK filter in its OAuth mode: Orion's OAuth sign-in and consent pages. |
| Session-key checks | Keys/User/{key}, User/Profile/{app}/{key}, Keys/User/{key}/Permission/{app} and User/{id}/OrionSessions: a relying party asking Orion about a legacy session key, often on every request. | Validating the ID or access token locally against /oauth/{org}/.well-known/jwks.json; userinfo or introspection for more. |
| Key conversion | Keys/User/{key}/Convert/To/UserPerm and …/UserTemp: turning a sign-in's key into one that never expires, or back. | The offline_access scope and refresh tokens, which follow the session and end with it. |
| Legacy sign-in actions | Authentication/Action/{id}/{type}: an application completing a sign-in's second factor, email or phone confirmation or password reset itself. | Orion's own pages: the OAuth sign-in asks for every second factor, confirmation and change itself. |
| Legacy registration | Authentication/User/Register, …/Register/Complete/{key} and …/Roaming/Register. | Orion's registration page (/oauth/{org}/register) and invitations. |
| VerifyIdentity agents | Authentication/Account/VerifyIdentity: a five-minute application key on every call, for agents such as Guardian and Lightning. | The client_credentials grant with a device certificate assertion, validated locally (docs/device-identity.md). |
| The legacy administration API | legacy/api/oauth/* and legacy/api/Organisation/*: managing clients, scopes and consents with a system account's HMAC keys. | The console's pages; there is no token-authenticated replacement yet. |
1. See what still uses it
Orion records each use of a legacy surface: who called (an application, a system account, a person, or an unsigned call), once per caller and surface each day. Two pages show it, for the last 30 and 90 days:
- Platform administrators: Retiring legacy sign-in (Platform, then Legacy retirement): the server's own sign-in, every surface and its callers, every organisation, every system account.
- An organisation's administrators: the organisation's page (Security, then Legacy retirement): its applications, system accounts and the people who signed in through legacy.
Orion's legacy sign-in page still calls the legacy API itself; those uses are shown apart, are not counted as outside use, and stop when the legacy sign-in portal is switched off. Password reset, email confirmation and sign-out call nothing.
2. Move in this order
- Applications' sign-in (portal, login, session keys, key conversion, actions): one change per application, below.
- Agents and scripts (VerifyIdentity, the
administration API): move each to
client_credentials, then delete its system account. - Registration (legacy registration): send people to Orion's own pages.
- This server's own sign-in, if the management portal still uses the legacy portal (below).
- Unprefixed claim names, once applications read
@handle/name(each organisation's Scopes page). - Watch the pages: a surface shows Unused for 30 days when nothing outside Orion has called it for 30 days. Then switch it to Warn, and Off (below).
3. Moving a web application
An application on the .NET SDK changes one setting, its filter type, and gains its OAuth client details:
- On the application's page (Applications, then the application, then OAuth), turn OAuth on, allow the
authorization_codegrant and add its redirect URIs. The SDK sends the address of the page being opened as its redirect URI, so register the addresses of the pages that carry the filter. - Change the application's configuration:
builder.Services.AddSingleton<IFederationConfig>(new FederationConfig { FederationServer = "https://login.craven.dev/federation", ApplicationId = "my-application", - FilterType = FederationFilterType.UserFederated, + FilterType = FederationFilterType.OAuthFederated, + OAuthOrganisationId = "your-organisation-public-id", + OAuthClientId = "my-application", + OAuthScopes = "openid profile email", + OAuthAudience = "my-application", });
- Sign in through the application once. Its people see Orion's sign-in page and, where its scopes need it, a consent page; their accounts are the same.
- Delete the application's system accounts (its page, System accounts) once its legacy page shows no calls from them.
Controllers keep [OrionFederationFilter] and OrionPrincipal as before.
4. Surface by surface
The legacy login API
What it is: legacy/api/Authentication/User/Login: an email and password, or a directory token, exchanged for a session key.
Who calls it: Relying parties on the legacy SDK, and Orion's own legacy portal page.
Replaced by: The authorization code flow with PKCE (/oauth/{org}/authorize), through the SDK's OAuthFederated filter.
- Register the application for OAuth on its page (Applications, then OAuth), with its redirect URI.
- In the application, change the SDK filter's type from UserFederated to OAuthFederated and give it the client id.
- Sign in through the application once to check the redirect, then remove its system account's keys.
The legacy sign-in portal
What it is: /Federation/Login?appId=…: Orion's legacy sign-in pages, which hand the session key back to the application as orion_key.
Who calls it: Browsers sent by applications whose SDK filter is UserFederated.
Replaced by: The same SDK filter in its OAuth mode: Orion's OAuth sign-in and consent pages.
- Move the application as for the login API: OAuth on its page, then OAuthFederated in the application.
- Its people keep their accounts and passwords; their first OAuth sign-in asks consent where the application needs it.
- Legacy permissions the application relied on become scopes and consents (Applications, then Scopes).
Session-key checks
What it is: Keys/User/{key}, User/Profile/{app}/{key}, Keys/User/{key}/Permission/{app} and User/{id}/OrionSessions: a relying party asking Orion about a legacy session key, often on every request.
Who calls it: UserFederated applications' filters.
Replaced by: Validating the ID or access token locally against /oauth/{org}/.well-known/jwks.json; userinfo or introspection for more.
- Moving the application to OAuthFederated (above) ends these calls: the SDK validates tokens itself.
- A service that only checks a key it was handed checks a bearer token instead (the SDK's OrionMachineTokenValidator).
Key conversion
What it is: Keys/User/{key}/Convert/To/UserPerm and …/UserTemp: turning a sign-in's key into one that never expires, or back.
Who calls it: Relying parties keeping a person signed in.
Replaced by: The offline_access scope and refresh tokens, which follow the session and end with it.
- Ask for offline_access when the application signs in through OAuth, and keep the refresh token instead of a permanent key.
- Refresh when the access token expires; a refresh is refused once the person's session has ended.
Legacy sign-in actions
What it is: Authentication/Action/{id}/{type}: an application completing a sign-in's second factor, email or phone confirmation or password reset itself.
Who calls it: Relying parties that drive the legacy sign-in in their own pages.
Replaced by: Orion's own pages: the OAuth sign-in asks for every second factor, confirmation and change itself.
- Moving the application to OAuthFederated removes these: Orion's sign-in page does each step.
- Password resets go through Orion's own reset page (the sign-in page's "Forgotten your password?").
Legacy registration
What it is: Authentication/User/Register, …/Register/Complete/{key} and …/Roaming/Register.
Who calls it: Relying parties registering accounts through the API.
Replaced by: Orion's registration page (/oauth/{org}/register) and invitations.
- Send people to the organisation's registration page, or invite them from the console (Invites).
- Roaming (guest) accounts have no OAuth equivalent: invite the person to an organisation instead.
VerifyIdentity agents
What it is: Authentication/Account/VerifyIdentity: a five-minute application key on every call, for agents such as Guardian and Lightning.
Who calls it: Agents and services with a system account, continuously.
Replaced by: The client_credentials grant with a device certificate assertion, validated locally (docs/device-identity.md).
- Enrol the agent's machine as a device (Devices), and give its application client_credentials.
- The agent asks the token endpoint for a token with its device assertion, and services validate it locally.
- Remove the agent's system account keys once it has moved.
The legacy administration API
What it is: legacy/api/oauth/* and legacy/api/Organisation/*: managing clients, scopes and consents with a system account's HMAC keys.
Who calls it: Scripts and tools with an organisation's system account.
Replaced by: The console's pages; there is no token-authenticated replacement yet.
- Make the change on the organisation's pages instead (Applications, Scopes).
- If a script must keep doing it, note which calls it makes before this surface is switched off.
5. Agents and services
An agent that calls VerifyIdentity with a system account's keys gets a token instead: enrol its machine as a
device (Devices), give its application the client_credentials grant, and have it ask the token endpoint with
its device assertion. A service that checked the legacy key it was handed validates the bearer token locally against
https://login.craven.dev/oauth/{organisation}/.well-known/jwks.json (the SDK's OrionMachineTokenValidator).
The device guide (Device Identity) has the details.
POST https://login.craven.dev/oauth/{organisation}/token
grant_type=client_credentials&client_id=my-agent&client_assertion_type=…&client_assertion=<device assertion>
6. This server's own sign-in
The management portal itself may still sign in through the legacy portal (ORION_AUTH_MODE=legacy, or auto
mode on a server whose portal application is not OAuth-enabled). The platform administrator's legacy page and Platform
Admin say which. To move it, open the portal application (the platform organisation's orion), turn OAuth on
with the authorization_code grant, or set ORION_AUTH_MODE=oauth, and sign in again.
ORION_AUTH_MODE=legacy brings the old page back.7. Switching a surface off
Each surface on the platform administrator's legacy page has a switch:
| Switch | What callers see |
|---|---|
| On | Nothing changes. |
| Warn | It works, and every answer carries Deprecation: @<date> and a Link to this guide (rel="deprecation", RFC 9745), so callers' own logs say it is going. |
| Off | The API answers 410 Gone with { "error": "legacy_disabled", "surface", "replacedBy", "guide" }. The legacy sign-in portal shows people a page saying the application has moved. |
- Set a surface to Warn once its callers have been told, and watch the page.
- When it shows Unused for 30 days, set it to Off. Refused calls are still recorded, so the page shows anything still trying.
- A change applies at once on the instance that saved it and within half a minute on the others. It needs a recent sign-in and is recorded in the activity log.
The environment can fix any switch: ORION_LEGACY_<SURFACE>=on|warn|off (the surface's id in
capitals, a hyphen as an underscore, such as ORION_LEGACY_VERIFY_IDENTITY) wins over the page, and
ORION_LEGACY_LOCKED=true makes every switch read-only.
8. All of it, off
On a server whose own sign-in uses OAuth, every surface can be switched off, in this order: the legacy sign-in portal, then the login API and session-key checks, then the rest in any order. Nothing is switched off by an upgrade; each switch can be turned back on at any time, and the legacy page keeps showing anything that still tries.