| Top | |
|
|
|
| LassoLogout * | lasso_logout_new () |
| LassoLogout * | lasso_logout_new_from_dump () |
| lasso_error_t | lasso_logout_build_request_msg () |
| lasso_error_t | lasso_logout_build_response_msg () |
| void | lasso_logout_destroy () |
| gchar * | lasso_logout_dump () |
| gchar * | lasso_logout_get_next_providerID () |
| lasso_error_t | lasso_logout_init_request () |
| lasso_error_t | lasso_logout_process_request_msg () |
| lasso_error_t | lasso_logout_process_response_msg () |
| lasso_error_t | lasso_logout_reset_providerID_index () |
| lasso_error_t | lasso_logout_validate_request () |
This profile Send logout notifications between providers. Any receiving provider must retransmit the notification to any other providers with which it shares the current identity by any means supported by the two, that is any provider federated with the current provider. There can be partial failures if no binding can be found to notify a federating partner or if a partner fails to respond.
It is generally advised to apply the local logout transaction before sending a logout request to a partner. In short:
an identity provider receiving a logout request should kill the local session before sending logout request to other service provider and proxyied identity providers.
a service provider intitiating a logout request must first kill its local session, then proceeds with the logout exchange with its identity provider
The following examples must not be used 'as-is' they lack most of the error checking code that is needed for a secured and robust program, but they give an idea of how to use the API
Example 5. Service Provider Initiated Logout
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
LassoLogout *logout; char *session_dump; // must contain the session dump // for the current user int rc; // hold return codes char *soap_response; LassoHttpMethod method; // method to use, LASSO_HTTP_METHOD_REDIRECT, // LASSO_HTTP_METHOD_POST or LASSO_HTTP_METHOD_SOAP, // other methods are rarely supported logout = lasso_logout_new(server); lasso_profile_set_session_from_dump(&logout->parent, session_dump); // the second argument can be NULL, lasso_logout_init_request() will automatically choose the // identity provider from the first assertion int the session rc = lasso_logout_init_request(logout, "http://identity-provider-id/", method); if (rc != 0) { ... // handle errors, most of them are related to bad initialization // or unsupported binding } rc = lasso_logout_build_request_msg(logout); if (rc != 0) { ... // handle errors, most of them are related to bad initialization // or impossibility to build the query string (missing private keys for signing) } // now send the request switch (method) { case LASSO_HTTP_METHOD_REDIRECT: // LASSO_PROFILE(logout)->msg_url contains the URL where the // User Agent must be redirected ... // save the session and logout object, and store them attached to the RequestID of the // request, you will need them for handling the response session_dump = lasso_node_dump((LassoNode*)logout->parent.session); logout_dump = lasso_node_dump((LassoNode*)logout); break; case LASSO_HTTP_METHOD_POST: // you must build a form with a field name SAMLRequest (SAML 2.0) or LAREQ (ID-FF 1.2) // with the content of LASSO_PROFILE(logout)->msg_body // posting to the address LASSO_PROFILE(logout)->msg_url ... // save the session and logout object, and store them attached to the RequestID of the // request, you will need them for handling the response session_dump = lasso_node_dump((LassoNode*)logout->parent.session); logout_dump = lasso_node_dump((LassoNode*)logout); break; case LASSO_HTTP_SOAP: // makes a SOAP call, soap_call is NOT a Lasso function soap_response = soap_call(login->parent.msg_url, login->parent.msg_body); rc = lasso_logout_process_response_msg(logout, soap_response); if (rc != 0) { // handle errors, important ones are LASSO_LOGOUT_ERROR_UNSUPPORTED_PROFILE meaning // that one other service provider of the current session cannot be contacted by the // identity provider with the current binding, for example it only accept REDIRECT (asynchronous-binding) or // POST an we are using SOAP (synchronous-binding). ... } // everything is ok save the session session_dump = lasso_node_dump(logout->parent.session); // nothing to save because you killed the local session already break; default: // other binding neither are frequent or largely supported // so report an error break; } |
The next example show the endpoint for handling response to request with asynchronous binding (POST and Redirect).
Example 6. Service Provider Logout Request Endpoint
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
LassoLogout *logout; char *request_method = getenv("REQUEST_METHOD"); logout = lasso_logout_new(server); if (strcmp(request_method, "GET") == 0) { char query_string = getenv("QUERY_STRING"); rc = lasso_logout_process_response_msg(logout, query_string); } elif (strcmp(request_method, "POST") == 0) { char *message; // message should contain the content of LARES or SAMLResponse fied, depending if this is an // ID-FF 1.2 or SAML 2.0 service. rc = lasso_logout_process_response_msg(logout, message); } if (rc != 0) { // handle errors, as we are already unlogged, those must go to a log file or audit trail, // because at this time the user do not care anymore. A report about a failure to logout to // the IdP can be eventually shown. ... } |
The next snippet show how to implement a logout endpoint, to receive a logout request and respond.
Example 7. Service Provider Logout Request Endpoint
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
LassoLogout *logout; char *session_dump; char *request_method = getenv("REQUEST_METHOD"); int rc; int method; logout = lasso_logout_new(server); // server must be previously initialized, it can be kept around // and used for many transaction, it is never modified by any profile if (strcmp(request_method. "GET") == 0) { method = LASSO_HTTP_METHOD_REDIRECT; char query_string = getenv("QUERY_STRING"); rc = lasso_logout_process_request_msg(logout, query_string); if (rc != 0) { // handle errors ... } } else if (strcmp(request_method, "POST") == 0) { char *message; // read submitted content if this is a form, put LAREQ or SAMLRequest field into message and set method to LASSO_HTTP_METHOD_POST // if content type is application/xml then put the full body of the POST inside message and // set method to LASSO_HTTP_METHOD_SOAP rc = lasso_logout_process_request_msg(logout, message); if (rc != 0) { // handle errors ... } } protocolProfile = lasso_provider_get_protocol_conformance(LASSO_PROVIDER(server)); if (protocolProfile == LASSO_LIBERTY_1_2) { char *session_index; LassoSamlNameIdentifier *name_id; LibLogoutRequest *logout_request; logout_request = LIB_LOGOUT_REQUEST(LASSO_PROFILE(logout)->request); session_index = logout_request->SessionIndex; name_id = logout_request->NameIdentifier; // lookup the session dump using session_index and name_id } else if (protocolProfile == LASSO_SAML_2_0) { char *session_index; LassoSaml2NameID *name_id; LassoSamlp2LogoutRequest *logout_request; logout_request = LASSO_SAMLP2_LOGOUT_REQUEST(LASSO_PROFILE(logout)->request); session_index = logout_request->SessionIndex; name_id = logout_request->NameID; // lookup the session dump using session_index and name_id } lasso_profile_set_session_from_dump(LASSO_PROFILE(logout), session_dump); // you can check other property of the request here if you want // if (request is accepted) { rc = lasso_logout_validate_request(logout); if (rc != 0) { // handle errors.. ... } else { .... // kill the local session // if local server is an identity provider, then traverse the session using // lasso_logout_get_next_providerID() and send logout request to all logged // service providers. } } // if lasso_logout_validate_request() was not called this will automatically create a Failure // response. rc = lasso_logout_build_response_msg(logout); if (rc != 0) { // handle errors.. ... } // the response is produced with the same binding as the request // see the previous request example for how to send the response // the only change is for SOAP, you just need to print the msg_body as page content with a // Content-type of application/xml. |
LassoLogout *
lasso_logout_new (LassoServer *server);
Creates a new LassoLogout.
LassoLogout * lasso_logout_new_from_dump (LassoServer *server,const gchar *dump);
Restores the dump
to a new LassoLogout.
lasso_error_t
lasso_logout_build_request_msg (LassoLogout *logout);
Builds the logout request message.
It gets the HTTP method retrieved to send the request and:
if it is a SOAP method, then it builds the logout request SOAP message,
sets the msg_body attribute, gets the single logout service url and sets
msg_url in the logout object.
if it is a HTTP-Redirect method, then it builds the logout request QUERY
message, builds the logout request url, sets msg_url in the logout
request url, sets msg_body to NULL.
If private key and certificate are set in server object it will also signs the message (either with X509 if SOAP or with a simple signature for query strings).
lasso_error_t
lasso_logout_build_response_msg (LassoLogout *logout);
Builds the logout response message.
It gets the request message method and:
if it is a SOAP method, then it builds the logout response SOAP message,
sets the msg_body attribute, gets the single logout service return url
and sets msg_url in the logout object.
if it is a HTTP-Redirect method, then it builds the logout response QUERY message,
builds the logout response url, sets msg_url with the logout response url,
sets msg_body to NULL
If private key and certificate are set in server object it will also signs the message (either with X509 if SOAP or with a simple signature for query strings).
gchar *
lasso_logout_dump (LassoLogout *logout);
Dumps logout
content to an XML string.
gchar *
lasso_logout_get_next_providerID (LassoLogout *logout);
Returns the provider id from providerID_index in list of providerIDs in principal session with the exception of initial service provider ID.
lasso_error_t lasso_logout_init_request (LassoLogout *logout,gchar *remote_providerID,LassoHttpMethod request_method);
Initializes a new SLO request.
lasso_error_t lasso_logout_process_request_msg (LassoLogout *logout,gchar *request_msg);
Processes a SLO LogoutRequest message. Rebuilds a request object from the message and optionally verifies its signature.
lasso_error_t lasso_logout_process_response_msg (LassoLogout *logout,gchar *response_msg);
Parses the response message and builds the response object.
Checks the status code value and if it is not success, then if the local provider is a Service Provider and response method is SOAP, then builds a new logout request message for HTTP Redirect / GET method and returns the error code LASSO_LOGOUT_ERROR_UNSUPPORTED_PROFILE.
If it is a SOAP method or, IDP type and http method is Redirect/GET, then removes assertion.
If local server is an Identity Provider and if there is no more assertion (Identity Provider has logged out every Service Providers), then restores the initial response.
lasso_error_t
lasso_logout_reset_providerID_index (LassoLogout *logout);
Reset the providerID_index attribute (set to 0).
lasso_error_t
lasso_logout_validate_request (LassoLogout *logout);
Sets the remote provider id
Sets a logout response with status code value to success.
Checks current signature status, if verification failed, stop processing and set the status code value to failure.
Verifies federation and authentication.
If the request http method is a SOAP method, then verifies every other Service Providers supports SOAP method : if not, then sets status code value to UnsupportedProfile and returns a code error with LASSO_LOGOUT_ERROR_UNSUPPORTED_PROFILE.
Every tests are ok, then removes assertion.
If local server is an Identity Provider and if there is more than one Service Provider (except the initial Service Provider), then saves the initial request, response and remote provider id.
0 on success; or LASSO_PROFILE_ERROR_MISSING_REQUEST if no request has been found -- usually means that lasso_logout_process_request_msg was not called, LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the requesting provider is not known to the server object, LASSO_PROFILE_ERROR_BUILDING_RESPONSE_FAILED if creation of the response object failed, LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND if the request do not contain a NameID element, LASSO_PROFILE_ERROR_SESSION_NOT_FOUND if the logout profile object do not contain a session object, LASSO_PROFILE_ERROR_MISSING_ASSERTION if no assertion from the requesting provider was found, LASSO_PROFILE_ERROR_IDENTITY_NOT_FOUND if the logout profile object do not contain an identity object, LASSO_PROFILE_ERROR_FEDERATION_NOT_FOUND if no federation for the requesting provider was found, LASSO_LOGOUT_ERROR_UNSUPPORTED_PROFILE if the requested HTTP method is not supported by all the remote provider of the current session.