oauth2-proxy/docs/docs/features/endpoints.md

id	title
endpoints	Endpoints

OAuth2 Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated. The /oauth2 prefix can be changed with the --proxy-prefix config variable.

• / - the proxy endpoint provides authentication and returns the appropriate 40x error if not authenticated or authorized then passes the request upstream.
• /robots.txt - returns a 200 OK response that disallows all User-agents from all paths; see robotstxt.org for more info
• /ping - returns a 200 OK response, which is intended for use with health checks
• /ready - returns a 200 OK response if all the underlying connections (e.g., Redis store) are connected
• /metrics - Metrics endpoint for Prometheus to scrape, serve on the address specified by --metrics-address, disabled by default
• /oauth2/sign_in - the login page, which also doubles as a sign-out page (it clears cookies)
• /oauth2/sign_out - this URL is used to clear the session cookie
• /oauth2/start - a URL that will redirect to start the OAuth cycle
• /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
• /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
• /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the Nginx auth_request directive
• /oauth2/auth/sign_in - returns a 202 Accepted response when authenticated, or redirects to the sign-in flow when unauthenticated; for use with the Traefik ForwardAuth middleware
• /oauth2/static/* - stylesheets and other dependencies used in the sign_in and error pages

Sign out

To sign the user out, redirect them to /oauth2/sign_out. This endpoint only removes oauth2-proxy's own cookies, i.e. the user is still logged in with the authentication provider and may automatically re-login when accessing the application again. You will also need to redirect the user to the authentication provider's sign-out page afterward using the rd query parameter, i.e. redirect the user to something like (notice the url-encoding!):

/oauth2/sign_out?rd=https%3A%2F%2Fmy-oidc-provider.example.com%2Fsign_out_page

Alternatively, include the redirect URL in the X-Auth-Request-Redirect header:

GET /oauth2/sign_out HTTP/1.1
X-Auth-Request-Redirect: https://my-oidc-provider/sign_out_page
...

(The "sign_out_page" should be the end_session_endpoint from the metadata if your OIDC provider supports Session Management and Discovery.)

BEWARE that the domain you want to redirect to (my-oidc-provider.example.com in the example) must be added to the --whitelist-domain configuration option otherwise the redirect will be ignored. Make sure to include the actual domain and port (if needed) and not the URL (e.g "localhost:8081" instead of "http://localhost:8081").

ID Token can be injected in the redirect url by using {id_token} placeholder. For example to redirect to https://my-oidc-provider.example.com/sign_out_page?id_token_hint={id_token}&post_logout_redirect_uri=https://my-app.example.com;

/oauth2/sign_out?rd=https%3A%2F%2Fmy-oidc-provider.example.com%2Fsign_out_page%3Fid_token_hint%3D%7Bid_token%7D%26post_logout_redirect_uri%3Dhttps%3A%2F%2Fmy-app.example.com

or alternatively in the header:

GET /oauth2/sign_out HTTP/1.1
X-Auth-Request-Redirect: https://my-oidc-provider.example.com/sign_out_page?id_token_hint={id_token}&post_logout_redirect_uri=https://my-app.example.com
...

Auth

This endpoint returns 202 Accepted response or a 401 Unauthorized response.

It can be configured using the following query parameters:

• allowed_groups: comma separated list of allowed groups
• allowed_email_domains: comma separated list of allowed email domains
• allowed_emails: comma separated list of allowed emails

Auth Sign In

This endpoint returns a 202 Accepted response when authenticated and authorized, or redirects to the sign-in flow when there is no valid session. If the user is authenticated but fails authorization checks (e.g., not in an allowed group), it returns 403 Forbidden to prevent infinite redirect loops.

When --skip-provider-button is set, unauthenticated requests are redirected directly to the OAuth provider. Otherwise, the oauth2-proxy sign-in page is shown.

This endpoint is useful with reverse proxies like Traefik that use ForwardAuth, as it combines auth checking with sign-in redirect in a single endpoint — no separate error middleware is needed.

It can be configured using the following query parameters:

• allowed_groups: comma separated list of allowed groups
• allowed_email_domains: comma separated list of allowed email domains
• allowed_emails: comma separated list of allowed emails

Proxy (/)

This endpoint returns the upstream response if authenticated. If unauthenticated it returns a 401 Unauthorized. If the authenticatd user is not in one of the allowed groups, or emails then it returns a 403 forbidden

It can be configured using the following query parameters:

• allowed_groups: comma separated list of allowed groups
• allowed_email_domains: comma separated list of allowed email domains
• allowed_emails: comma separated list of allowed emails