Redirect URIs are a security boundary in OAuth environment design

At a glance

What this is: This is a developer guide to redirect URI registration across environments, showing that exact matching, environment separation, and impersonation are the safest patterns for OAuth-based authentication.

Why it matters: IAM, NHI, and application security teams need to treat redirect URI design as part of identity governance because weak environment boundaries can expose authorization codes, tokens, and production access paths.

👉 Read WorkOS's guide to redirect URI patterns, errors, and impersonation

Context

Redirect URIs are the callback endpoints used in OAuth 2.0 authorization code flows, and they are only safe when the authorization server can verify that the destination was pre-registered exactly. That makes redirect URI design a core identity control, not just an app configuration detail, because the wrong URI can turn sign-in into a code interception path.

For identity teams, the governance problem is environment drift: local development, staging review apps, and production all need different redirect strategies, different credentials, and different risk tolerance. WorkOS’ guidance reflects a broader IAM principle that the authentication boundary must match the deployment boundary, or teams end up debugging access failures while also widening attack surface.

Key questions

Q: How should teams handle redirect URIs across local, staging, and production environments?

A: Treat each environment as a separate trust boundary. Use localhost and sandbox credentials for development, custom wildcard subdomains for review apps you control, and a single exact HTTPS redirect URI in production wherever possible. The key is consistency between the registered callback and the application config, because mismatch creates both login failures and avoidable security exposure.

Q: Why do redirect URI mistakes create both reliability and security problems?

A: Because the redirect URI is where the authorization code lands, a mismatch can block authentication entirely, but an overly broad match can send codes to an unintended destination. In OAuth code flows, the security value comes from exact pre-registration, so loosened patterns trade convenience for expanded interception risk.

Q: What do security teams get wrong about wildcard redirect URIs?

A: They often treat wildcards as a generic shortcut for dynamic environments, but wildcard scope is only safe when the domain is fully owned and the tenancy model is understood. Shared or public suffix domains are dangerous because they widen the set of valid callback targets beyond what a single application should trust.

Q: When should teams use impersonation instead of changing redirect URI settings?

A: Use impersonation when the goal is to see what a specific user sees in production. It preserves the real authentication path, records the action in the audit log, and avoids leaking production tokens to a local machine. Redirect URI changes should support deployment needs, not debugging convenience.

Technical breakdown

Exact redirect URI matching in the OAuth code flow

In the OAuth 2.0 authorization code flow, the redirect URI tells the authorization server where to send the browser after authentication. The server returns a short-lived authorization code, which the backend exchanges for tokens. Because that code can be exchanged for account access, the redirect URI must match a pre-registered value exactly. Even small differences such as protocol, trailing slash, path, or port will break the flow. That strictness is a control, not a nuisance, because it prevents an attacker from redirecting the code to an unauthorized endpoint.

Practical implication: register exact callback URLs per environment and compare the code and dashboard values character by character before troubleshooting.

Wildcard redirect URI patterns in staging and review apps

Wildcard redirect URIs exist to support ephemeral review environments, but their scope is tightly constrained. The wildcard must sit in the leftmost subdomain position, only one wildcard is allowed, and it cannot span multiple subdomain levels. WorkOS also blocks wildcards on public suffix domains such as shared hosting and tunnel domains because those are multi-tenant by design. The security issue is trust expansion: a broad wildcard accepts more destinations than a narrowly defined callback, which is useful for CI/CD convenience but dangerous when the domain is not exclusively controlled by the application owner.

Practical implication: use custom owned subdomains for review apps and keep wildcard registrations narrow, explicit, and isolated from shared public suffix domains.

Impersonation as a safer alternative to production redirect workarounds

Impersonation changes the debugging model. Instead of routing production authentication through a local machine, an administrator can assume a user context in the production environment with audit logging and an impersonator field. That preserves the real access path while avoiding local production tokens, redirect URI changes, and accidental data mutation. The design matters because the goal in most debugging cases is to observe user experience, not to recreate production authentication locally. Impersonation therefore separates identity verification from diagnostic access, which is cleaner than reusing the sign-in flow for support work.

Practical implication: use impersonation for production troubleshooting and reserve redirect URI changes for legitimate deployment needs, not for debugging convenience.

Breaches seen in the wild

• Salesloft OAuth token breach — hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Dropbox Sign breach — compromised Dropbox Sign service account exposed API keys and OAuth tokens.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Redirect URI governance is part of OAuth trust boundary design, not application plumbing. The redirect endpoint determines where authorization codes land, which means it sits inside the identity control plane whether teams treat it that way or not. Exact matching, environment separation, and callback registration are all boundary controls. Practitioners should govern redirect URIs with the same discipline they apply to secrets and federation settings.

