Add usage notice in readme file

README.adoc

@@ -1,18 +1,184 @@
 = central-saml-logout
 
-=== License
+This project is a dedicated service that allows to perform Single Logout (SLO) actions.
+
+Many web applications nowadays support SAML 2.0, but there is a lack of support for the SLO mechanism, which causes additional costs for plugins with proprietary licenses.
+In order to reduce costs a dedicated logout service can be used to perform logout actions for all applications instead of using the SLO mechanism for each application.
+
+This solution is intended to be used with a proxy to specify URL https://en.wikipedia.org/wiki/Rewrite_engine[rewrite rules] to internally rewrite requests directed to a logout URL of a https://en.wikipedia.org/wiki/Service_provider_(SAML)[service provider (SP)] to the dedicated service, which can handle the logout instead.
+
+.The Use case explained via communication diagram
+image::docs/images/use-case.drawio.png[Use case explained]
+
+== What is Single Logout (SLO)
+
+When a user initiates a logout, the SAML 2.0 https://en.wikipedia.org/wiki/Identity_provider[identity provider (IdP)] performs a logout for all service providers in the current session of the identity provider.
+
+== Usage
+
+To pass arguments to the application there are three options available.
+
+* create a _.env_ file to specify the environment variables
+* set the environment variables directly
+* use command line parameters
+
+[cols="7,7,15,1",options="header"]
+|===
+
+|command line parameter
+|environment variable
+|description
+|required
+
+|`‑n` +
+`‑‑server‑hostname`
+|`SERVER_HOSTNAME`
+|The server hostname. (default: "localhost", default for use inside a docker container: "0.0.0.0")
+|no
+
+|`‑p` +
+`‑‑server‑port`
+|`SERVER_PORT`
+|The server port. (default: "8090")
+|no
+
+|`‑b` +
+`‑‑base‑url`
+|`BASE_URL`
+|The frontend base URL (default: "http://localhost:8090")
+|no
+
+|`‑m` +
+`‑‑idp‑metadata`
+|`IDP_METADATA`
+|A local file path or URL directed to the IdP metadata.
+|yes
+
+|`‑i` +
+`‑‑issuer`
+|`ISSUER`
+|The SAML issuer. (default: the callback URL)
+|no
+
+|`‑c` +
+`‑‑cookies‑to‑clear`
+|`COOKIES_TO_CLEAR`
+|An optional list of cookies that are cleared on logout for all service providers to end the running sessions directly. See the topic session invalidation below.
+|no
+
+|`‑l` +
+`‑‑fallback‑logout‑url`
+|`FALLBACK_LOGOUT_URL`
+|Do only specify if needed. The fallback URL if no URL is specified in the query string of the logout call.
+|no
+
+|`‑s` +
+`‑‑login‑success‑url`
+|`LOGIN_SUCCESS_URL`
+|Do only specify if needed. An alternative page to signal login success.
+|no
+
+|`‑f` +
+`‑‑login‑failure‑url`
+|`LOGIN_FAILURE_URL`
+|Do only specify if needed. An alternative page to signal login failure.
+|no
+
+|`‑h` +
+`‑‑help`
+|
+|Shows a detailed help text and ignores other arguments.
+|
+
+|`‑V` +
+`‑‑version`
+|
+|Shows the tool version and ignores other arguments.
+|
+
+|===
+
+=== Session invalidation
+
+The SLO mechanism allows to end the identity provider session, but the sessions of the service providers remain active.
+If this is a problem, there are two strategies to handle it.
+
+1. The session of each service provider is short-lived by a restrictive timeout.
+2. The central-saml-logout service allows to invalidate the session for each application of the whole platform by specifying a list of cookies that will be cleared on the logout action.
+
+NOTE: In modern browsers cross-site scripting (XSS) only works via HTTPS and only with the cookie attributes "SameSite=None" and "Secure".
+This is done by enabling cross-site scripting.
+See example below.
+
+.Notation for cookies to clear
+[source,json]
+----
+[
+  {
+    "domain": "sp1.domain.tld",
+    "name": "MY_SESSION_ID",
+    "xss": true
+  },
+  {
+    "domain": "domain.tld",
+    "path": "/sp2",
+    "name": "MY_SESSION_ID",
+    "xss": false
+  }
+]
+----
+
+=== Proxy configuration
+
+The proxy needs to be configured with a redirection to pass logout actions of a service provider to the central-saml-logout service.
+In order to allow the central-saml-logout service to clear the running session of a service provider, additional headers that enable XSS must be specified.
+
+.Example configuration for Nginx
+[source]
+----
+server {
+
+...
+
+    add_header Access-Control-Allow-Credentials true;
+    add_header Access-Control-Allow-Headers Set-Cookie;
+    add_header Access-Control-Allow-Origin https://central-saml-logout.domain.tld;
+
+    location ~ ^/sp1/logout$ {
+         return 302 https://central-saml-logout.domain.tld/logout?http://localhost:8080/sp1/status;
+    }
+
+...
+
+}
+----
+
+.Example configuration for Apache2 HTTP Server
+[source]
+----
+<VirtualHost *:8080>
+
+...
+
+    Header set Access-Control-Allow-Credentials "true"
+    Header set Access-Control-Allow-Headers "Set-Cookie"
+    Header set Access-Control-Allow-Origin "http://localhost:8181"
+
+    RewriteRule ^/sp1/logout$ "https://central-saml-logout.domain.tld/logout?http://localhost:8080/sp1/status" [R=302,L]
+
+...
+
+</VirtualHost>
+----
+
+== License
 
 Copyright (c) 2022 ASERVO Software GmbH
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
 _http://www.apache.org/licenses/LICENSE-2.0_
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License.

docs/images/use-case.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2023-01-09T00:50:31.158Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" etag="snbKIkKygmnReu8Guxrw" version="20.8.3" type="device"><diagram id="rOvC9Trzw2GRtopu_ALN" name="Seite-1">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</diagram></mxfile>