How SAML2 Single Logout Works

First, lets understand the single logout work flow that is initiated by SP
Please note here,  i am using following diagram (This is copied from specification).  Here IDP is referred to SAML2 SSO Identity Provider and SP is referred to SAML2 SSO Service Provider

Profile Overview 


1.  LogoutRequest issued by SP to  IDP

2.  IDP determines authenticated SPs for given user session.  If there are no SPs, other than the SP who sends logout request, the profile proceeds with step 5. 

Otherwise, steps 3 and 4 are repeated for each SP 

3. LogoutRequest issued by IDP to SP

4. SP issues LogoutResponse to IDP

5. IDP issues LogoutResponse to SP who sends logout request

Let see what is in these requests and response messages 

Logout Request

LogoutRequest is extend from RequestAbstractType.  

There are some attributes that must be in the RequestAbstractType element 

1. ID   – An identifier for the request. This must be unique.  Basically a random number. 

2. Version  – Indicate SAML version 

3. IssueInstant – Time instant of issue of the request. The time value is encoded in UTC

Apart from that,  One of following is a required attribute for LogoutRequest request…

4. BaseID or NameID or EncryptedID  

This indicate the principle (user identifier).  Basically name that is known to both IDP and SP. 

Also there are few optional elements

5. NotOnOrAfter  – The time at which the request expires in UTC

6. Reason  –  reason for the logout, in the form of a URI reference.

There are two standard reasons 

urn:oasis:names:tc:SAML:2.0:logout:user  – user terminates session and initiates logout

urn:oasis:names:tc:SAML:2.0:logout:admin – admin terminates session and initiates logout

7. SessionIndex  – This is the session identifier that is used to identify the user session with both IDP and SP for given user.

Logout Repsonse

LogoutRepsonse is extend from StatusResponseType.  There are some attributes that must be in the StatusResponseType element.  i.e.  ID, Version and IssueInstant which is same as in RequestAbstractType. There is element called Status  element that is required.  Status element would contain the status code corresponding to the request. 

Sample Scenario

Lets take sample scenarios to explain how IDP and SPs handle the single logout scenario. Here we assume that there are IDP and two SPs; i.e called as SP1 and SP2 

Please note all request response messages must be signed or otherwise authenticated and integrity protected by the under line protocol. 

Step 1.  User is trying access SP1 and user has no authenticated session, therefore user is redirected to IDP

2. IDP has no authenticated session for user. Therefore user would be authenticated with user store.    

3. After successful authentication; 

IDP creates SAML token based on user and user’s attributes.  

IDP creates a session for user and IDP that is normally called as SSO session.  This SSO session is uniquely identified by session Id (which would be sent in assertion as SessionIndex) and the user. SSO session would contain details about the SP1.  Mostly SSO session would be persisted by the IDP

4. User is redirected to SP1 with SAML Response. 

Here we are interesting in followings element in the SAML Assertion 

a) Subject   –   This is used to identify the authenticated User. Mostly NameID is used for this.  Basically this is user name of the authenticated user. 


b) AuthnStatement  –  This provides some statement describing how subject has been authenticated with IDP. 

<saml2:authnstatement authninstant="2013-06-28T11:49:29.879Z" sessionindex="26C0530CBEA1DCF404C95B029D6A64AF">

 Here user has been authenticated by providing password.  Also it specifies the session identifier of the session that has been created with IDP and user, using SessionIndex attribute 

Step 5. If SAML response is valid, SP1 would create session for user and SP1.  Then, created session would be map with the received SessionIndex value.

Step 6. Now same user is trying to access SP2. 
and user has no authenticated session, therefore user is redirected to IDP

Step 7. IDP has an authenticated SSO session for user and IDP. Therefore SAML token is created.  SSO session would be updated with SP2 details. 

Step 8. User is redirected to SP2 with SAML Response.   SAML Assertion would be same as 
we discussed in step4

Step 9. If SAML response is valid, SP2 would create session with user and SP2.  Then, created session would be map with the received SessionIndex.

Now lets see single logout scenario….

Step 10. User is trying to logout from SP1. Then LogoutRequest is sent to IDP from SP1.  

Lets see what should be in this request. 

Basically,  SP1 need to provided the SSO session that is associated with IDP and the User. 

SP1 could finds out, received SessionIndex id and NameID for the user. As these details has been kept in SP’s  session

Then creates LogoutRequest based on that.. 

Sample LogoutRequest would be as follows

<saml2p:logoutrequest id="flkjhgfehcfjkjjmabgkcmlcnalbcillibfeeeag" issueinstant="2013-06-28T11:51:06.024Z" notonorafter="2013-06-28T11:56:06.024Z" reason="urn:oasis:names:tc:SAML:2.0:logout:user" version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
<saml2:nameid format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">admin</saml2:nameid>

Step 11. IDP validates LogoutRequest and If valid, it finds out the associate SSO session for given SessionIndex and that also is matched with NameID 

Step 12. IDP identifies the SPs that have been authenticated for the user from the SSO session.   Then IDP sends LogoutRequest to each SP (other than SP1) with corresponding SessionIndex and NameID

Therefore same LogoutRequest that is discussed in step10 would be sent to SP2 from IDP

Step 13. SP2 validates and processes LogoutRequest. SP2 invalidates the session that is associated with SessionIndex and is matched with NameID 

