Revision for the mw-esaco contribution

contributions/mw-esaco/mw-esaco.tex

@@ -6,7 +6,7 @@
 
 \begin{document}
 
-\title{Esaco: the OIDC client to support multiple provider}
+\title{Esaco: an OAuth/OIDC token introspection service}
 
 \author{
 	M. Caberletti,
@@ -26,62 +26,106 @@
   Esaco is a service that has the responsibility of checking validity and signatures 
   of OAuth tokens for registered trusted OAuth authorization servers.
   This service exposes an OAuth token introspection endpoint compliant with RFC 7662 
-  that can be used by authenticated clients to inspect tokens. 
-  The service can only introspect JWT access tokens that contain the \texttt{iss} claim.
+  that can be used by authenticated clients to inspect JWT OAuth tokens. 
 \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 
+The 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.
+To keep the Argus implementation OAuth-agnostic, we chose to split the
+development in two separate components: 
+
+\begin{itemize}
+
+  \item a new Argus Policy Information Point (PIP), added to the Argus
+    codebase, that would have the responsibility of extracting token
+    information from the XACML authorization request submitted to Argus; 
+
+  \item a token inspection and validation service, ESACO, that would be
+    contacted by the PIP to actually extract information from the authorization
+    token.
+
+\end{itemize}
+
+This approach had the following advantages:
+
+\begin{itemize}
+    \item minimize the changes to the Argus codebase and avoid
+      dependency-clashes that could by caused by introducing explicit support
+      for JWT token validation in Argus; 
+	
+    \item provide a standalone microservice responsible for token introspection
+      that could be useful also for integrating support for token-based
+      authorization in other services with minimal changes.
+\end{itemize}
 
 \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 is a lightweight Spring Boot~\cite{spring-boot} application, developed in
+the Java programming language. It is typically deployed behind a reverse proxy that 
+terminates TLS such as NGINX\cite{nginx}.
 
-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.
+Esaco is registered as a client at one (or more) trusted OAuth authorization
+servers and is accessed by client applications as a gateway for token
+validation and introspection.
 
-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 exposes two endpoints: an endpoint compliant with the OAuth token
+introspection standard (RFC 7662) and an Argus specific endpoint that combines
+the result of token introspection with authentication details obtained from the
+OpenID-Connect \texttt{userinfo} endpoint of Authorization Server that issued the
+token. 
 
-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.
+When a token is submitted to Esaco, it performs local JWT validation checks and
+leverages the introspection endpoints at the remote  AS to inspect the token.
+The result of a token introspection is cached, if caching is enabled, to
+speedup future introspection requests for the same token. 
+
+\section*{Esaco Argus integration}
+
+Esaco has been successfully integrated in the Argus authorization service,
+enabling support for token-based authorization driven by Argus policies.
+
+Besides the PIP described above, the Argus PEP Java client was modified in
+order to submit authorization requests containing tokens and a profile was
+defined and integrated in the Argus PDP and PAP services to allow the whole
+system to render authorization decisions based on the OAuth token contents. 
+
+\begin{figure}
+  \centering
+  \includegraphics[scale=0.8]{argus-esaco-01.png}
+  \caption{The ESACO Argus integration.}
+  \label{fig:esaco-argus}
+\end{figure}
+
+This integration, depicted in figure \ref{fig:esaco-argus}, will allow services that are
+OAuth-token agnostic to delegate authorization decisions to Argus.
 
 \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 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.
+In Greek mythology, \textit{Esaco} (or \textit{Aesacus}) was a son of king
+Priam of Troy, half-brother of the most famous \textit{Cassandra}.
+\textit{Esaco} was born with a special gift: he could interpret dreams, and was
+often requested to do so by people who wanted to know the meaning of 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}.
+into the sea but as he plunges, he is turned into a bird by the goddess Tethys.
+\textit{Esaco} still attempts to dive into the depth yet continues to live in
+the form of a diving bird, the merganser \cite{esaco-wikipedia}.
+
+Just as Esaco in Greek mythology was capable of interpreting dreams, our Esaco
+service introspects and decodes OAuth tokens.
 
-Just as Esaco in the Greek myth interpreted the people dreams, our Esaco service
-introspect and decode the JWT access token.
+Or, if you don't want to remember this whole story, you can refer to the
+service as the Extra-Slim Authorization Checker for OAuth (ESACO).
 
 \section*{References}
 \begin{thebibliography}{99}
@@ -91,6 +135,8 @@ introspect and decode the JWT access token.
   \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}
+  \bibitem{esaco-wikipedia} Aesacus on Wikipedia \url{https://en.wikipedia.org/wiki/Aesacus}
+  \bibitem{nginx} The NGINX Web Server site \url{https://nginx.org}
 \end{thebibliography}
 
 \end{document}