got uptodate documentation about single sign on (I think)

4 files changed, 135 insertions, 86 deletions

diff --git a/docs/lasso-book/single-logout.process b/docs/lasso-book/single-logout.process
index 0085885d..e735766a 100644
--- a/docs/lasso-book/single-logout.process
+++ b/docs/lasso-book/single-logout.process
@@ -10,6 +10,9 @@ Single Log Out
                 lasso_profile_set_session_from_dump(LASSO_PROFILE(logout), session_dump)
                 lasso_logout_init_request(logout, idpProviderId, lassoHttpMethodAny)
                     # if idpProviderId is NULL the first one defined in the metadata will be picked
+                    # if third param http method is lassoHttpMethodAny, then lasso retrieves
+		    # the first http mehtod supported by both providers, else check
+		    # the passed http method is supported.
                 request = LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(logout)->request)
                 lasso_lib_authn_request_set_relayState(request, relayState)
                     # relayState is an optional value set by the SP
@@ -59,7 +62,7 @@ Single Log Out
     IdP
         /singleLogout (* normative, Single Log-Out service URL *)
             logout = lasso_logout_new(server, lassoProviderTypeIdp)
-            lasso_logout_process_request_msg(logout, /query string/, lassoHttpMethodRedirect)
+            lasso_logout_process_request_msg(logout, /query string/)
             IF error AND error IS NOT LASSO_PROFILE_ERROR_INVALID_QUERY
                 BOOM
 
@@ -80,8 +83,7 @@ Single Log Out
                     SOAP CALL
                         TO LASSO_PROFILE(logout)->msg_url
                         BODY LASSO_PROFILE(logout)->msg_body
-                    lasso_logout_process_response_msg(logout,
-                                soap_answer_message, lassoHttpMethodSoap)
+                    lasso_logout_process_response_msg(logout, soap_answer_message)
                 other_sp = lasso_logout_get_next_providerID(logout)
 
             lasso_logout_reset_providerID_index(logout)
@@ -123,8 +125,7 @@ Single Log Out
                     SOAP CALL
                         TO LASSO_PROFILE(logout)->msg_url
                         BODY LASSO_PROFILE(logout)->msg_body
-                    lasso_logout_process_response_msg(logout,
-                                soap_answer_message, lassoHttpMethodSoap)
+                    lasso_logout_process_response_msg(logout, soap_answer_message)
                     other_sp = lasso_logout_get_next_providerID(logout)
 
                 lasso_logout_build_response_msg(logout)
diff --git a/docs/lasso-book/single-sign-on.process b/docs/lasso-book/single-sign-on.process
index 6dbc81d6..d04ff539 100644
--- a/docs/lasso-book/single-sign-on.process
+++ b/docs/lasso-book/single-sign-on.process
@@ -1,46 +1,68 @@
-Single Sign On
+Single Sign-On and Federation
     SP
         /login (* url not normative *)
             login = lasso_login_new(server)
-            lasso_login_init_authn_request(login, method)
-                # method = lassoHttpMethodRedirect or lassoHttpMethodPost
+            lasso_login_init_authn_request(login, idpProviderId, method)
+                # method is one of:
+                #  - LASSO_HTTP_METHOD_REDIRECT
+                #  - LASSO_HTTP_METHOD_POST
+
             request = LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)
-            lasso_lib_authn_request_set_forceAuthn(request, TRUE)
-            lasso_lib_authn_request_set_nameIDPolicy(request, policy)
+
+            request->NameIDPolicy = strdup(policy)
                 # policy is one of:
-                #  - lassoLibNameIDPolicyTypeFederated
-                #  - (...)
-            lasso_lib_authn_request_set_consent(request, consent)
+                #  - LASSO_LIB_NAMEID_POLICY_TYPE_FEDERATED (for SSO and federation)
+                #  - LASSO_LIB_NAMEID_POLICY_TYPE_NONE (for SSO only)
+                #  - LASSO_LIB_NAMEID_POLICY_TYPE_ONE_TIME (anonymous SSO)
+                #  - LASSO_LIB_NAMEID_POLICY_TYPE_ANY (Tries FEDERATED otherwise ONE_TIME)
+            request->ForceAuthn = TRUE;
+            request->IsPassive = FALSE;
+            request->ProtocolProfile = strdup(protocol_profile);
+                # protocol_profile is one of:
+                #  - LASSO_LIB_PROTOCOL_PROFILE_BRWS_ART;
+                #  - LASSO_LIB_PROTOCOL_PROFILE_BRWS_POST;
+            request->consent = strdup(consent);
                 # consent is one of:
