# Configure OAuth redirect URIs

> Source: https://docs.clonepartner.com/security/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:

```text
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:

```text
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:

```text
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.