Broad redirect patterns create identity blast radius in multi-environment delivery pipelines. Wildcard subdomains are defensible only when the organisation controls the namespace and understands the tenancy model. Shared domains, tunnel domains, and opportunistic review-app patterns enlarge the set of valid destinations and weaken assurance. The practitioner conclusion is straightforward: the more dynamic the deployment model, the more tightly redirect trust must be scoped.

Impersonation is a control for observation, not a workaround for broken authentication design. The article points to a governance distinction that many teams miss. Support and engineering often want production visibility, but the right way to get that view is to assume the user context with auditability, not to reroute authentication through a local environment. That preserves accountability and keeps production tokens out of debugging workflows.

Environment-specific credentials are the real separator between safe testing and accidental exposure. Sandbox and production are not interchangeable, and the common failure mode is cross-pollinating keys, redirect URIs, and expectations between them. That breaks both availability and governance, because the same configuration mistake can stop sign-in and create unsafe access paths. Teams should treat environment isolation as an identity control requirement, not a deployment preference.

From our research:

• Only 20% have formal processes for offboarding and revoking API keys, and even fewer have procedures for rotating them, according to Ultimate Guide to NHIs.
• A separate finding shows that 96% of organisations store secrets outside secrets managers in vulnerable locations including code, config files, and CI/CD tools.
• For a broader lifecycle view, the Ultimate Guide to NHIs shows how offboarding, rotation, and visibility failures compound across machine identities.

What this signals

Redirect URI control is becoming a practical identity-governance test for application teams. As delivery pipelines become more ephemeral, teams need to prove they can keep callback trust tightly bound to the environment that actually owns the session. The risk is not just failed sign-ins, but the gradual normalisation of broad callback exceptions that later become hard to unwind.

Identity blast radius grows when debugging paths reuse production trust. The safer pattern is to separate observation from authentication and to keep support workflows inside auditable mechanisms such as impersonation. That same logic applies across NHI and human identity programmes: the more a team mixes environments, the harder it becomes to explain who accessed what, when, and under which trust boundary.

For teams aligning with NIST Cybersecurity Framework 2.0, redirect URI governance sits squarely in protect and govern activities. The operational signal to watch is whether callback registration is treated as a release artefact, not an afterthought.

For practitioners

• Register exact callback URIs per environment Keep local, staging, and production redirect URIs separate, and make the callback path, protocol, host, and port match exactly. Use environment variables so the application and dashboard stay aligned during releases.
• Pin local ports before widening URI patterns Prefer a fixed localhost port for development and only use wildcard localhost patterns when multiple developers genuinely need them. This reduces ambiguity and makes invalid redirect URI errors easier to diagnose.
• Use owned subdomains for review apps Route ephemeral review environments through a custom wildcard domain that you control, such as a preview subdomain, rather than relying on shared public suffix domains that broaden redirect trust.
• Treat impersonation as the production troubleshooting path When a support or engineering team needs to see a real user session, use impersonation with justification and audit logging instead of pointing local tooling at production authentication.

Key takeaways

• Redirect URIs are a trust boundary in OAuth, so exact matching and environment separation are security controls, not developer preferences.
• Wildcard patterns help with ephemeral review apps, but shared domains and broad matching rules increase the chance of code interception and misrouting.
• Impersonation is the right way to inspect production user experience because it preserves auditability and avoids moving production authentication into a local workflow.

Key terms

• Redirect URI: The redirect URI is the callback endpoint where an OAuth authorization server sends the browser after authentication. It is security-sensitive because it determines where the authorization code lands before the backend exchanges it for tokens, so exact registration is part of trust enforcement.
• Authorization Code Flow: Authorization code flow is the OAuth pattern where the user authenticates, the server returns a short-lived code, and the backend exchanges that code for tokens. The code is intentionally brief and tightly scoped, which is why callback integrity matters so much in practice.
• Impersonation: Impersonation is a controlled administrative action that lets an authorised operator assume a user context for debugging or support. In a well-governed setup it preserves audit logging, limits exposure of credentials, and keeps production authentication separate from local troubleshooting.
• Wildcard Redirect URI: A wildcard redirect URI allows multiple callback hosts to match a shared registration pattern, usually for dynamic environments such as review apps. The control is useful only when the domain is tightly owned and the wildcard scope is narrow enough to avoid shared-tenant exposure.

Deepen your knowledge

Redirect URI governance and OAuth callback hardening are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If your teams are separating local, staging, and production identity boundaries, the course provides a useful governance baseline.

This post draws on content published by WorkOS: Redirect URIs for local, staging, and production: secure patterns and anti-patterns. Read the original.