-                #  - lassoLibConsentObtained
-            lasso_lib_authn_request_set_relayState(request, relayState)
-                # relayState is an optional value set by the SP
-            lasso_login_build_authn_request_msg(login, idpProviderId)
-                # if idpProviderId is NULL the first one defined in the metadata will be picked
+                #  - LASSO_LIB_CONSENT_OBTAINED
+                #  - LASSO_LIB_CONSENT_OBTAINED_PRIOR
+                #  - LASSO_LIB_CONSENT_OBTAINED_CURRENT_IMPLICIT
+                #  - LASSO_LIB_CONSENT_OBTAINED_CURRENT_EXPLICIT
+                #  - LASSO_LIB_CONSENT_UNAVAILABLE
+                #  - LASSO_LIB_CONSENT_INAPPLICABLE
+
+            lasso_login_build_authn_request_msg(login)
             
-            IF lassoHttpMethodRedirect
+            IF method == REDIRECT
                 REDIRECT TO LASSO_PROFILE(login)->msg_url
             
-            IF lassoHttpMethodPost
+            IF method == POST
                 DISPLAY HTML FORM
+                   <body onload="document.forms[0].submit()">
                     <form action="** LASSO_PROFILE(login)->msg_url **" method="post">
                      <input type="hidden" name="LAREQ"
-		     	value="** LASSO_PROFILE(login)->msg_body **"/>
+                       value="** LASSO_PROFILE(login)->msg_body **"/>
                     </form>
+                   </body>
 
 
     IdP
         /singleSignOn (* normative, Single Sign On service URL *)
             login = lasso_login_new(server)
             lasso_profile_set_identity_from_dump(LASSO_PROFILE(login), identity_dump)
-                # if identity_dump exists
             lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump)
-                # if session_dump exists
             IF METHOD IS GET
-                authn_request_msg = /query string/
+                IF lasso_profile_is_liberty_query(/query string/)
+                    authn_request_msg = /query string/
+                ELSE
+                   # The single sign-on service URL has been accessed directly by the user, so
+                   # proceed to an IDP initiated SSO.
+                   # First ask the user the SP for which he wants to proceed to sign-on.
+                   lasso_login_init_idp_initiated_authn_request(serviceProviderId)
             IF METHOD IS POST
                 authn_request_msg = /form submitted LAREQ field/
-            lasso_login_init_from_authn_request_msg(login, authn_request_msg)
+
+            IF authn_request_msg:
+                lasso_login_process_msg(login, authn_request_msg)
 
             IF lasso_login_must_authenticate(login)
                 # proceed to authentication
@@ -50,30 +72,56 @@ Single Sign On
 
                 # may be coming back from another function; another url
                 # unserialize with lasso_login_new_from_dump(dump)
-                userAuthenticated = TRUE
-
+                userAuthenticated = TRUE # or FALSE if authentication failed
             ELSE
                 userAuthenticated = TRUE
                     # or FALSE if it was not authenticated previously
 
-            authenticationMethod = lassoSamlAuthenticationMethodPassword
-                # or lassoSamlAuthenticationMethodSoftwarePki or others
+            consentObtained = FALSE
+            IF userAuthenticated
+                IF lasso_login_must_ask_for_consent(login)
+                   # ask user if he consents to federation
+                   # may serialize login object now: lasso_login_dump(login)  
+
+                   # (...)
+
+                   # may be coming back from another function; another url
+                   # unserialize with lasso_login_new_from_dump(dump)
+                   consentObtained = TRUE # or FALSE if user didn't give its consent
+
+            authenticationMethod = LASSO_SAML_AUTHENTICATION_METHOD_PASSWORD
+                # or LASSO_SAML_AUTHENTICATION_METHOD_SOFTWARE_PKI or others
                 # (see ...)
                 # this is how the user has been authenticated
 
