Common URL Encoding Bugs in OAuth Redirects 日本語ガイド

OAuth redirect issues are often URL encoding issues wearing an authentication badge. The identity provider says the redirect_uri does not match, the callback drops a parameter, or a nested return URL breaks after login.

Most of these bugs come from one of three places: missing encoding, double encoding, or encoding the wrong boundary.

See the API debugging pillar guide for the full local workflow. When query structure is unclear, read parse and rebuild URL query strings before changing encoding.

The redirect URI must match exactly

Identity providers usually compare redirect URIs strictly. These can be different values:

• https://app.example.com/callback
• https://app.example.com/callback/
• https://app.example.com/callback?source=login
• https%3A%2F%2Fapp.example.com%2Fcallback

The registered value, authorization request, and application callback route must agree.

Nested URLs need special care

A common pattern is a login URL with a return target:

/login?return_to=/billing?tab=invoices&page=2

The nested ? and & characters belong to the return URL, not the outer login query. Without encoding, the outer parser will split them incorrectly.

The safer form encodes the nested value:

/login?return_to=%2Fbilling%3Ftab%3Dinvoices%26page%3D2

Use URL Encoder / Decoder to inspect each boundary separately. When the authorize URL is one long string, split keys and values first with URL Parser, then encode or decode one component at a time.

Watch for double encoding

Double encoding happens when a value is encoded once by your code and again by a framework or HTTP client.

Signs include:

• %253A where you expected %3A.
• %252F where you expected %2F.
• A provider showing a redirect URI that still contains percent signs after decoding once.

Decode one layer at a time. If the value only becomes readable after two decodes, find where the second encode happens.

Spaces and plus signs are not always the same

In application/x-www-form-urlencoded, + often represents a space. In general URL percent encoding, spaces are %20 and plus signs are literal plus signs.

OAuth parameters often move through form posts, URLs, logs, and SDK helpers. Be explicit about which encoding mode is being used.

Debugging checklist

When the callback fails:

• Compare the registered redirect URI with the request value.
• Decode the request value exactly once.
• Check whether nested URLs are encoded as a single parameter value.
• Look for %25, a sign that % itself was encoded.
• Confirm state and nonce values survive the round trip.

OAuth can be complex, but many redirect bugs become simple once you separate each URL layer.

Return to the API debugging workflow overview when you need the full tool chain.