Configure OAuth redirect URIs

Envoy supports Microsoft Entra ID and Google OAuth sign-in. Each provider must allow the exact callback URL Envoy sends during authorization and token exchange.

Callback format

Register one callback per provider and public Envoy origin:

https://envoy.example.com/api/auth/oauth/microsoft/callback
https://envoy.example.com/api/auth/oauth/google/callback

Paths and provider names are lowercase. Scheme, host, port, path, and trailing slash behavior must match exactly.

How Envoy determines the origin

For the OAuth request, Envoy uses:

1. X-Forwarded-Proto when present, otherwise the request scheme;
2. X-Forwarded-Host when present, otherwise the request host;
3. /api/auth/oauth/{provider}/callback.

The authorization start request and callback must resolve to the same public origin.

Reverse-proxy configuration

Terminate TLS at an approved proxy and forward the original values:

X-Forwarded-Proto: https
X-Forwarded-Host: envoy.example.com

Do not forward an untrusted client-supplied host unchanged. Configure the proxy with an allowlisted public host and replace inbound forwarding headers.

If the application is exposed on a non-default port, include it in both the forwarded host and registered redirect URI.

Provider setup

For Microsoft Entra ID:

• create a web application registration;
• register the Microsoft callback URI;
• configure client ID and secret;
• set the intended tenant ID when access should be tenant-restricted.

For Google:

• create an OAuth web client;
• register the Google callback URI;
• configure client ID and secret;
• configure the consent screen and allowed users as required.

Store client secrets through deployment secret management. Never put them in documentation, browser code, or task YAML.

Multiple environments

Register each environment separately:

https://envoy-dev.example.com/api/auth/oauth/google/callback
https://envoy.example.com/api/auth/oauth/google/callback

Prefer separate OAuth clients for development and production so credentials, consent, and revocation are isolated.

Verify safely

1. Open the public HTTPS login page.
2. Start sign-in for the provider.
3. Inspect the provider's redirect_uri value.
4. Confirm it matches an allowlisted URI exactly.
5. Complete sign-in.
6. Verify the callback returns to the expected origin.
7. Test account linking separately if enabled.
8. Repeat through every production proxy or hostname.

Troubleshooting

• redirect_uri_mismatch: compare the URI character for character.
• Internal HTTP host appears: forward the public proto and host.
• Wrong tenant: verify Microsoft tenant configuration and account policy.
• Callback loops to login: verify cookies, HTTPS, proxy headers, and clock synchronization.
• Works locally only: add the production callback and test through the production proxy.

OAuth uses state and PKCE protections, but those controls do not compensate for accepting an attacker-controlled forwarded host. Validate proxy trust boundaries.