+            authenticationInstant = "2004-03-01T00:00:00Z"
+                # this is when the authentication occured; when NULL Lasso will put current time
+
+            assertionIsNotBefore = "2004-03-01T00:00:00Z"
+                # this is when assertion starts to be valid; NULL when not used
+
+            assertionIsNotOnOrAfter = "2004-04-01T00:00:00Z"
+                # this is when assertion stops to be valid; NULL when not used
+
             reauthenticationTime = "2004-04-01T00:00:00Z"
-                # this is when the user will have to be reauthenticated
+                # this is when the user will have to be reauthenticated; NULL when not used
 
             IF login->protocolProfile IS lassoLoginProtocolProfileBrwsArt
                 lasso_login_build_artifact_msg(login, userAuthenticated,
-                    authenticationMethod, reauthenticationTime,
+                    consentObtained,
+                    authenticationMethod,
+                    authenticationInstant, reauthenticationTime,
+                    assertionIsNotBefore, assertionIsNotOnOrAfter,
                     lassoHttpMethodRedirect)
-
-            IF login->protocolProfile IS lassoLoginProtocolProfileBrwsPost
+            ELSE # IF login->protocolProfile IS lassoLoginProtocolProfileBrwsPost
                 lasso_login_build_authn_response_msg(login, userAuthenticated,
-                    authenticationMethod, reauthenticationTime)
+                    consentObtained,
+                    authenticationMethod,
+                    authenticationInstant, reauthenticationTime,
+                    assertionIsNotBefore, assertionIsNotOnOrAfter,
+                    reauthenticationTime)
 
-            # map LASSO_PROFILE(login)->nameIdentifier to user
+            # map LASSO_PROFILE(login)->nameIdentifier to user and session
             # (write this down in a database)
 
             IF lasso_profile_is_identity_dirty(LASSO_PROFILE(login))
@@ -86,21 +134,19 @@ Single Sign On
                 # save session;
                 #   serialization with lasso_session_dump(session)
 
-
             IF login->protocolProfile IS lassoLoginProtocolProfileBrwsArt
-                assertion = lasso_login_get_assertion(login)
-                # save assertion; mapped to login->assertionArtifact  (|1|)
-                #   serialization with lasso_node_export(LASSO_NODE(assertion))
-                #    !!! LAME !!!
-        
+                # map assertionArtifact to login.remote_providerID and web session
+                # FIXME : artifact can be either Redirect or POST
                 REDIRECT TO LASSO_PROFILE(login)->msg_url
 
-            IF login->protocolProfile IS lassoLoginProtocolProfileBrwsPost
+            ELSE # IF login->protocolProfile IS lassoLoginProtocolProfileBrwsPost
                 DISPLAY HTML FORM
+                   <body onload="document.forms[0].submit()">
                     <form action="** LASSO_PROFILE(login)->msg_url **" method="post">
                      <input type="hidden" name="LARES"
-		     	value="** LASSO_PROFILE(login)->msg_body **"/>
+                       value="** LASSO_PROFILE(login)->msg_body **"/>
                     </form>
+                   </body>
 
 
     SP
@@ -108,15 +154,15 @@ Single Sign On
             login = lasso_login_new(server)
             IF METHOD IS GET OR SUBMITTED FORM HAS LAREQ FIELD
                     IF METHOD IS GET
-                        authn_request_msg = /query string/
+                        artifact_msg = /query string/
                         relayState = /query string, RelayState var/
-                        method = lassoHttpMethodRedirect
-                    IF METHOD IS POST
-                        authn_request_msg = /form submitted LAREQ field/
+                        method = LASSO_HTTP_METHOD_REDIRECT
+                    ELSE # IF METHOD IS POST
+                        artifact_msg = /form submitted LAREQ field/
                         relayState = /form submitted RelayState field/
-                        method = lassoHttpMethodPost
+                        method = LASSO_HTTP_METHOD_POST
 
-                    lasso_login_init_request(login, authn_request_msg, method)
+                    lasso_login_init_request(login, artifact_msg, method)
                     lasso_login_build_request_msg(login)
 
                     SOAP CALL ---------------------------------------------------------\
@@ -126,7 +172,7 @@ Single Sign On
                     lasso_login_process_response_msg(login, soap_answer_message)
 
             ELSE IF SUBMITTED FORM HAS LARES FIELD
