Add Esaco contribution

contributions/mw-esaco/mw-esaco.tex

@@ -23,39 +23,74 @@
 }
 
 \begin{abstract}
-  ESACO is a service that has the responsibility of checking validity and signatures 
+  Esaco is a service that has the responsibility of checking validity and signatures 
   of OAuth tokens for registered trusted OAuth authorization servers.
-  The daemon exposes an OAuth token introspection endpoint compliant with RFC 7662 
+  This service exposes an OAuth token introspection endpoint compliant with RFC 7662 
   that can be used by authenticated clients to inspect tokens. 
-  The daemon can only introspect JWT access tokens that contain the iss claim.
+  The service can only introspect JWT access tokens that contain the \texttt{iss} claim.
 \end{abstract}
 
 \section*{Introduction}
+Esaco~\cite{esaco} was initially developed to integrate the Argus Authorization 
+Service~\cite{argus} with the Indigo IAM Login Service~\cite{indigo-iam}.
 
+The initial goal was to introduce in Argus the ability to understand OAuth tokens and 
+write authorization policies based on the token claims.
+To achieve this, we need two things: a new Argus PIP that understand OAuth tokens and 
+a service that interact with the token issuer to validate the access tokens and get more
+information about the user.
 
+Esaco covers the second requirement to achieve this integration.
 
-\section*{Usage}
-Esaco is registered as a client at one (or more) trusted OAuth authorization servers, 
-and is used by client applications as a gateway for token validation and introspection.
-Esaco performs local JWT validation checks and leverages the introspection endpoints 
-at trusted AS to inspect a submitted token. The result of a token introspection is cached, 
-if caching is enabled.
+\section*{How Esaco works}
+Esaco is a very light Spring Boot~\cite{spring-boot} application, developed in Java.
+It runs behind a reverse proxy to enable the SSL communication with both Argus and
+the configured OAuth authorization servers (AS).
+
+Esaco is registered as a client at one (or more) trusted OAuth authorization servers,
+listed into the configuration file, and is used by client applications as a gateway 
+for token validation and introspection.
+
+Esaco expose two endpoints: an endpoint compliant with the standard RFC 7662 OAuth 
+Token Introspection and another not-standard endpoint, that return a data structure 
+used by Argus, that is the union of the token introspection and the user details obtained
+from the \texttt{userinfo} endpoint of the issuer authorization server.
+
+When a token is submitted to Esaco, it performs local JWT validation checks and 
+leverages the introspection endpoints at trusted AS to inspect the token. 
+The result of a token introspection is cached, if caching is enabled, to speedup
+other following introspection requests.
+
+Esaco is not bounded to Argus, but it is general purpose service.
+Another usefull integration, is the use of Esaco to overcome the limitation of 
+the Apache OpenID-Connect module, that support only a single OAuth issuer.
 
 \section*{About the name \textit{Esaco}}
-In Greek mythology, \textit{Esaco} (or \textit{Aesacus}) was a son of king Prim of Troy, half
-brother of \textit{Cassandra}.
+In Greek mythology, \textit{Esaco} (or \textit{Aesacus}) was a son of king Prim of Troy, 
+half brother of the most famous \textit{Cassandra}.
+
 \textit{Esaco} was born with the gift of the interpretation of dreams, so
 people ask him to understand their own dreams.
+
 One day he catches sight of the nymph Hesperia, falls in love, and pursues her.
 However, Hesperia dies because of the bite of a poisonous snake.
+
 \textit{Esaco}, unable to bear living any longer, leaps from a tall cliff
 into the sea but as he plunges, he is changed into a bird by the godess Tethys.
 \textit{Esaco} still attempts to dive into the depth yet continues still to live
 in the form of a diving bird, called \textit{smergo}.
 
+Just as Esaco in the Greek myth interpreted the people dreams, our Esaco service
+introspect and decode the JWT access token.
+
 \section*{References}
 \begin{thebibliography}{99}
-	\bibitem{esaco} Esaco on GitHub \url{https://github.com/indigo-iam/esaco}
+  \bibitem{esaco} Esaco on GitHub \url{https://github.com/indigo-iam/esaco}
+  \bibitem{argus} Argus Authorization Service \url{https://argus-documentation.readthedocs.io}
+  \bibitem{indigo-iam} Indigo IAM documentation \url{https://indigo-iam.github.io/docs}
+  \bibitem{spring-boot} Spring Boot project \url{https://projects.spring.io/spring-boot/}
+  \bibitem{rfc7662} RFC 7662 OAuth 2.0 Token Introspection \url{https://tools.ietf.org/html/rfc7662}
+  \bibitem{mod-apache-oidc} Apache OpenID-Connect module \url{https://github.com/zmartzone/mod_auth_openidc}
 \end{thebibliography}
 
 \end{document}