Origins and redirect URLs
How Legation checks request origins, authentication callback URLs and OAuth redirect URIs.
Legation applies two different rules to URLs. Authentication callback URLs, used by your own app's sign-in flows, are checked against the trusted origins of your environment. OAuth redirect URIs, used when Legation acts as an OAuth provider for a registered client, must match a registered URI exactly.
Request origins
State-changing requests, such as sign-in and sign-up, must come from a trusted origin of your environment. GET, HEAD and OPTIONS requests are not origin-checked.
Authentication callback URLs
These are the URLs your app passes to Legation's sign-in and account flows: callbackURL, redirectTo, errorCallbackURL and newUserCallbackURL. Each one is accepted when it matches a trusted origin of your environment.
| URL form | When it is accepted |
|---|---|
https:// or http:// URL | Its origin (scheme, host and port) equals a trusted origin. The path is not compared, so any path on a trusted origin is accepted. |
Wildcard pattern, for example https://*.example.com | The URL's origin matches the pattern. A pattern without a scheme matches the host only. |
App scheme, for example myapp:// | The scheme matches. If the trusted entry includes a host or path, the URL must have the same host and a path equal to or beneath it. |
Relative path, for example /dashboard | Accepted when it is a safe path on your own origin. Paths starting with //, containing backslashes or control characters, or encoding a path separator are rejected. |
A relative path is never accepted as a request origin, only as a callback URL.
OAuth redirect URIs
When Legation acts as an OAuth provider, each OAuth client registers its redirect URIs. The redirect_uri in an authorization request must match one of them exactly, character for character, including scheme, host, port, path and query.
https://app.example.com/auth/callbackdoes not matchhttps://app.example.com/auth/callback/orhttp://app.example.com/auth/callback.- A redirect URI with a fragment (
#) or with user information (user@) is rejected. - For loopback addresses used by native apps, such as
http://127.0.0.1/callback, the port is ignored when comparing, so a native app can listen on any free port.
If the client or redirect URI cannot be verified, the error is shown on Legation's error page rather than sent to the unverified address.
Register what you use
- Register every origin your app signs in from, in each environment.
- Register every OAuth client's redirect URIs exactly as the client sends them.
- For mobile apps, register your app scheme, for example
myapp://.
Available at release
Registering origins, application clients and redirect URIs through id0n's management interface is available at release.
Errors
| Error | Meaning | Fix |
|---|---|---|
INVALID_ORIGIN | The request came from an origin that is not trusted. | Register the origin for the environment. |
MISSING_OR_NULL_ORIGIN | The request had no origin. | Make the request from a browser page or app on a registered origin. |
INVALID_CALLBACK_URL | callbackURL does not match a trusted origin. | Use a URL on a registered origin, or a safe relative path. |
INVALID_REDIRECT_URL | redirectTo does not match a trusted origin. | Use a URL on a registered origin, or a safe relative path. |
INVALID_ERROR_CALLBACK_URL, INVALID_NEW_USER_CALLBACK_URL | Same check for those URLs. | Use a URL on a registered origin, or a safe relative path. |
CROSS_SITE_NAVIGATION_LOGIN_BLOCKED | A sign-in was attempted through a cross-site navigation. | Start sign-in from your own site. |