-                response_msg = /form submitted LARED field/
+                response_msg = /form submitted LARES field/
                 lasso_login_process_authn_response_msg(login, response_msg)
                 relayState = LASSO_PROFILE(login)->msg_RelayState
 
@@ -134,6 +180,7 @@ Single Sign On
 
             IF known nameIdentifier
                 # GET BACK identity_dump and session_dump
+                # First retrieve session and user by nameIdentifier
                 lasso_profile_set_identity_from_dump(LASSO_PROFILE(login, identity_dump)
                 lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump)
 
@@ -149,8 +196,12 @@ Single Sign On
                 # save session;
                 #   serialization with lasso_session_dump(session)
 
+            IF nameIdentifier was not known:
+                # if the user was not yet logged on SP before SSO, it is a good place to ask the
+                # user to register on SP, to create a web session and store lasso_session_dump in
+                # it, and to create or retrieve user account and store lasso_identity_dump there.
             
-            REDIRECT anywhere
+            REDIRECT anywhere # SSO is finished
 
 
     IdP                                                                                |
@@ -161,11 +212,10 @@ Single Sign On
             IF request_type IS lassoRequestTypeLogin
                 login = lasso_login_new(server);
                 lasso_login_process_request_msg(login, soap_msg);
-                
-                # retrieve assertion_dump saved in (|1|) (and then delete it)
-                lasso_login_set_assertion_from_dump(login, assertion_dump)
-
-                lasso_login_build_response_msg(login)
-
+                # Retrieve remote_providerID and web session using login->assertionArtifact
+                # and then remove them.
+                # Retrieve session_dump stored in session.
+                lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump)
+                lasso_login_build_response_msg(login, remote_providerID)
                 ANSWER SOAP REQUEST WITH: LASSO_PROFILE(login)->msg_body
 
diff --git a/docs/lasso-book/single-sign-on.rst b/docs/lasso-book/single-sign-on.rst
index 5067468e..d7d00157 100644
--- a/docs/lasso-book/single-sign-on.rst
+++ b/docs/lasso-book/single-sign-on.rst
@@ -109,33 +109,32 @@ match a providerID defined in the metadata file).
 
 Select profile to use, HTTP Redirect::
 
-  lasso_login_init_authn_request(login, lassoHttpMethodRedirect);
+  lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_REDIRECT);
 
 or HTTP POST::
 
-  lasso_login_init_authn_request(login, lassoHttpMethodPost);
+  lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_POST);
   
 
 Parametrize request::
 
   /* will force authentication on the identity provider */
-  lasso_lib_authn_request_set_forceAuthn(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), 1);
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->ForceAuthn = TRUE;
   
   /* ask for identity federation */
-  lasso_lib_authn_request_set_nameIDPolicy(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), lassoLibNameIDPolicyTypeFederated);
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->NameIDPolicy =
+      strdup(LASSO_LIB_NAME_ID_POLICY_TYPE_FEDERATED);
 
   /* the user consents with the idea of identity federation */
-  lasso_lib_authn_request_set_consent(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), lassoLibConsentObtained);
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->consent =
+      strdup(LASSO_LIB_CONSENT_OBTAINED);
 
 (see API reference for other possible values)
 
 
 Create the authentication request::
 
-  lasso_login_build_authn_request_msg(login, idpProviderId);
+  lasso_login_build_authn_request_msg(login);
 
 
 An URL is then defined in ``LASSO_PROFILE(login)->msg_url``; the user must be
@@ -163,7 +162,7 @@ used to initialize the *LassoLogin* object.
   LassoLogin *login;
   
   login = lasso_login_new(server);
-  lasso_login_init_request(login, query_string, lassoHttpMethodRedirect);
+  lasso_login_init_request(login, query_string, LASSO_HTTP_METHOD_REDIRECT);
   lasso_login_build_request_msg(login);
 
 If it was a form post it will have a ``LAREQ`` field.
@@ -173,7 +172,7 @@ If it was a form post it will have a ``LAREQ`` field.
   LassoLogin *login;
 
   login = lasso_login_new(server);
-  lasso_login_init_request(login, lareq_field, lassoHttpMethodPost);
+  lasso_login_init_request(login, lareq_field, LASSO_HTTP_METHOD_POST);
   lasso_login_build_request_msg(login);
 
 
