From 3f9643c44660683433960fa3722794b9075bd761 Mon Sep 17 00:00:00 2001 From: brianmajor Date: Thu, 5 May 2022 15:03:21 -0700 Subject: [PATCH] Fixes #11 - line length --- doc/SSO.tex | 468 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 331 insertions(+), 137 deletions(-) diff --git a/doc/SSO.tex b/doc/SSO.tex index 85038e1..021e9d0 100644 --- a/doc/SSO.tex +++ b/doc/SSO.tex @@ -30,15 +30,29 @@ \begin{document} \begin{abstract} -Approved client-server authentication mechanisms are described for the IVOA single-sign-on profile: No Authentication; HTTP Basic Authentication; TLS with passwords; TLS with client certificates; Cookies; Open Authentication; Security Assertion Markup Language; OpenID. Normative rules are given for the implementation of these mechanisms, mainly by reference to pre-existing standards. The Authorization mechanisms are out of the scope of this document. +Approved client-server authentication mechanisms are described for the +IVOA single-sign-on profile: No Authentication; HTTP Basic +Authentication; TLS with passwords; TLS with client certificates; +Cookies; Open Authentication; Security Assertion Markup Language; +OpenID. Normative rules are given for the implementation of these +mechanisms, mainly by reference to pre-existing standards. The +Authorization mechanisms are out of the scope of this document. \end{abstract} - \section*{Acknowledgments} -This document derives from discussions among the Grid and Web Services working-group of IVOA. It is particularly informed by prototypes built by Matthew Graham (Caltech/US-NVO), Paul Harrison (ESO/EuroVO), David Morris (Cambridge/AstroGrid), Raymond Plante (NCSA/US-NVO) Brian Major and Donovan Patrick Dowler (CADC) and Giuliano Taffoni (INAF-VObs.it). -The prior art for the use of proxy certificates comes from the Globus Alliance. -This document has been developed with support from the National Science Foundation's Information Technology Research Program with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC) and from the European Commission's Work programme FP7 via the CoSADIE project and the H2020 via the ASTERICS project. +This document derives from discussions among the Grid and Web Services +working-group of IVOA. It is particularly informed by prototypes built +by Matthew Graham (Caltech/US-NVO), Paul Harrison (ESO/EuroVO), David +Morris (Cambridge/AstroGrid), Raymond Plante (NCSA/US-NVO) Brian Major +and Donovan Patrick Dowler (CADC) and Giuliano Taffoni (INAF-VObs.it). +The prior art for the use of proxy certificates comes from the Globus +Alliance. +This document has been developed with support from the National Science +Foundation's Information Technology Research Program with The Johns +Hopkins University, from the UK Particle Physics and Astronomy Research +Council (PPARC) and from the European Commission's Work programme FP7 +via the CoSADIE project and the H2020 via the ASTERICS project. \section*{Conformance-related definitions} @@ -56,8 +70,29 @@ \section*{Conformance-related definitions} \section{Introduction} -IVOA's single-sign-on architecture is a system in which users assign cryptographic credentials to user agents so that the agents may act with the user's identity and access rights. This standard describes how agents use those credentials to authenticate the user's identity in requests to services. This standard describes also the authentication mechanism of an application or a service making a call (on behalf of someone or something else) to an API or to another service. -This document describes how clients can discover and use authentication mechansims supported by a service, and how services advertise their support of those authentication mechanisms. Additionally, it conveys a {\em profile} of existing security standards; that is, it describes how an existing standard should be applied in an IVOA application to support single sign-on capabilities in the IVOA. In the following sections, we make specific references to details spelled out in these standards. For the purposes of validating against this standard, those referenced documents should be consulted for a full explanation of those details. Each major section is concluded by a Commentary subsection that provides some explanations of the detailed terms and concepts being referred to. The Commentary subsection may also provide recommended scenarios for how this specification might actually be realised. Note that the statements in the Commentary subsections are non-normative and should not be considered part of precise specification; nevertheless, they are indicative of the intended spirit of this document. +IVOA's single-sign-on architecture is a system in which users assign +cryptographic credentials to user agents so that the agents may act with +the user's identity and access rights. This standard describes how +agents use those credentials to authenticate the user's identity in +requests to services. This standard describes also the authentication +mechanism of an application or a service making a call (on behalf of +someone or something else) to an API or to another service. +This document describes how clients can discover and use authentication +mechansims supported by a service, and how services advertise their +support of those authentication mechanisms. Additionally, it conveys a +{\em profile} of existing security standards; that is, it describes how +an existing standard should be applied in an IVOA application to support +single sign-on capabilities in the IVOA. In the following sections, we +make specific references to details spelled out in these standards. For +the purposes of validating against this standard, those referenced +documents should be consulted for a full explanation of those details. +Each major section is concluded by a Commentary subsection that provides +some explanations of the detailed terms and concepts being referred to. +The Commentary subsection may also provide recommended scenarios for how +this specification might actually be realised. Note that the statements +in the Commentary subsections are non-normative and should not be +considered part of precise specification; nevertheless, they are +indicative of the intended spirit of this document. \subsection{Role within the VO Architecture} @@ -80,17 +115,31 @@ \subsection{Role within the VO Architecture} \section{Authentication Discovery} -Of the authentication mechanisms listed in section \ref{sec:authentication-mechanisms}, Authentication Mechanisms, some of them can be used exactly as their associated specifications dictate, including how to discover their support. Some of them are intended to be used in an HTTP browser environment, and thus discovery is performed interactively by end users. However, to support non-browser clients (standalone applications and command line tools), the follow procedures can be used to programmatically and interoperabily discover and use the associated authentication mechansim. These procedures are extensions to the existing standards and are built upon HTTP standards themselves. +Of the authentication mechanisms listed in section +\ref{sec:authentication-mechanisms}, Authentication Mechanisms, some of +them can be used exactly as their associated specifications dictate, +including how to discover their support. Some of them are intended to +be used in an HTTP browser environment, and thus discovery is performed +interactively by end users. However, to support non-browser clients +(standalone applications and command line tools), the follow procedures +can be used to programmatically and interoperabily discover and use the +associated authentication mechansim. These procedures are extensions to +the existing standards and are built upon HTTP standards themselves. \subsection{IVOA Challenges} -Services that support one of the approved authentication mechanisms may advertise this through the use of \emph{www-authenticate} HTTP response headers, as defined by \citep{std:RFC7235}. The basic form of this header is: +Services that support one of the approved authentication mechanisms may +advertise this through the use of \emph{www-authenticate} HTTP response +headers, as defined by \citep{std:RFC7235}. The basic form of this +header is: \begin{verbatim} www-authenticate: {auth-scheme} {scheme-specific-params} \end{verbatim} -Where \emph{auth-scheme} is a reference to the authentication mechanism, and \emph{scheme-specific-params} conveys service-specific details on the use of the identified authentication mechansim. +Where \emph{auth-scheme} is a reference to the authentication mechanism, +and \emph{scheme-specific-params} conveys service-specific details on +the use of the identified authentication mechansim. For example: @@ -98,28 +147,61 @@ \subsection{IVOA Challenges} www-authenticate: ivoa_bearer standard_id="ivo://ivoa.net/sso#tls-with-password", access_url="https://example.org/login" \end{verbatim} -As seen above, the \emph{scheme-specific-params} contains two standard parameters: +As seen above, the \emph{scheme-specific-params} contains two standard +parameters: \begin{itemize} -\item{\emph{standard\_id}} - Describes how to obtain the credentials, and refers to one of the authentication mechanisms outlined in this document. Clients can obtain tokens according to the rules for that standard ID. -\item{\emph{access\_url}} - Describes where to obtain the credentials. It is the URL to use in the process. +\item{\emph{standard\_id}} - Describes how to obtain the credentials, +and refers to one of the authentication mechanisms outlined in this +document. Clients can obtain tokens according to the rules for that +standard ID. +\item{\emph{access\_url}} - Describes where to obtain the credentials. +It is the URL to use in the process. \end{itemize} -The list of challenges and their meanings that are recognized by the IVOA are described below. Multiple chanllenges may be in a service's response. Clients can choose whichever one they understand or prefer. - -\textbf{Bearer} - The OAuth2 \citep{std:RFC6749} challenge for a Bearer token. It means one can autheticate with a Bearer token, but does not communicate the details of how such tokens can be obtained. - -\textbf{ivoa_bearer} - The ivoa_bearer challenge also means that one can authticate with an OAuth2 Bearer token, but will also include details on obtaining such tokens through the two parameters, \emph{standard\id}, and \emph{access\. - -\textbf{ivoa_x509} - The ivoa_x509 challenge is an indication that you can authenticate with an X.509 client certificate (including self-signed proxy certificates). There are two variants: one with the two parameters, \emph{standard\id}, and \emph{access\}, and one without. The one with parameters tells the client they can get an acceptable client cert via the described mechanism. (For sites that provide their own cert certificate authority.) The second, without params, says that the service accepts client certificates from external certificate authorities. - -\textbf{ivoa_cookie} - The ivoa_cookie challenge also means that one can authticate with an HTTP Cookie, and may also include details on obtaining cookies through the two parameters, \emph{standard\id}, and \emph{access\. +The list of challenges and their meanings that are recognized by the +IVOA are described below. Multiple chanllenges may be in a service's +response. Clients can choose whichever one they understand or prefer. + +\textbf{Bearer} - The OAuth2 \citep{std:RFC6749} challenge for a Bearer +token. It means one can autheticate with a Bearer token, but does not +communicate the details of how such tokens can be obtained. + +\textbf{ivoa_bearer} - The ivoa_bearer challenge also means that one can +authticate with an OAuth2 Bearer token, but will also include details on +obtaining such tokens through the two parameters, \emph{standard\id}, +and \emph{access\. + +\textbf{ivoa_x509} - The ivoa_x509 challenge is an indication that you +can authenticate with an X.509 client certificate (including self-signed +proxy certificates). There are two variants: one with the two +parameters, \emph{standard\id}, and \emph{access\}, and one without. The +one with parameters tells the client they can get an acceptable client +cert via the described mechanism. (For sites that provide their own cert +certificate authority.) The second, without params, says that the +service accepts client certificates from external certificate +authorities. + +\textbf{ivoa_cookie} - The ivoa_cookie challenge also means that one can +authticate with an HTTP Cookie, and may also include details on +obtaining cookies through the two parameters, \emph{standard\id}, and +\emph{access\. \subsection{Bootstrapping} -How does a client start and how does a service signal that there is \emph{optional}, \emph{required}, or \emph{no} authentication? First, it must be noted that the above www-authenticate challenges can be returned in any response, but typically in 200, 401, or 403. And it must be emphasized that any endpoint can respond with those challenges if something changes. (For example, a token expires, or an attempt to access a protected resource is made.) +How does a client start and how does a service signal that there is +\emph{optional}, \emph{required}, or \emph{no} authentication? First, i + must be noted that the above www-authenticate challenges can be + returned in any response, but typically in 200, 401, or 403. And it + must be emphasized that any endpoint can respond with those challenges + if something changes. (For example, a token expires, or an attempt to + access a protected resource is made.) -For clients to initially find the level of authentication (to bootstrap), they can make anonymous HTTP GET or HTTP HEAD requests to the service's /capabilities endpoint. (See VO Support Interfaces (VOSI) (\citep{2017ivoa.spec.0524G}.) Responses from this call to /capabilities include: +For clients to initially find the level of authentication (to +bootstrap), they can make anonymous HTTP GET or HTTP HEAD requests to +the service's /capabilities endpoint. (See VO Support Interfaces (VOSI) +(\citep{2017ivoa.spec.0524G}.) Responses from this call to /capabilities +include: \begin{itemize} \item{\emph{200}} with no www-authenticate headers: anonymous access only (no authentication) @@ -127,37 +209,60 @@ \subsection{Bootstrapping} \item{\emph{401}} with www-authenticate headers: authentication required \end{itemize} -[Editor's note: two changes to VOSI are required: 1) VOSI augmented to require http HEAD support for /capabilities endpoints, and 2) Modify VOSI to allow /capabilities to respond with 401 (or 403) (also affects TAP 1.1 sec 2; & others?)] +[Editor's note: two changes to VOSI are required: 1) VOSI augmented to +require http HEAD support for /capabilities endpoints, and 2) Modify +VOSI to allow /capabilities to respond with 401 (or 403) (also affects +TAP 1.1 sec 2; & others?)] \subsection{Checking Authentication} -Clients can also check current credentials with an HTTP HEAD call to /capabilities and then look for the header \emph{x-vo-authenticated} in the response. If present, it means that the service recognized it as an authenticated call. The value of this header should identify the user, such as the user's username, or X.509 distinguished name. The scope of the uniqueness of this value is undefined. +Clients can also check current credentials with an HTTP HEAD call to +/capabilities and then look for the header \emph{x-vo-authenticated} in +the response. If present, it means that the service recognized it as an +authenticated call. The value of this header should identify the user, +such as the user's username, or X.509 distinguished name. The scope of +the uniqueness of this value is undefined. -Services may choose to include the x-vo-authenticated header in all requests (not just to /capabilities) made where user authentication was successful. +Services may choose to include the x-vo-authenticated header in all +requests (not just to /capabilities) made where user authentication was +successful. \subsection{SecurityMethod} [Editor's note: Should this section remain?] -When a service is registered in an IVOA registry, that service's resource document MAY include metadata expressing conformance to one or more of the authentication mechanisms approved in the IVOA SSO profile. Such a service MUST implement those mechanisms as described in this document, and clients of the service MUST participate in the mechanism when calling the service. If a service does not provide any SSO specification it is assumed that no authentication is required. +When a service is registered in an IVOA registry, that service's +resource document MAY include metadata expressing conformance to one or +more of the authentication mechanisms approved in the IVOA SSO profile. +Such a service MUST implement those mechanisms as described in this +document, and clients of the service MUST participate in the mechanism +when calling the service. If a service does not provide any SSO +specification it is assumed that no authentication is required. The registration of the service interface MAY contain an XML element of type \xmlel{SecurityMethod} as specified in the XML schema for -VOResource \citep{2018ivoa.spec.0625P}. The value of this element distinguishes the -authentication mechanism using the values stated in the sections below. -Services registered without the metadata alluded to above need not -support any authentication mechanism. If they do require authentication, -they MAY use either the IVOA-standard mechanisms or others that are not -IVOA standards, but they MUST specify a \xmlel{SecurityMethod} element. +VOResource \citep{2018ivoa.spec.0625P}. The value of this element +distinguishes the authentication mechanism using the values stated in +the sections below. Services registered without the metadata alluded to +above need not support any authentication mechanism. If they do require +authentication, they MAY use either the IVOA-standard mechanisms or +others that are not IVOA standards, but they MUST specify a +\xmlel{SecurityMethod} element. \subsection{Commentary} -The IVOA SSO profile allows the development of a ``realm'' of interoperable services and clients. -Service providers opt in to this realm by implementing this current standard and by registering accordingly in the IVOA registry. -This allows clients to discover a secured service through the registry and to be able to use it without +The IVOA SSO profile allows the development of a ``realm'' of +interoperable services and clients. +Service providers opt in to this realm by implementing this current +standard and by registering accordingly in the IVOA registry. +This allows clients to discover a secured service through the registry +and to be able to use it without being customized for the details of the specific service. -Services within the Virtual Observatory that are not intended to be widely interoperable need not opt in to the SSO realm. -In particular, ``private'' services, accessed by web browsers and protected by passwords, are allowed. -However, these private services SHOULD be reworked to follow the IVOA standard if they are later promoted to a wider audience. +Services within the Virtual Observatory that are not intended to be +widely interoperable need not opt in to the SSO realm. +In particular, ``private'' services, accessed by web browsers and +protected by passwords, are allowed. +However, these private services SHOULD be reworked to follow the IVOA +standard if they are later promoted to a wider audience. An example of a registration for a secured interface follows. \begin{lstlisting}[language=XML] @@ -180,15 +285,16 @@ \subsection{Commentary} \end{lstlisting} -The order of the \xmlel{securityMethod} elements determines the priority of -the method to use. In the example above, the preferred method to access -the service is {\em SAML}, then {\em cookies}, and finally, if the others are not available, -{\em OpenID}. +The order of the \xmlel{securityMethod} elements determines the priority +of the method to use. In the example above, the preferred method to +access the service is {\em SAML}, then {\em cookies}, and finally, if +the others are not available, {\em OpenID}. \section{Authentication Mechanisms} \label{sec:authentication-mechanisms} -The following authentication mechanisms are approved for use in the SSO profile. +The following authentication mechanisms are approved for use in the SSO +profile. \begin{itemize} \item No authentication required. \item HTTP Basic Authentication @@ -200,17 +306,24 @@ \section{Authentication Mechanisms} \item OpenID \end{itemize} -The mechanism is associated with the interface provided by the service and registered in the IVOA registry. +The mechanism is associated with the interface provided by the service +and registered in the IVOA registry. -Services that are registered with a IVOA registry as having a {\em WebService} type interface (as -described in the VOResource document) SHALL support OAuth, or SHALL support cookies or SHALL support TLS with client +Services that are registered with a IVOA registry as having a +{\em WebService} type interface (as +described in the VOResource document) SHALL support OAuth, or SHALL +support cookies or SHALL support TLS with client certificates or SHALL require no authentication. -Interfaces by which a user logs in to the SSO system SHALL support either -TLS with client certificates, or TLS with passwords, or SAML or a combination of them. +Interfaces by which a user logs in to the SSO system SHALL support +either +TLS with client certificates, or TLS with passwords, or SAML or a +combination of them. -\subsection{List of approved authentication mechanisms and the corresponding securityMethod} +\subsection{List of approved authentication mechanisms and the +corresponding securityMethod} -The approved authentication mechanisms and the corresponding \xmlel{securityMethod} to implement is +The approved authentication mechanisms and the corresponding +\xmlel{securityMethod} to implement is listed in the table below. \begin{table}[th] @@ -232,60 +345,84 @@ \subsection{List of approved authentication mechanisms and the corresponding sec \section{HTTP Basic Authentication} \subsection{Requirements} -Services using HTTP basic authentication SHALL use the authentication mechanism described in the RFC7235 \citep{std:RFC7235} +Services using HTTP basic authentication SHALL use the authentication +mechanism described in the RFC7235 \citep{std:RFC7235} that updates RFC2617 \citep{std:RFC2617}. -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#BasicAA} \subsection{Commentary} -HTTP provides a simple challenge-response authentication framework that can be used by a server to challenge -a client request and by a client to provide authentication information. -The HTTP authentication framework does not define a single mechanism for maintaining the confidentiality of credentials. -HTTP depends on the security properties of the underlying transport or session-level connection to provide -confidential transmission of header fields. Connection secured with TLS are RECOMMENDED prior to exchanging any credentials. - -The ``HTTP basic authentication'' SHOULD be used with particular attention as sensible -information (password) are sent over the wire in base64 encoding (which can be easily converted to plaintext) exposing +HTTP provides a simple challenge-response authentication framework that +can be used by a server to challenge +a client request and by a client to provide authentication +information. +The HTTP authentication framework does not define a single mechanism for +maintaining the confidentiality of credentials. +HTTP depends on the security properties of the underlying transport or +session-level connection to provide +confidential transmission of header fields. Connection secured with +TLS are RECOMMENDED prior to exchanging any credentials. + +The ``HTTP basic authentication'' SHOULD be used with particular +attention as sensible +information (password) are sent over the wire in base64 encoding (which +can be easily converted to plaintext) exposing the user to the possibility her credentials to be stolen. \section{Details of TLS} \subsection{Requirements} -Services using Transport Layer Security (TLS) SHALL do so according to the TLS v1.2 standard RFC5246 \citep{std:RFC5246}. +Services using Transport Layer Security (TLS) SHALL do so according to +the TLS v1.2 standard RFC5246 \citep{std:RFC5246}. \subsection{Commentary} -TLS supersedes the Secure Sockets Layer that is an outdated cryptographic protocol. -TLS v1.0 was based on SSL v3.0; the current version of TLS is V1.2 described in by \citet{std:RFC5246}. +TLS supersedes the Secure Sockets Layer that is an outdated +cryptographic protocol. +TLS v1.0 was based on SSL v3.0; the current version of TLS is V1.2 +described in by \citet{std:RFC5246}. TLS v1.2 is backwards compatible with TLS v1.0, TLS v1.1 and SSL v3.0. -``TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use compatible ClientHello messages; -thus, supporting all of them is relatively easy.[...] TLS 1.2 clients that wish to support SSL 2.0 servers MUST -send version 2.0 CLIENT-HELLO messages defined in SSL2.'' \citep{std:RFC5246}. +``TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use +compatible ClientHello messages; +thus, supporting all of them is relatively easy.[...] TLS 1.2 clients +that wish to support SSL 2.0 servers MUST +send version 2.0 CLIENT-HELLO messages defined in SSL2.'' +\citep{std:RFC5246}. \section{Details of TLS-with-client-certificate} \subsection{Requirements} -Certificates SHALL be transmitted and checked according to the TLS v1.2 standard RFC5246. +Certificates SHALL be transmitted and checked according to the TLS v1.2 +standard RFC5246. -Services implementing TLS MUST support certificate chains including proxy certificates according to RFC6818 \citep{std:RFC6818}. +Services implementing TLS MUST support certificate chains including +proxy certificates according to RFC6818 \citep{std:RFC6818}. -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#tls-with-certificate} \subsection{Commentary} -When Mutual Certificate Authentication is configured for REST services, both the client and the service perform +When Mutual Certificate Authentication is configured for REST services, +both the client and the service perform identity verification or authentication through X.509 certificates. -The client authenticates the service during the initial SSL handshake, when the server sends the client a certificate to authenticate itself. +The client authenticates the service during the initial SSL handshake, +when the server sends the client a certificate to authenticate itself. \section{Details of TLS-with-password} \subsection{Requirements} -The username and password SHALL be passed in the message protected by the TLS mechanism, and, with a valid password credential, a Bearer token SHALL be returned, also protected by the TLS mechanism. +The username and password SHALL be passed in the message protected by +the TLS mechanism, and, with a valid password credential, a Bearer token +SHALL be returned, also protected by the TLS mechanism. The HTTP POST form parameters to be used in tls-with-password are: \paragraph{username} - The username to use for login \paragraph{password} - The password to use for login -When valid credentials (username and password) are used, the service responses with a 200 response code and uses the \emph{x-vo-bearer} response header to return an OAuth2 Bearer token. For example: +When valid credentials (username and password) are used, the service +responses with a 200 response code and uses the \emph{x-vo-bearer} +response header to return an OAuth2 Bearer token. For example: \begin{verbatim} curl -d 'username={userid}' -d 'password={password}' https://example.org/login @@ -294,7 +431,8 @@ \subsection{Requirements} < x-vo-bearer: {token} \end{verbatim} -When invalid credentials are used, the service resonsds with a 401 response code and optional message in the response body. For example, +When invalid credentials are used, the service resonsds with a 401 +response code and optional message in the response body. For example, \begin{verbatim} curl -d 'username={userid}' -d 'password={password}' https://example.org/login @@ -302,31 +440,41 @@ \subsection{Requirements} invalid username or password \end{verbatim} -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#tls-with-password} \subsection{Commentary} -``HTTP basic authentication'' passes the user-name and password in the HTTP headers, -assuming that the credentials are not a natural part of the message body. -This standard applies the TLS-with-Password mechanism only to the special case of logging in to the SSO realm. -Hence, the user-name and password are logically part of the message body, not the message header. +``HTTP basic authentication'' passes the user-name and password in the +HTTP headers, +assuming that the credentials are not a natural part of the message +body. This standard applies the TLS-with-Password mechanism only to the +special case of logging in to the SSO realm. +Hence, the user-name and password are logically part of the message +body, not the message header. \section{The use of Cookies} \subsection{Requirements} -Cookie-Based Authentication uses server side cookies to authenticate the user on every request. -The way to manage cookies for authentication is described in RFC6265 \citep{std:RFC6265}. +Cookie-Based Authentication uses server side cookies to authenticate the +user on every request. +The way to manage cookies for authentication is described in RFC6265 +\citep{std:RFC6265}. -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#cookie} \subsection{Commentary} -RESTful web services MAY support session-based authentication, either by establishing a session token via a POST or +RESTful web services MAY support session-based authentication, either +by establishing a session token via a POST or by using an API key as a POST body argument or as a cookie. -User-names, passwords, session tokens, and API keys SHOULD not appear in the URL, -as this can be captured in web server logs, which makes them intrinsically valuable. +User-names, passwords, session tokens, and API keys SHOULD not appear in +the URL, +as this can be captured in web server logs, which makes them +intrinsically valuable. \begin{figure} \centering \includegraphics[width=0.9\textwidth]{SSO_image002.png} @@ -336,26 +484,35 @@ \subsection{Commentary} \section{Details on SAML authentication} \subsection{Requirements} -Services using SAML authentication mechanisms SHALL do so according to the +Services using SAML authentication mechanisms SHALL do so according to +the saml-core-2.0-os OASIS standard \citep{std:SAML}. -SAML includes protocols and protocol bindings and security \citep{std:SAMLB}. +SAML includes protocols and protocol bindings and security +\citep{std:SAMLB}. -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#saml2.0} \subsection{Commentary} -SAML presumes two primary roles in any transaction: the organisation where the identity is established, +SAML presumes two primary roles in any transaction: the organisation +where the identity is established, known as the Identity Provider (``IdP''), or Asserting Party (``AP''); -and the organisation which (for this transaction) wants to use this identity, known as the Service Provider (``SP''), +and the organisation which (for this transaction) wants to use this +identity, known as the Service Provider (``SP''), or Relying Party (``RP''). A user attempts to access an application with the Service Provider. -The SP needs to establish the identity of this user, and so sends an authentication request to the Identity Provider. - -The user authenticates with the IdP (IdP is taking care of the authentication mechanisms and protocols e.g. Kerberos, ldap etc.) so the IdP can send back an `Assertion' to the SP. -Now the SP knows who the user is, and can process that user accordingly (see Fig.~\ref{fig:saml}). +The SP needs to establish the identity of this user, and so sends an +authentication request to the Identity Provider. + +The user authenticates with the IdP (IdP is taking care of the +authentication mechanisms and protocols e.g. Kerberos, ldap etc.) so the +IdP can send back an `Assertion' to the SP. +Now the SP knows who the user is, and can process that user accordingly +(see Fig.~\ref{fig:saml}). \begin{figure} \centering \includegraphics[width=0.9\textwidth]{SSO_image003.png} @@ -363,16 +520,20 @@ \subsection{Commentary} \label{fig:oauth} \end{figure} -SAML2.0 protocol allows also to implement authentication service discovery mechanisms. SAML2.0 defines a browser-based protocol -by which a centralized discovery service can provide a requesting service provider with the unique identifier of an +SAML2.0 protocol allows also to implement authentication service +discovery mechanisms. SAML2.0 defines a browser-based protocol +by which a centralized discovery service can provide a requesting +service provider with the unique identifier of an IdP that can authenticate the user. \section{Details on OAuth} \subsection{Requirements} -Services using OAuth authentication mechanisms SHALL do so according to the RFC6749 \citep{std:RFC6749}. +Services using OAuth authentication mechanisms SHALL do so according to +the RFC6749 \citep{std:RFC6749}. -Clients perform authentication with OAuth Bearer tokens using the \emph{authorization} header. For example: +Clients perform authentication with OAuth Bearer tokens using the +\emph{authorization} header. For example: \begin{verbatim} curl -H 'authorization: Bearer {token}' https://example.org/tap @@ -380,71 +541,103 @@ \subsection{Requirements} < x-vo-authenticated: {username} \end{verbatim} -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#OAuth} \subsection{Commentary} -Open Authentication 2.0 (also in conjunction with OpenID Connect) is actually the adopted standard +Open Authentication 2.0 (also in conjunction with OpenID Connect) is +actually the adopted standard to handle identity in the framework of RESTful web services. -OAuth is used when an application is making a request on behalf of a user. +OAuth is used when an application is making a request on behalf of a +user. -OAuth introduces the notion of an `authorization token', a `refresh token' and Authorization Service (AS). -The `authorization' token states that the client application has the right to access services on the server (see Fig.~\ref{fig:oauth}). -However, it does not supersede any access control decisions that the server-side application might make. +OAuth introduces the notion of an `authorization token', a `refresh +token' and Authorization Service (AS). +The `authorization' token states that the client application has the +right to access services on the server (see Fig.~\ref{fig:oauth}). +However, it does not supersede any access control decisions that the +server-side application might make. -OAuth protocol can be implemented to delegate credential from an application to another. +OAuth protocol can be implemented to delegate credential from an +application to another. \section{Details on OpenID} \subsection{Requirements} -Services using OpenID authentication mechanisms SHALL do so according to the OpenID Foundation standards \citep{std:openid} +Services using OpenID authentication mechanisms SHALL do so according to +the OpenID Foundation standards \citep{std:openid} -Interfaces using this mechanism SHALL be registered with the security method +Interfaces using this mechanism SHALL be registered with the security +method \texttt{ivo://ivoa.net/sso\#OpenID} \subsection{Commentary} -OpenID is an open and decentralized authentication and identity system. OpenID relying parties do not manage end user credentials -such as passwords or any other sensitive information which makes authentication and identity management much simpler and secure. -In a RESTful environment OpenID Connect \citep{std:openidconnect} is commonly adopted as authentication solution. ``OpenID Connect is a simple identity -layer on top of the OAuth 2.0 protocol, which allows computing clients to verify the identity of an end-user based on the authentication - performed by an authorization server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner.'' \citep{std:openid}. +OpenID is an open and decentralized authentication and identity system. +OpenID relying parties do not manage end user credentials +such as passwords or any other sensitive information which makes +authentication and identity management much simpler and secure. +In a RESTful environment OpenID Connect \citep{std:openidconnect} is +commonly adopted as authentication solution. ``OpenID Connect is a +simple identity +layer on top of the OAuth 2.0 protocol, which allows computing clients +to verify the identity of an end-user based on the authentication + performed by an authorization server, as well as to obtain basic + profile information about the end-user in an interoperable and + REST-like manner.'' \citep{std:openid}. \section{Conclusions} -This document presents a list of security standards that may be implemented when developing a service that requires authentication. -The list includes the most frequently used standards at the time this document has been produced. +This document presents a list of security standards that may be +implemented when developing a service that requires authentication. +The list includes the most frequently used standards at the time this +document has been produced. In this document we are presenting two types of SSO protocols: ``local'' and ``federated''. -Local SSO provides solutions for keeping a repository of user-names and passwords -that could be used transparently across several internal applications but it is local to one domain/service. - -Federated identity means linking and using the electronic identities a user has across several identity management systems. -In simpler terms, a service does not necessarily need to obtain and store users credentials in order to authenticate them. Instead, the service (or the application) can use an identity management system that is already storing a user's electronic identity -to authenticate the users given, of course, that the application trusts that identity management system. -Federated identities are convenient for users, since they don't have to keep a set of user-names and passwords for every single application that they use and for service providers that do not need to store and manage credentials. - -Local SSO is managed by the following protocols: HTTP Basic Authentication, Transport Layer Security (TLS) with passwords, cookies -OAuth, SAML, OpenID and Transport Layer Security (TLS) with client certificates (thanks to the CA trust) are protocol that +Local SSO provides solutions for keeping a repository of user-names +and passwords that could be used transparently across several internal +applications but it is local to one domain/service. + +Federated identity means linking and using the electronic identities a +user has across several identity management systems. +In simpler terms, a service does not necessarily need to obtain and +store users credentials in order to authenticate them. Instead, the +service (or the application) can use an identity management system that +is already storing a user's electronic identity +to authenticate the users given, of course, that the application trusts +that identity management system. +Federated identities are convenient for users, since they don't have to +keep a set of user-names and passwords for every single application that +they use and for service providers that do not need to store and manage +credentials. + +Local SSO is managed by the following protocols: HTTP Basic +Authentication, Transport Layer Security (TLS) with passwords, cookies +OAuth, SAML, OpenID and Transport Layer Security (TLS) with client +certificates (thanks to the CA trust) are protocol that allow to implement federated SSO. -The choice the authentication to use is related to the project/service requirements, we suggest at least to implement -a local authentication based on Transport Layer Security (TLS) with passwords, that allows a reasonable security +The choice the authentication to use is related to the project/service +requirements, we suggest at least to implement +a local authentication based on Transport Layer Security (TLS) with +passwords, that allows a reasonable security framework for exchanging authentication tokens. -More complex projects/services that need to offer resources to large communities should prefer federated identities. -For example SAML2.0 is the protocol used to build the EduGain World wide identity federation for education and research. - - +More complex projects/services that need to offer resources to large +communities should prefer federated identities. +For example SAML2.0 is the protocol used to build the EduGain World wide +identity federation for education and research. \appendix \section{VOResource SecurityMethod} -This Appendix presents an extract of the VOResource Description XML schema. -Here we present the part of the schema regarding the \xmlel{SecurityMethod} element -to facilitate the reader identify the relevant schema sections in the VOResource Description. - +This Appendix presents an extract of the VOResource Description XML +schema. Here we present the part of the schema regarding the +\xmlel{SecurityMethod} element +to facilitate the reader identify the relevant schema sections in the +VOResource Description. \begin{lstlisting}[language=xml,basicstyle=\footnotesize]