Redirect URI mismatch
Why a sign-in is refused because of the redirect address, what the person and the developer see, and how to fix the registration or the request.
On this page
Symptom#
For a person: the sign-in does not start. What they see depends on your application, because the redirect address is checked when the application pushes its authorization request, before the browser is sent to identity. If a browser does reach identity with a request that cannot be answered, identity shows a page such as The request was not valid (Start again from the application you came from.) or This application is not recognised, with a Request ID. Nothing is sent back to the application.
For a developer: the pushed authorization request fails with status 400 and:
{ "error": "invalid_request", "error_description": "redirect_uri does not exactly match a registered redirect URI" }Or the token request fails with invalid_grant and redirect_uri does not match the one this code was issued for.
Why identity is strict#
A redirect address is where the authorization code is delivered. If identity accepted any address, an attacker could send a code to a site they control. So the address must be one the client registered, compared exactly. The comparison is checked first, before anything else about the request, because it decides whether identity may send an error to the address at all. When the address cannot be trusted, an error page is shown to the person instead.
Likely causes#
| Cause | Detail |
|---|---|
| A character differs | The comparison is byte for byte: a trailing slash, an upper case letter in the host, a different path, a port, http instead of https, or www. all make a different address. |
| The registered form is not canonical | A redirect address is registered in canonical form: https, a lower case host, no default port, an explicit path, no fragment, no credentials and no wildcard. A value that was registered differently never matches what your code sends. |
| The address is built from the wrong place | Your application builds redirectUri from a request header or a different environment. A development address was registered, and a production address is sent. |
| Different address at the token step | The token request must send the same redirect_uri as the authorization request. |
| The client has no redirect address | The answer is invalid_request with this client has no registered redirect URI. |
| An unknown or suspended client | The answer is invalid_client, and a person sees This application is not recognised. The client_id is not registered, or the client is suspended. |
| A client ID metadata document client | Where the platform has turned on oauth_cimd (default OFF), a client_id that is an https URL names a document, and the registered redirect addresses are the redirect_uris of that document, under the same rules as any registered address. A document that changed, or a cached copy, can differ from what your code sends. |
| A wrong application origin | The SDK builds addresses from the origin you configure. A wrong origin yields a wrong address. |
What to check#
- Print the
redirect_uriyour application sends at the pushed authorization request, with every character visible. - Read the registered redirect addresses for the client in the place you registered them.
- Compare them one character at a time. Look for the trailing slash and the host case first.
- Check the environment: local, preview and production each need their own registered address.
- Check the token request sends the same value.
Fix#
- Change your configuration so
redirectUriequals the registered value exactly. In the SDK this is a single option and it must equal the registered address; see Quickstart. - Register the address you need if it is missing. Ask whoever registers clients for your organization; a person registers one for themselves where that is allowed. The rules for a registered address are in Quickstart.
- Do not use a wildcard. One is never accepted. Register each address.
- Do not build the address from user input or a header. Fix it in configuration.
- A person who sees this page cannot fix it. Go back to the application and try again, and tell its owner, with the Request ID, if it keeps happening.