# Diff of /trunk/projects/grid/sso/doc/SSOAuthMech.tex

revision 3278 by taffoni, Wed Apr 6 17:23:23 2016 UTC revision 3279 by taffoni, Thu Apr 7 11:17:53 2016 UTC
# Line 12  Line 12
12  \ivoagroup{http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices}  \ivoagroup{http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices}
13
14  %\author[????URL????]{http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices}  %\author[????URL????]{http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices}
15  \author{Brian Majour, Guy Rixon, Andre\e Schaaff, Giuliano Taffoni}  \author{Brian Majour, Guy Rixon, Andr\e Schaaff, Giuliano Taffoni}
16
17  \editor{Giuliano Taffoni}  \editor{Giuliano Taffoni}
18
# Line 49  Line 49
49
50
51  \section{Introduction}  \section{Introduction}
52  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  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.
53  This document is essentially a {\em profile} against 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. Unfortunately, a reader that is unfamiliar with these external standards might find this specification confusing. To alleviate this problem, 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.  This document is essentially a {\em profile} against 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. Unfortunately, a reader that is unfamiliar with these external standards might find this specification confusing. To alleviate this problem, 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.
54
55  \subsection{Role within the VO Architecture}  \subsection{Role within the VO Architecture}
# Line 77  Line 77
77  When a service is registered in an IVOA registry, that services 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. Is 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 services 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. Is a service does not provide any SSO specification it is assumed that no authentication is required.
78  The registration of the service interface SHALL contain an XML element  The registration of the service interface SHALL contain an XML element
79  of type \xmlel{SecurityMethod} as specified in the XML schema for  of type \xmlel{SecurityMethod} as specified in the XML schema for
80  VOResource \citep{std:VOR}. The value of this element distinguished the  VOResource \citep{std:VOR}. The value of this element distinguishes the
81  authentication mechanism using the values stated in the sections below.  authentication mechanism using the values stated in the sections below.
82  Services registered without the metadata alluded to above need not  Services registered without the metadata alluded to above need not
83  support any authentication mechanism. If they do require authentication,  support any authentication mechanism. If they do require authentication,
# Line 96  Line 96
96
97  An example of a registration for a secured interface follows.  An example of a registration for a secured interface follows.
98  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
99  <interface xmlns:vs:=''ivo://www.ivoa.net/xml/VODataService/v1.0''    <interface xmlns:vs='ivo://www.ivoa.net/xml/VODataService/v1.0'
100          xsi:type=''vs:ParamHTTP''>          xsi:type='vs:ParamHTTP'>
101          <accessURL>http://some.where/some/thing</accessURL>          <accessURL>http://some.where/some/thing</accessURL>
102          <securityMethod>ivo://ivoa.net/sso#saml2.0</securityMethod>          <securityMethod>ivo://ivoa.net/sso#saml2.0</securityMethod>
103  </interface>  </interface>
# Line 105  Line 105
105
106  More than one {\xmlel securityMethod} can be specified:  More than one {\xmlel securityMethod} can be specified:
107  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
108  <interface xmlns:vs:=''ivo://www.ivoa.net/xml/VODataService/v1.0''    <interface xmlns:vs='ivo://www.ivoa.net/xml/VODataService/v1.0'
109          xsi:type=''vs:ParamHTTP''>          xsi:type='vs:ParamHTTP'>
110          <accessURL>http://some.where/some/thing</accessURL>          <accessURL>http://some.where/some/thing</accessURL>
111          <securityMethod>ivo://ivoa.net/sso#saml2.0</securityMethod>          <securityMethod>ivo://ivoa.net/sso#saml2.0</securityMethod>
# Line 115  Line 115
115  \end{lstlisting}  \end{lstlisting}
116
117  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 order of the \xmlel{securityMethod} elements determines the priority of the method to use, in the example above the preferred method to access
118  the service is {\em SAML}, than {cookies} and finally if the other are not available OpenID.  the service is {\em SAML}, than {\em cookies} and finally if the other are not available OpenID.
119
120  \section{Approved authentication mechanisms}  \section{Approved authentication mechanisms}
121
# Line 137  Line 137
137  \textbf{SSO mechanism}&\textbf{\xmlel{<securityMethod>}}\\ \sptablerule  \textbf{SSO mechanism}&\textbf{\xmlel{<securityMethod>}}\\ \sptablerule
138  No authentication required & none\\  No authentication required & none\\
139   HTTP Basic Authentication &   HTTP Basic Authentication &
140  \xmlel{http//www.w3.org/Protocols/HTTP/ 1.0/spec/html\#BasicAA}\\  \xmlel{https://www.w3.org/Protocols/HTTP/ 1.0/spec/html\#BasicAA}\\
142  TLS with client certificate & \xmlel{ivo://ivoa.net/sso\#tls-with-certificate} \\  TLS with client certificate & \xmlel{ivo://ivoa.net/sso\#tls-with-certificate} \\
# Line 150  Line 150
150  \end{tabular}  \end{tabular}
151  \end{table}  \end{table}
152
153  Services that are registered with a IVOA registry as having a {em WebService} type interface  Services that are registered with a IVOA registry as having a {\em WebService} type interface
154  \citep{ivo:resource} SHALL support OAuth, or SHALL support cookies or SHALL support TLS with client  \citep{ivo:resource} SHALL support OAuth, or SHALL support cookies or SHALL support TLS with client
155  certificates or SHALL require no authentication.  certificates or SHALL require no authentication.
156  Interfaces by which a user logs in to the SSO system SHALL support either  Interfaces by which a user logs in to the SSO system SHALL support either
157  TLS with client certificates, or TLS with passwords, or SAML or a combination of the them  TLS with client certificates, or TLS with passwords, or SAML or a combination of  them
158
159  \section{HTTP Basic Authentication}  \section{HTTP Basic Authentication}
160  \subsection{Requirements}  \subsection{Requirements}
# Line 162  Line 162
163  Interfaces using this mechanism SHALL be be registered with the security method  Interfaces using this mechanism SHALL be be registered with the security method
164
165   \texttt{http://www.w3.org/Protocols/HTTP/1.0/spec/html\#BasicAA}   \texttt{https://www.w3.org/Protocols/HTTP/1.0/spec/html\#BasicAA}
166
167  \subsection{Commentary}  \subsection{Commentary}
168  HTTP provides a simple challenge-response authentication framework that can be used by a server to challenge  HTTP provides a simple challenge-response authentication framework that can be used by a server to challenge
# Line 189  Line 189
189
190  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}.
191
192  Interfaces using this mechanism SHALL be be registered with the security method \texttt{ivo://ivoa.net/sso\#tls-with-client-certificate}.  Interfaces using this mechanism SHALL be be registered with the security method
193
194    \texttt{ivo://ivoa.net/sso\#tls-with-certificate}.
195
196  \subsection{Commentary}  \subsection{Commentary}
197  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
# Line 202  Line 204
204  The user-name and password SHALL be passed in the message protected by the TLS mechanism,  The user-name and password SHALL be passed in the message protected by the TLS mechanism,
205  not as part of the mechanism itself. The HTTP basic authentication'' should be used with particular attention.  not as part of the mechanism itself. The HTTP basic authentication'' should be used with particular attention.
206
207  Interfaces using this mechanism SHALL be be registered with the security method \texttt{ivo://ivoa.net/sso\#tls-with-password}.  Interfaces using this mechanism SHALL be be registered with the security method
208
210
211  \subsection{Commentary}  \subsection{Commentary}
212  HTTP basic authentication'' passes the user-name and password in the HTTP headers,  HTTP basic authentication'' passes the user-name and password in the HTTP headers,
# Line 215  Line 219
219  Cookie-Based Authentication uses server side cookies to authenticate the user on every request.  Cookie-Based Authentication uses server side cookies to authenticate the user on every request.
220  The way to manage  cookies for authentication is described in RFC6265 \citep{std:RFC6265}.  The way to manage  cookies for authentication is described in RFC6265 \citep{std:RFC6265}.
221
222    Interfaces using this mechanism SHALL be be registered with the security method
223
225
226
227  \subsection{Commentary}  \subsection{Commentary}
228  RESTful web services should use session-based authentication, either by establishing a session token via a POST or  RESTful web services should use session-based authentication, either by establishing a session token via a POST or
229  by using an API key as a POST body argument or as a cookie.  by using an API key as a POST body argument or as a cookie.
# Line 233  Line 242
242  saml-core-2.0-os OASIS standard \citep{std:SAML}.  saml-core-2.0-os OASIS standard \citep{std:SAML}.
243  SAML includes protocols and protocol bindings and security \citep{std:SAMLB}.  SAML includes protocols and protocol bindings and security \citep{std:SAMLB}.
244
245    Interfaces using this mechanism SHALL be be registered with the security method
246
247    \texttt{ivo://ivoa.net/sso\#saml2.0}.
248
249
250  \subsection{Commentary}  \subsection{Commentary}
251  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,
252  known as the Identity Provider (IdP''), or Asserting Party (AP'');  known as the Identity Provider (IdP''), or Asserting Party (AP'');
# Line 242  Line 256
256  A user attempts to access an application with the Service Provider.  A user attempts to access an application with the Service Provider.
257  The SP needs to establish the identity of this user, and so sends an authentication request to the Identity Provider.  The SP needs to establish the identity of this user, and so sends an authentication request to the Identity Provider.
258
259  The user authenticate 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.  The user authenticate 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.
260  Now the SP knows who the user is, and can process that user accordingly (see Fig.~\ref{fig:saml}).  Now the SP knows who the user is, and can process that user accordingly (see Fig.~\ref{fig:saml}).
261  \begin{figure}  \begin{figure}
262  \centering  \centering
# Line 251  Line 265
265  \label{fig:oauth}  \label{fig:oauth}
266  \end{figure}  \end{figure}
267
268    SAML2.0 protocol allows also to implement authentication service discovery mechanisms. SAML2.0  defines a browser-based protocol
269    by which a centralized discovery service can provide a requesting service provider with the unique identifier of an
270    identity provider that can authenticate a principal. In this way
271
272
SAML2.0 allow also to service discovery mechanisms

273  \section{Details on OAuth}  \section{Details on OAuth}
274  \subsection{Requirements}  \subsection{Requirements}
275  Services using OAuth authentication mechanisms SHALL do so according to the RFC6749 \citep{std:RFC6742}.  Services using OAuth authentication mechanisms SHALL do so according to the RFC6749 \citep{std:RFC6742}.
276
277    Interfaces using this mechanism SHALL be be registered with the security method
278
279    \texttt{ivo://ivoa.net/sso\#OAuth}.
280
281
282  \subsection{Commentary}  \subsection{Commentary}
283  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
284  to handle identity in the framework of RESTful web services.  to handle identity in the framework of RESTful web services.
# Line 274  Line 294
294  \subsection{Requirements}  \subsection{Requirements}
295  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}
296
297    Interfaces using this mechanism SHALL be be registered with the security method
298
299    \texttt{ivo://ivoa.net/sso\#OpenID}.
300
301
302  \subsection{Commentary}  \subsection{Commentary}
303  OpenID is an open and decentralized authentication and identity system. OpenID relying parties do not manage end user credentials  OpenID is an open and decentralized authentication and identity system. OpenID relying parties do not manage end user credentials
304  such as passwords or any other sensitive information which makes authentication and identity management much simpler and secure.  such as passwords or any other sensitive information which makes authentication and identity management much simpler and secure.

Legend:
 Removed from v.3278 changed lines Added in v.3279