From 2b98588ef2f82906f3d0b64bf46a8fc4fe09eea2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pavel=20B=C5=99ou=C5=A1ek?= <brousek@ics.muni.cz>
Date: Thu, 25 Apr 2024 08:57:03 +0200
Subject: [PATCH] docs: background
---
README.md | 34 ++++++++++++++++++++++++++++++++++
1 file changed, 34 insertions(+)
diff --git a/README.md b/README.md
index a170328..8c87598 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,40 @@
[nuclei](https://docs.projectdiscovery.io/tools/nuclei/overview) templates
for testing SAML service providers.
+## Background
+
+The goal of these templates is to test SAML authentication between a SP (the target) and a conformance IdP (see below).
+
+There are two ways to start the authentication:
+
+1. IdP-initiated, starts by redirecting to an endpoint of the conformance IdP
+1. SP-initiated (the most common), which usually starts at the SP by clicking a "login" button, accessing a protected page etc.
+
+The IdP-initiated login is easier to automate, because the endpoint is known, but this produces *unsolicited* authentication responses, which some SPs might reject.
+
+SP-initiated login can have many forms, but some of them are more or less standardized:
+
+### Service Provider Request Initiation Protocol
+
+[Service Provider Request Initiation Protocol](https://docs.oasis-open.org/security/saml/Post2.0/sstc-request-initiation.html) can be used to start login with a specific IdP (it is as easy as with IdP-initiated login)
+
+> there are about 50 universally looking paths to this endpoint in eduGAIN, most of them are Shibboleth SPs (SimpleSAMLphp does not have this, neither does SATOSA; Keycloak embeds a realm in the URLs so they cannot be guessed)
+
+### Discovery response endpoint
+
+[Identity Provider Discovery Service](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf) response endpoint can be used to pretend that a user has selected a specific IdP (unsolicited message to this endpoint),
+that should also trigger an SP-initiated login.
+
+> there are about 90 universally looking paths to this endpoint in eduGAIN - Shibboleth SPs, SimpleSAMLphp, SATOSA and more
+
+### SP-specific login page/button
+
+If neither of these previously mentioned endpoints are available, we can try to find a login page and click a login button, for example:
+
+* a generic template which will assume that the button is on the home page ("/") and it has the words "log in" or "sign in" on it, and it is a link which will directly select the conformance IdP
+ * this can be further extended to be able to bypass well-known discovery services by performing the selection of conformance IdP on the DS (only applicable if the conformance IdP is going to be in the DS)
+* a SP-specific template for SP-specific behavior
+
## Requirements
### nuclei
--
GitLab