Redirect URIs

The redirect URI is where SingleSign sends the user after they authenticate. It is a critical security boundary — if an attacker can trick SingleSign into redirecting to a URI they control, they can steal the authorization code and exchange it for tokens.

SingleSign enforces strict rules to prevent this.

How Redirect URIs Work

1. You register one or more redirect URIs in the developer portal when creating your app.
2. When your app initiates the authorization flow, it includes a redirect_uri parameter.
3. SingleSign checks that the redirect_uri exactly matches one of the registered URIs.
4. If there's a match, SingleSign redirects the user to that URI with the authorization code.
5. If there's no match, the request is rejected with an error.

GET https://api.singlesign.com/oauth/authorize
  ?platform_guid=YOUR_PLATFORM_GUID
  &response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://app.example.com/callback    ← must match exactly
  &scope=openid+profile+email
  &state=RANDOM_STATE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

Rules

1. HTTPS is Required in Production

All redirect URIs must use the https:// scheme in production. This ensures the authorization code is transmitted over an encrypted channel.

Exception: http://localhost (with any port) is allowed for local development.

✅ https://app.example.com/callback
✅ https://staging.example.com/auth/callback
✅ http://localhost:3000/callback          (development only)
✅ http://localhost:8080/auth/callback      (development only)
❌ http://app.example.com/callback         (not HTTPS)

2. Exact Match — No Wildcards

SingleSign compares the redirect_uri parameter against the registered URIs using exact string matching. There is no wildcard, pattern, or subdomain matching.

Registered: https://app.example.com/callback

✅ https://app.example.com/callback
❌ https://app.example.com/callback/       (trailing slash)
❌ https://app.example.com/callback?foo=bar (query string)
❌ https://APP.example.com/callback         (case difference in path)
❌ https://*.example.com/callback           (wildcard — not supported)

3. No Query Parameters

The registered URI must not include query parameters. SingleSign will append the code and state parameters to the URI during the redirect.

Registered: https://app.example.com/callback

Redirect will be:
https://app.example.com/callback?code=AUTH_CODE&state=RANDOM_STATE

4. No Fragments

Fragment identifiers (#) are not allowed in redirect URIs.

❌ https://app.example.com/callback#section

5. Custom URI Schemes for Mobile

Mobile and native apps may use custom URI schemes:

✅ com.yourcompany.yourapp://callback
✅ com.yourcompany.yourapp://auth/callback

For production mobile apps, prefer universal links (iOS) or app links (Android) over custom schemes for stronger security. See the Mobile / Native Guide.

Allow-Listing in the Developer Portal

Adding Redirect URIs

1. Go to Developer Portal → Applications → (your app) → Settings.
2. In the Redirect URIs section, click Add URI.
3. Enter the full URI including the scheme, host, port (if non-standard), and path.
4. Save.

Multiple Environments

Register a separate redirect URI for each environment:

Your app selects the appropriate URI at runtime based on the environment.

Common Mistakes

1. Trailing Slash Mismatch

Problem: Registered https://app.example.com/callback but the app sends https://app.example.com/callback/.

Fix: Make sure the registered URI and the redirect_uri parameter are identical, including the presence or absence of a trailing slash.

2. Port Mismatch

Problem: Registered http://localhost:3000/callback but the dev server runs on port 5173.

Fix: Register the URI with the correct port, or register multiple ports.

3. Scheme Mismatch

Problem: Registered https:// but the app sends http:// (or vice versa).

Fix: Always use https:// in production. For localhost, ensure the scheme matches.

4. Path Mismatch

Problem: Registered https://app.example.com/auth/callback but the app sends https://app.example.com/callback.

Fix: The full path must match. Double-check the registered path against your application's route.

5. Forgetting to Register a New Environment

Problem: Deployed to a new staging URL but forgot to add its redirect URI.

Error: redirect_uri_mismatch — "The redirect_uri does not match any registered redirect URIs."

Fix: Add the new URI in the developer portal before deploying.

6. Using Wildcards

Problem: Attempting to register https://*.example.com/callback or https://app.example.com/*.

Fix: Wildcards are not supported. Register each exact URI individually.

Security Rationale

Why Exact Matching?

Open redirect vulnerabilities are one of the most common OAuth attacks. If SingleSign allowed wildcards or partial matching:

• https://*.example.com/callback could match https://evil.example.com/callback.
• https://app.example.com/* could match https://app.example.com/attacker-controlled-page.

Exact matching eliminates these attack vectors entirely.

Why HTTPS?

Without HTTPS, the authorization code is sent in cleartext over the network. An attacker on the same network (e.g., public Wi-Fi) could intercept it and exchange it for tokens.

The localhost exception exists because local development traffic never leaves your machine.

Redirect URI Validation Flowchart

Client sends redirect_uri
        │
        ▼
Is redirect_uri registered? ──No──▶ Reject: redirect_uri_mismatch
        │
       Yes
        │
        ▼
Is it HTTPS or localhost? ──No──▶ Reject: invalid redirect scheme
        │
       Yes
        │
        ▼
Proceed with authorization flow

Troubleshooting

If you receive a redirect_uri_mismatch error:

1. Copy the exact URI from your application's authorization request (check the browser's address bar or network tab).
2. Compare it character by character to the URI registered in the developer portal.
3. Check for: trailing slashes, scheme differences, port differences, path differences, and URL encoding differences.
4. If using a framework that auto-appends a trailing slash, either update the registered URI or configure the framework to not add it.

Next Steps

• Register an App — Configure redirect URIs in the portal.
• SPA with PKCE Guide — See redirect URIs in action.
• Mobile / Native Guide — Custom URI schemes and universal links.
• Troubleshooting — Fix common redirect URI issues.