1=============================
2Single Sign-On and Federation
3=============================
4
5Profile Overview
6================
7
8The service provider has four things to do:
9
10- creating an authentication request
11- sending it to the identity provider
12- receiving an authentication response or an artifact
13- (eventually) checking it against the identity provider
14
15The first two steps are handled with an HTTP redirection or an HTML form;
16typically the user would click on a button, the service provider would then
17create the authentication request and send an HTTP Redirect to the browser.  No
18URL is defined in the specifications for this first step.
19
20The last two steps are handled in the *AssertionConsumerServiceURL*; the user
21will arrive there through an HTTP Redirect or an HTTP POST carrying a piece of
22information from the identity provider.  In case of a redirect, this
23information, called *artifact*, won't be large and will be exchanged with the
24identity provider for a *AuthnResponse*.  An HTTP POST will be able to carry
25much more information and will therefore be able to provide either the
26*artifact* or directly the *AuthnResponse*.
27
28An appropriate metadata snippet would be::
29
30  <?xml version="1.0"?>
31  <EntityDescriptor providerID="service-provider" xmlns="urn:liberty:metadata:2003-08">
32   <SPDescriptor>
33    <AssertionConsumerServiceURL id="AssertionConsumerServiceURL1" isDefault="true">
34     https://service-provider.example.com/liberty-alliance/assertionConsumer
35    </AssertionConsumerServiceURL>
36   </SPDescriptor>
37  </EntityDescriptor>
38
39
40The identity provider has more things to do:
41
42- receiving an authentication request
43- authenticating the user if necessary
44- sending a response to the service provider
45- (eventually) answering a SOAP request with an other response
46
47All but the last one is handled in the *SingleSignOnServiceURL*; the user has
48been redirected there from the service provider with an authentication request
49as URL parameter.  This authentication request is used to decide several things
50(allowed authentication methods for example) and the authentication is done.
51This step is not part of the Liberty protocols, this can be as simple as
52straight HTTP authentication with a username and a password or as complex as a
53Java applet checking a certificate on the client.
54
55Anyway, once the user has been authenticated, an answer must be sent to the
56service provider.  It is actually not a direct communication, the answer
57bounces on the user agent with an HTTP Redirect or by an HTML form pointing to
58the service provider.
59
60The answer may be an *artifact* (available in the query string in case of a
61redirect or in a ``LAREQ`` form field in case of a POST); the user is then
62simply redirected to this URL.  The service provider will then make a SOAP
63request to the *SoapEndpoint* asking for the authentication response matching
64the artifact.
65
66The answer may also be an *authentication response*; since it will be a large
67piece of data it must be passed in an HTML page; an HTML form embedding the
68authentication response.  The user will then submit this form to the service
69provider *AssertionConsumerURL*.
70
71Metadata would be::
72
73  <?xml version="1.0"?>
74  <EntityDescriptor providerID="identity-provider" xmlns="urn:liberty:metadata:2003-08">
75   <IDPDescriptor>
76    <SoapEndpoint>
77     https://identity-provider.example.com/soapEndpoint
78    </SoapEndpoint>
79    <SingleSignOnServiceURL>
80     https://identity-provider.example.com/singleSignOn
81    </SingleSignOnServiceURL>
82   </IDPDescriptor>
83  </EntityDescriptor>
84
85
86Implementing the service provider parts
87=======================================
88
89.. warning:: The source code presented in the "implementing" section has for
90             sole purpose to explain the different steps necessary to implement
91             the profiles; they notably lack proper error checking.  See
92             XXX for details on error checking.
93
94
95Sending the user to the identity provider
96-----------------------------------------
97
98``server`` is a *LassoServer* object as seen earlier (`LassoServer`_) and
99``idpProviderId`` is a string with the identity provider Id (the string must
100match a providerID defined in the metadata file).
101
102::
103
104  LassoLogin *login;
105
106  /* create login object */
107  login = lasso_login_new(server);
108
109
110Select profile to use, HTTP Redirect::
111
112  lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_REDIRECT);
113
114or HTTP POST::
115
116  lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_POST);
117
118
119Parametrize request::
120
121  /* will force authentication on the identity provider */
122  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->ForceAuthn = TRUE;
123
124  /* ask for identity federation */
125  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->NameIDPolicy =
126      strdup(LASSO_LIB_NAME_ID_POLICY_TYPE_FEDERATED);
127
128  /* the user consents with the idea of identity federation */
129  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->consent =
130      strdup(LASSO_LIB_CONSENT_OBTAINED);
131
132(see API reference for other possible values)
133
134
135Create the authentication request::
136
137  lasso_login_build_authn_request_msg(login);
138
139
140An URL is then defined in ``LASSO_PROFILE(login)->msg_url``; the user must be
141redirected to it; for example, in a CGI::
142
143  printf("Location: %s\n", LASSO_PROFILE(login)->msg_url);
144
145
146
147Receiving an answer from the identity provider
148----------------------------------------------
149
150This part is handled on the *AssertionConsumerURL*.
151
152
153Receiving an assertion
154......................
155
156The user has been directed to this URL.  If it was a redirect the query string
157(the part of the URL after the question mark) will hold the artifact and may be
158used to initialize the *LassoLogin* object.
159
160::
161
162  LassoLogin *login;
163
164  login = lasso_login_new(server);
165  lasso_login_init_request(login, query_string, LASSO_HTTP_METHOD_REDIRECT);
166  lasso_login_build_request_msg(login);
167
168If it was a form post it will have a ``LAREQ`` field.
169
170::
171
172  LassoLogin *login;
173
174  login = lasso_login_new(server);
175  lasso_login_init_request(login, lareq_field, LASSO_HTTP_METHOD_POST);
176  lasso_login_build_request_msg(login);
177
178
179The service provider must then check this artifact using a SOAP request to the
180identity provider.  The URL is ``LASSO_PROFILE(login)->msg_url`` while the
181request is ``LASSO_PROFILE(login)->msg_body``.  The request must succeed with
182an HTTP 200 status code.  The SOAP answer body must then be passed to::
183
184  lasso_login_process_response_msg(login, answer);
185
186Receiving an authentication response
187....................................
188
189A form with a ``LARES`` field has been posted; this element holds the
190authentication response.
191
192::
193
194  LassoLogin *login;
195
196  login = lasso_login_new(server);
197  lasso_login_process_authn_response_msg(lares_field);
198
199
200Federating identities
201.....................
202
203There is then a ``nameIdentifier`` (accessible through
204``LASSO_PROFILE(login)->nameIdentifier``) for the user identifying.  If this
205name identifier is already known by the service provider the corresponding
206identity and session must be restored.
207
208::
209
210  if (session_dump != NULL) {
211      lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump);
212  }
213  if (identity_dump != NULL) {
214      lasso_profile_set_identity_from_dump(LASSO_PROFILE(login), identity_dump);
215  }
216
217
218Process the authentication request, this will update (or create) the identity
219and session.
220
221::
222
223  lasso_login_accept_sso(login);
224
225Identity and session must then be saved and finally the ``login`` object can be
226destroyed::
227
228  lasso_login_destroy(login);
229
230And a success web page may then be displayed.
231
232
233
234
235
236Implementing the identity provider parts
237========================================
238
239XXX
240
241
242