docs: add longer introduction and a diagram

Author: TomiBelan

README.md

@@ -1,9 +1,15 @@
-# Andrvotr: service delegation plugin for Shibboleth IdP
+# Andrvotr
 
-Andrvotr allows one service to sign in to another service on behalf of the user.
+Andrvotr is a service delegation plugin for Shibboleth IdP (Identity Provider). It allows one service to sign in to another service on behalf of the user.
 
 The IdP administrator can define pairs of "front services" and "back services". When any *user* **U** signs in to a given *front service* **F**, the server of **F** can ask the IdP to sign in to its *back service* **B** on behalf of **U**, and send authenticated HTTP requests to the server of **B** in the name of **U**.
 
+Andrvotr is similar to OAuth in that both allow one service to authenticate on behalf of a user to another service. The IdP is analogous to the OAuth authorization server, the front service is like the OAuth client, and the back service acts as the OAuth resource server.
+
+The defining feature of Andrvotr is that the back service can be a normal SAML SP (Service Provider), and does not need to be aware of the protocol. This is useful if the back service only supports basic SAML and cannot be modified. But in circumstances where it's possible to replace the sign in system, it is recommended to use OAuth instead of Andrvotr and SAML.
+
+Andrvotr is used in production at [Comenius University](https://uniba.sk/en/) to power [Votr](https://github.com/fmfi-svt/votr), [Anketa](https://github.com/fmfi-svt/anketa) and [ePrihlaska](https://github.com/fmfi-svt/eprihlaska).
+
 ## Deployment requirements (limitations)
 
 This is a list of facts that Andrvotr requires from its environment. They must be satisfied in order to successfully deploy and use Andrvotr.
@@ -30,18 +36,40 @@ This is a list of design requirements that Andrvotr meets. In contrast to the li
 
 ## How it works
 
+```mermaid
+sequenceDiagram
+    participant U as User+Browser
+    participant IdP
+    participant F as Front service
+    participant B as Back service
+    note over U, F: Normal SAML SSO flow:
+    U->>F: POST /ClickLoginButton
+    F->>U: 303 to https://IdP/.../SSO<br>with SAML request
+    U->>IdP: ;
+    U<<->>IdP: user enters credentials<br>or reuses older IdP session
+    IdP->>U: 200 OK with POST to https://F/.../ACS<br>with SAML response to F's request<br>with Andrvotr Authority Token
+    U->>F: ;
+    F->>U: 200 OK with a session cookie
+    note over IdP, B: Andrvotr SSO flow:
+    F->>B: POST /ClickLoginButton
+    B->>F: 303 to https://IdP/.../SSO<br>with SAML request
+    F->>IdP: POST /.../andrvotr/fabricate<br>with original SSO url,<br>Andrvotr Authority Token,<br>front SP ID, API key
+    IdP->>IdP: GET /.../SSO<br>(internal nested request)
+    IdP->>F: 200 OK with POST to https://B/.../ACS<br>with SAML response to B's request
+    F->>B: ;
+    B->>F: 200 OK with a session cookie
+```
+
 The front service receives an "Andrvotr Authority Token" from the IdP as a SAML attribute inside its SAML assertion. The token is essentially an encrypted tuple of (front service entity ID, user's IdP session cookies, expiration timestamp). It identifies a specific user accessing a specific front service at a specific point in time. It can be used to exchange SAML requests for SAML responses.
 
-The front service then sends a login request to the back service, thus starting a normal SP-initiated SAML web flow. It follows redirects and maintains a cookie jar like real browsers. The back service responds with a HTTP redirect containing an encoded SAML request. This redirect would normally lead to the IdP's sign in form page.
+The front service then sends a login request to the back service, thus starting a SP-initiated SAML web flow. It follows redirects and maintains a cookie jar like real browsers. The back service responds with a HTTP redirect containing an encoded SAML request. This redirect would normally lead to the IdP's sign in form page.
 
 Instead of following this redirect, the front service sends a special request to the IdP, asking Andrvotr to generate an artificial SAML response for this SAML request and Andrvotr Authority Token. If the request is valid and this front to back service connection is allowed, Andrvotr returns a SAML response. This is implemented with a nested request from the IdP to itself. The SAML response is just like what it would be if this user would sign into the back service directly.
 
 The front service forwards this SAML response to the back service, receiving a session cookie and completing the sign in.
 
 The key benefit of this design is that it requires zero changes to the back service, which just sees normal SAML flow. The cost is a moderate amount of front service complexity. If this is not a requirement you have, Andrvotr might not be the right solution for you.
 
-<!-- TODO: Add a diagram. -->
-
 ## IdP setup
 
 1.  Look up the latest plugin version on the [Releases page](https://github.com/fmfi-svt/andrvotr/releases).
@@ -161,6 +189,8 @@ The key benefit of this design is that it requires zero changes to the back serv
     sudo -u {USER} /opt/shibboleth-idp/bin/plugin.sh -i $PWD/andrvotr-dist/target/idp-plugin-andrvotr-*-SNAPSHOT.tar.gz --noCheck
     ```
 
+For more information about developing and testing the plugin with a local IdP, see https://github.com/fmfi-svt/saml-shibboleth-guide.
+
 ## Developing front services
 
 Front services which want to use Andrvotr to connect to a back service must follow this procedure.
@@ -185,6 +215,7 @@ You will need:
       ```
     - If the IdP does not send you the attribute, the process cannot continue.
       This is most likely because the IdP is not configured correctly (andrvotr.allowedConnections, andrvotr.apiKeys).
+      Or it can happen if the IdP is configured to ask for attribute consent, and the user did not give it.
 
 2.  Initialize an empty cookie jar. It will be used for all HTTP requests you send.
 
@@ -222,5 +253,3 @@ It is not integrated with an SP -- you must extract the token and run demo.py ma
 The demo requires some Python libraries. Either [install "uv"](https://docs.astral.sh/uv/getting-started/installation/) which will take care of it. Or `apt install python3-bs4 python3-requests` and run with `python3 demo.py ...`. Or create a venv with `beautifulsoup4` and `requests`.
 
 [Votr](https://github.com/fmfi-svt/votr/blob/master/fladgejt/login.py) contains another implementation of this procedure (also in Python).
-
-<!-- TODO: ## Similar projects -->