twobotechnologies

Authorization · 5 min read

OAuth redirect_uri Mismatch: Causes and Fixes

Short answer

A redirect_uri mismatch error means the redirect URI in the authorization request is not character-for-character identical to one registered for the client; compare scheme, host, port, path, trailing slash and encoding, fix the registration or the request so they match exactly, and send the same value again in the token request.

Key takeaways

  • RFC 9700 requires authorization servers to compare redirect URIs by exact string matching, with one exception for loopback ports in native apps.
  • The usual culprits are http versus https, a trailing slash, www, a missing port, a different path or double encoding.
  • Apps behind a proxy often build the redirect URI from the internal host or scheme; configure them to use the public URL.
  • The token request must carry the same redirect_uri as the authorization request when one was sent.
  • Never fix a mismatch by registering a wildcard; that reopens the open-redirect and code-theft attacks exact matching prevents.

"redirect_uri_mismatch," "invalid redirect URI," "The redirect URI in the request does not match the ones authorized for the OAuth client." Every identity provider words it differently, but it's the same error and one of the most common in OAuth integration work. It's also an error worth respecting, because the check behind it stops real attacks. This article explains what the server compares, the usual causes, and how to fix them without weakening anything.

What does a redirect_uri mismatch mean?

It means the redirect_uri in your authorization request is not identical to any redirect URI registered for that client, so the authorization server refuses to send a code there.

The authorization server will only send the user, and the authorization code, back to addresses the client registered in advance. If the request names any other address, the server stops and shows an error page instead of redirecting. It does not redirect to the unregistered URI with an error, because that would defeat the purpose.

Why do servers require an exact match?

Exact matching prevents attackers from steering authorization codes or tokens to pages they control, which pattern matching has repeatedly allowed.

Older deployments allowed wildcards or prefix matching, such as anything under https://app.example.com/. Attackers found ways to abuse that: an open redirect somewhere on the allowed host, a path traversal, or a subdomain they could take over. The code would land on a page that leaked it.

RFC 9700, the OAuth 2.0 security best current practice published in January 2025, requires authorization servers to compare redirect URIs using exact string matching. The one exception is the port number on localhost redirect URIs for native apps, covered below.

What are the most common causes?

Small differences in scheme, host, port, path, trailing slash or encoding cause nearly all mismatches.

Registered Sent Problem
https://app.example.com/callback http://app.example.com/callback Scheme
https://app.example.com/callback https://app.example.com/callback/ Trailing slash
https://app.example.com/callback https://www.app.example.com/callback Host
https://app.example.com/callback https://app.example.com:443/callback Port written out
https://app.example.com/callback https://app.example.com/Callback Path case
https://app.example.com/cb?x=1 https://app.example.com/cb?x=2 Query string

Encoding is the other frequent cause. The redirect_uri parameter must be URL-encoded once inside the authorization URL. Encoded twice, the server decodes it to a string full of %3A and %2F, which matches nothing.

To check what you actually send, build the request in the authorization URL builder and compare its decoded redirect_uri with the registered value character by character.

Why does it work locally but fail in production?

Behind a load balancer or reverse proxy, the application often builds its redirect URI from the internal scheme, host or port instead of the public one.

A typical case: TLS ends at the load balancer, the app receives plain HTTP on port 8080, and the framework generates http://app.internal:8080/callback. The fix is to configure the app or framework to trust the proxy's forwarded headers or to set the public base URL explicitly. Hard-coding the full redirect URI in configuration per environment is the simplest and most predictable option.

Register a separate redirect URI for each environment (development, staging, production) rather than reusing one.

How do native apps handle localhost ports?

Native apps can register a loopback redirect URI and use any port at runtime, and the server must accept the varying port.

A desktop app can't know in advance which local port will be free. RFC 8252 section 7.3 lets it register something like http://127.0.0.1/callback and listen on a random port. The authorization server must allow any port in the request for loopback URIs. RFC 8252 recommends the IP literal 127.0.0.1 (or [::1]) over the name localhost, since localhost can resolve unexpectedly.

If your provider rejects loopback ports, check whether it has a separate "native" or "public client" registration type.

What about the token request?

If you sent redirect_uri in the authorization request, send the identical value in the token request too.

RFC 6749 requires the authorization server to check that the redirect_uri in the token request matches the one used to obtain the code. A mismatch here produces an invalid_grant error at the token endpoint rather than an error page, which can be confusing. Build both values from the same configuration setting so they cannot drift apart.

What should you never do to fix it?

Never register a wildcard or a broad prefix, never accept the redirect URI from user input, and never turn off the check in a custom server.

Every one of those "fixes" brings back the code-theft attacks exact matching was designed to stop. If you need many redirect URIs, register each one. If you need dynamic return pages, use a single fixed redirect URI and carry the final destination in state, protected against tampering. Our article on the state parameter explains how.

Questions

Why is my redirect_uri rejected when it looks identical?

Look for invisible differences: a trailing slash, uppercase letters in the path, a default port written out, a URL-encoded character, or a space copied into the registration. Compare the raw decoded strings side by side.

Can I register a wildcard redirect URI?

You shouldn't, and many authorization servers no longer allow it. RFC 9700 calls for exact matching because pattern matching has repeatedly been exploited to send authorization codes to attacker-controlled pages.

How do native apps use localhost redirect URIs?

RFC 8252 lets native apps use a loopback redirect such as http://127.0.0.1 with a port chosen at runtime, and the authorization server must allow any port for that registration. RFC 9700 keeps this as the one exception to exact matching.

Do I need redirect_uri in the token request?

If the authorization request included redirect_uri, RFC 6749 requires the token request to include the identical value. OAuth 2.1 drafts tighten this further.

Sources

Tagged: OAuth, OAuth 2.0, Authorization code flow, Security, Authorization

The Twobo Technologies editors write practical explainers on identity and API security and maintain the free tools on this site. Spotted an error or an outdated detail? Email contact@twobotechnologies.com.

Related articles