diff --git a/docs/lasso-book/writing-a-c-sp.txt b/docs/lasso-book/writing-a-c-sp.txt
index a3fb3004..c6492faa 100644
--- a/docs/lasso-book/writing-a-c-sp.txt
+++ b/docs/lasso-book/writing-a-c-sp.txt
@@ -86,9 +86,10 @@ The ``LassoServer`` object may be created as follows:
 
   LassoServer *server;
   server = lasso_server_new("sp-metadata.xml",
-  		NULL, "sp-private-key.pem", "sp-crt.pem", lassoSignatureMethodRsaSha1);
-  lasso_server_add_provider(server, "idp-metadata.xml",
-  		"idp-public-key.pem", "ca-crt.pem");
+  		"sp-private-key.pem", "sp-crt.pem",
+		LASSO_SIGNATURE_METHOD_RSA_SHA1);
+  lasso_server_add_provider(server, LASSO_PROVIDER_ROLE_IDP,
+  		"idp-metadata.xml", "idp-public-key.pem", "ca-crt.pem");
 
 - ``sp-metadata.xml`` is the Liberty metadata file for the service provider
 - ``idp-metadata.xml`` is the Liberty metadata file for the identity provider
@@ -189,17 +190,15 @@ defined in the metadata file).
   LassoLogin *login;
   
   login = lasso_login_new(server);
-  lasso_login_init_authn_request(login, lassoHttpMethodRedirect);
+  lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_REDIRECT);
   
-  lasso_lib_authn_request_set_forceAuthn(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), 1);
-  lasso_lib_authn_request_set_isPassive(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), 0);
-  lasso_lib_authn_request_set_nameIDPolicy(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), lassoLibNameIDPolicyTypeFederated);
-  lasso_lib_authn_request_set_consent(
-      LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request), lassoLibConsentObtained);
-  lasso_login_build_authn_request_msg(login, idpProviderId);
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->ForceAuthn = TRUE;
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->IsPassive = FALSE;
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->NameIDPolicy =
+      strdup(LASSO_LIB_NAME_ID_POLICY_TYPE_FEDERATED);
+  LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->consent =
+      strdup(LASSO_LIB_CONSENT_OBTAINED);
+  lasso_login_build_authn_request_msg(login);
 
 
 You can now redirect the user to the URL defined in ``LASSO_PROFILE(login)->msg_url``; for
@@ -220,7 +219,7 @@ passed in the query parameter.
   LassoLogin *login;
   
   login = lasso_login_new(server);
-  lasso_login_init_request(login, query_string, lassoHttpMethodRedirect);
+  lasso_login_init_request(login, query_string, LASSO_HTTP_METHOD_REDIRECT);
   lasso_login_build_request_msg(login);
 
 The service provider must check this artifact using a SOAP request to the
@@ -296,7 +295,7 @@ This part is about a logout using SOAP and initiated on the service provider.
 
   LassoLogout *logout;
 
-  logout = lasso_logout_new(lassoServer, lassoProviderTypeSp);
+  logout = lasso_logout_new(lassoServer);
 
 
 Identity and session dumps should be restored to prepare the logout request.
@@ -310,14 +309,14 @@ Identity and session dumps should be restored to prepare the logout request.
       lasso_profile_set_identity_from_dump(LASSO_PROFILE(logout), identity_dump);
   }
   
-  lasso_logout_init_request(logout, NULL, lassoHttpMethodSoap);
+  lasso_logout_init_request(logout, idpProviderId, LASSO_HTTP_METHOD_SOAP);
   lasso_logout_build_request_msg(logout);
 
 
 The service provider must then make a SOAP request to the identity provider;
 ``msg_url`` and ``msg_body``.  You should then pass the answer to Lasso::
 
-  lasso_logout_process_response_msg(logout, answer, lassoHttpMethodSoap)
+  lasso_logout_process_response_msg(logout, answer);
 
 And save back session and user dump; the process is similar as the one at the
 end of the single sign on profile.
@@ -333,7 +332,7 @@ is strongly advised to check this return code on each call.
 
   int rc;
 
-  rc = lasso_logout_process_response_msg(logout, answer, lassoHttpMethodSoap)
+  rc = lasso_logout_process_response_msg(logout, answer)
   if (rc) {
       fprintf(stderr, "Lasso Error: %d\n", rc);
       /* handling error; most probably bailing out */