Step 14. SP2 sends LogoutResponse  to IDP with the status of success

<saml2p:statuscode value="urn:oasis:names:tc:SAML:2.0:status:Success" />

Step 15. IDP validates the LogoutResponse  and tracks on received status

16. Finally IDP invalidates SSO session  that is  associated with SessionIndex and 
is matched with NameID 

17. IDP sends  LogoutResponse to SP1  

If all are success 
LogoutResponse would be with status code   


If SP2 sends an error status in LogoutResponse, then with status code


If any other error, it would be with error status code.

However, Step12, Step13, Step 14 and Step15  are normally happening in separate threads.  It means once, IDP receives a logout request from SP1,  IDP would invalidate the SSO session that is  associated with SessionIndex and is matched with NameID.  Then IDP sends the LogoutResponse to SP1.  But in separate flow IDP would execute the Step12, Step13, Step 14 and Step15  steps.

I guess,  this would help you to understand how single logout must be implemented. Basically , if i simplify, this in code level…

In IDP implementation, There must be a some kind of SSO session (session between User and IDP) persistence method. It can be a simple in-memory Map;  with SessionIndex (session Id) as the key and session as the value of the Map. Please find sample implementation from here     

In SP implementation. There must be a some kind of user session (session between User and SP) persistence method. It can be a simple in-memory Map; 
with SessionIndex (received SessionIndex in Assertion) as the key and user session as the value of the Map. Please find sample implementation from here    

With WSO2 Identity Server  release, you could find sample web apps that demonstrate single logout functions. Please refer this  

Discuss this article on Stack Overflow


  1. Nice post Asela, thanks!

    Just one question, why do you need to maintain a Map for the SP? I have had to implement my own single log out servlet for Weblogic and apart from the “SAML2 related actions” (construct, verify and sign the requests) I only need to invalidate the current session: javax.servlet.http.HttpSession.invalidate()

    Thanks and best regards,


    1. WE have the same issue with weblogic and we are trying to solve the sam logout with weblogic. Can you please provide the code and some configuration advices? thanks

    2. Hello Luis,

      I am trying to implement my own Single Logout servlet for Weblogic. If you could give me an idea of how you went about getting the session index to construct the logout request, it would be a great help to me.

      Thanks in advance.

  2. Hi Asela –

    Its funny I came across this page as a few months later YOU specifically helped with our Identity Server integration for our WSO2 Quick Start engagement. Using IDP 4.1 in a high availability setup with APIM 1.4, I’ve come across an issue that maybe you can help with and also benefit others looking into same issue. When a user is validated into an SP (WSO2 API Store) behind an Identity Server however the Identity Server has been restarted or the Logout request is directed to a different Identity Server, upon logout, the Logout Request will contain a session index that the Identity Server does not know about. This produces an error:

    ERROR {org.wso2.carbon.identity.sso.saml.processors.LogoutRequestProcessor} – No Established Sessions corresponding to Session Indexes provided. {org.wso2.carbon

    and in the Identity Server access log you see it POST to /null
    and the user is directed to the carbon management login instead of the appropriate SSO login.

    Does the latest Identity Server address this? Or is there another way to gracefully handle the situation where the SP is holding onto session indexes that the Identity Server no longer knows about. I would think the expected behavior would be to provide the SAML response to SP saying the SSO session does not exist or if not in SAML2.0 spec, say that its closed because that will allow the SP to logout accordingly as well. That would be better than not providing a response and going to a nasty admin console login =]

    Any thoughts?

    Happy Holidays,

    1. Hi Damian,

      I guess, you are using two identity servers in a cluster and you are providing credentials to one IS and when logout it would be redirected other IS… Actually SSO session that is created once user login to the IDP, contains this “Session Index”. If we can replicate this SSO session across two nodes, we can get rid of this issue. In 4.1.0 version, this replication is happened with axis2 state replication. You need to enable axis2 clustering and state replication using axis2.xml file in both nodes…..


      Actually, if you are using one IS node and if you restart it, SSO session would be invalidated as it is not persisted and there is not way to replicated with other nodes. With 4.6.0, IS uses Hazelcast based replication mechanism. According to my own idea, It is much convenient than the axis2 state replication

      1. Hi Asela —

        Your recommendation in re: axis2 clustering worked perfectly for our setup! This should greatly reduce the chance that a network or server failure impacts the user experience.

        Additionally, with only two nodes in the cluster located in same AWS AZ, the difference between:



        is pretty marginal in my quick testing (<0.2s). I am curious if WSO2 has done any testing around the performance of this setting as the number of nodes or geographical regions scale up.

        Does Hazelcast replication in your latest IS version provide any additional settings in this area, possibly provide a middle ground option like mongoDB's write concern (w:2) concept where it can return as soon as it has written to at least one other node? Bonus points if HazelCast can unblock when written to local node and the closest node by ping time 🙂

        FYI – I tried to upgrade our setup to IS 4.6.0 but I think I ran into this issue: which I cannot easily address in our APIM 1.4

        Great post and response!

  3. Nice post. Thanks.

    You are describing a GLOBAL logout (one SP logout, all the other SP logout as well). But I am interesting in LOCAL logout, one user logouts from his SP and is redirect back to where he is still logged-in, the IDP.

    Does SAML support local logout? And if it does, how do I specify parameters in LogoutRequest?


Leave a Reply

Your email address will not be published. Required fields are marked *