From 400aea365338ff2a5110cdfce22fea62a3204e42 Mon Sep 17 00:00:00 2001
From: Jakub Holy <jakub.holy@telia.no>
Date: Sat, 14 Mar 2020 11:07:23 +0100
Subject: [PATCH] Document how to use the sign_out endpoint (#443)

Fixes #441

+ a minor link fix
---
 docs/2_auth.md      |  2 +-
 docs/5_endpoints.md | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/2_auth.md b/docs/2_auth.md
index ba793bec..cbf63805 100644
--- a/docs/2_auth.md
+++ b/docs/2_auth.md
@@ -87,7 +87,7 @@ Note: The user is checked against the group members list on initial authenticati
    --client-secret=<value from step 6>
 ```
 
-Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the [redis session storage](configuration#redis-storage) should resolve this.
+Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the [redis session storage](configuration/sessions#redis-storage) should resolve this.
 
 ### Facebook Auth Provider
 
diff --git a/docs/5_endpoints.md b/docs/5_endpoints.md
index f4132d98..3df2224e 100644
--- a/docs/5_endpoints.md
+++ b/docs/5_endpoints.md
@@ -17,3 +17,23 @@ OAuth2 Proxy responds directly to the following endpoints. All other endpoints w
 - /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](#nginx-auth-request)
+
+### 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 afterwards 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`](https://openid.net/specs/openid-connect-session-1_0.html#rfc.section.2.1) from [the metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) 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) configuration option otherwise the redirect will be ignored.