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