OAuth2 Redirect URI Whitelisting for HackGATE

Overview

When using OAuth2-based authentication (for example with Google, Microsoft Entra ID, Azure AD B2C, Okta, Auth0, or similar IdPs) behind HackGATE, the authentication flow may fail if the HackGATE domain is not included in the OAuth2 redirect URI whitelist.

Because HackGATE serves your application through its own proxy domain (for example https://yourtenant.hackgate.net), the Identity Provider (IdP) must explicitly trust this domain as a valid redirect destination.

This article explains why redirect whitelisting is required, what symptoms indicate a missing configuration, and how to correctly configure OAuth2 redirect URIs for HackGATE.

1. Why OAuth2 Redirect Whitelisting Is Required

OAuth2 enforces strict redirect validation to prevent token leakage and open redirect attacks.

During login, the OAuth2 flow performs the following steps:

1. User is redirected to the Identity Provider (IdP)
2. After successful authentication, the IdP redirects the user back to the application
3. The redirect target must exactly match one of the pre-registered redirect URIs

When your application is accessed via HackGATE:

• The callback URL hostname changes
• The IdP sees the HackGATE domain as the redirect destination
• If this domain is not whitelisted, the IdP blocks the redirect

This is expected OAuth2 security behavior.

2. Common Symptoms

If the HackGATE domain is not whitelisted, you may see:

• Login fails after successful authentication
• Error pages such as:
  • redirect_uri_mismatch
  • The redirect URI is not registered
  • Invalid redirect_uri
  • AADSTS50011 (Microsoft Entra / Azure AD)
• Authentication works on the original domain, but fails via HackGATE
• User is redirected to an error page on the IdP instead of back to the app

3. What Needs to Be Whitelisted

You must whitelist the exact OAuth2 redirect URI used by your application when accessed via HackGATE.

Examples

If your application normally uses:

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


When proxied by HackGATE, it may become:

https://yourtenant.hackgate.net/auth/callback


The HackGATE-based redirect URI must be added explicitly.

Important rules:

• Redirect URIs must match scheme + hostname + path
• Wildcards are usually not allowed in OAuth2 redirect URIs
• Query parameters must match exactly if required by the IdP

4. How to Configure the Redirect URI (General Steps)

Step 1 — Identify the Callback Path

Determine the OAuth2 callback endpoint used by your application, for example:

• /auth/callback
• /signin-oidc
• /oauth2/callback

Step 2 — Construct the HackGATE Redirect URI

Combine the callback path with your HackGATE domain:

https://<your-hackgate-subdomain>.hackgate.net/<callback-path>


Step 3 — Add the URI to Your Identity Provider

In your IdP’s application/client configuration:

• Locate Redirect URIs, Callback URLs, or Reply URLs
• Add the HackGATE redirect URI
• Save and apply changes

Step 4 — Test the Login Flow via HackGATE

Retry authentication through the HackGATE URL.

If configured correctly, the login flow should complete successfully.

5. Identity Provider–Specific Notes

Microsoft Entra ID / Azure AD / Azure AD B2C

• Error code AADSTS50011 indicates missing or mismatched redirect URI
• Redirect URI must be added under:
• App Registration → Authentication → Redirect URIs
• Trailing slashes matter

Google OAuth

• Redirect URI must be listed under:
• APIs & Services → Credentials → OAuth 2.0 Client IDs
• HTTP vs HTTPS mismatch will cause failure

Auth0 / Okta / Others

• Redirect URIs must be an exact match
• Environment-specific URIs (prod / staging / HackGATE) must be added individually

6. Security Notes

• Adding the HackGATE redirect URI does not weaken authentication security
• OAuth2 validation remains strict
• Tokens are still issued only after successful authentication
• HackGATE does not modify OAuth2 tokens or authentication responses

This step simply informs the IdP that the HackGATE domain is a trusted entry point for your application.

7. Troubleshooting Checklist

If authentication still fails after adding the redirect URI:

• Verify there is no typo in hostname or path
• Check for missing or extra trailing slashes
• Confirm the callback path is the same as used in production
• Check IdP error logs for redirect-related errors
• Ensure HTTPS is used (most IdPs reject HTTP)

8. Contact Support

If you need assistance, please provide:

• Your HackGATE URL
• Identity Provider name
• OAuth2 error message or code
• The redirect URI you configured

Hackrate Support can help verify the correct redirect configuration.