Purpose

Confluence Data Center is bundled with the SSO for Atlassian Server and Data Center App. With this App, Confluence administrators can configure SSO using SAML 2.0 or OIDC with your preferred Identity Provider (IdP).

This document provides some general understanding about SAML and how it works in Confluence DC. 

What is SAML and How it works

Security Assertion Markup Language (SAML) is an open standard that allows identity providers (IdP) to pass authorization credentials to service providers (SP), this includes information about users, logins and their attributes. SAML transactions use Extensible Markup Language (XML) for standardised communications between the IdP and SP. 

Let's see an example of how SAML works with Confluence: 

1. A user tries to access Confluence using SSO Authentication
2. Confluence (acting as a SP) detects the IdP responsible for authenticating this user

3. Confluence generates a SAML <AuthnRequest> and redirects the user's browser to the IdP single sign-on URL. 

   2023-10-10 09:47:32,539 DEBUG [http-nio-8090-exec-41 url: /plugins/servlet/external-login/1; user: admin] [onelogin.saml2.authn.AuthnRequest] <init> AuthNRequest --> 
   <samlp:AuthnRequest 
   xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
   ID="ONELOGIN_a67bead3-dd5f-4cef-a616-b68298876380" 
   Version="2.0" IssueInstant="2023-10-10T13:47:32Z" ForceAuthn="true" 
   Destination="https://IDP_PROVIDER_URL/.../.../sso/saml" 
   ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
   AssertionConsumerServiceURL="https://CONFLUENCE_URL/plugins/servlet/samlconsumer">
   <saml:Issuer>https://CONFLUENCE_URL</saml:Issuer>
   </samlp:AuthnRequest>

4. The browser will then handle the received redirect and issue HTTP GET  to the Identity Provider URL
5. The IdP checks if the user has an active login session. If the session isn't found, the user will need to authenticate with their login/password. As a result, the IdP will generate a SAML token
6. IdP by using POST Binding passes the <Response> message to Confluence.
   1. The <Response> includes an assert with this user's security context.
   2. The SAMLResponse body is transferred in the base64 encoding in the <saml2p:Response> element. 

7. Confluence validates the SAML <Response> and completes user sign-in. 

   023-10-10 09:48:41,296 DEBUG [http-nio-8090-exec-275 url: /plugins/servlet/samlconsumer; user: admin] [onelogin.saml2.authn.SamlResponse] isValid SAMLResponse validated --> 
   <?xml version="1.0" encoding="UTF-8"?>
   <saml2p:Response 
   Destination="https://CONFLUENCE_URL/plugins/servlet/samlconsumer" 
   ID="id3652322626225772431717045" InResponseTo="ONELOGIN_a67bead3-dd5f-4cef-a616-b68298876380" 
   IssueInstant="2023-10-10T13:48:40.335Z" Version="2.0" 
   xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
   <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://IDP_PROVIDER_URL</saml2:Issuer>
   <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
   <ds:SignedInfo>
   <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
   <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
   <ds:Reference URI="#id3652322626225772431717045"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
   <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms>
   <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><ds:DigestValue>573cgF/mZF9POJh0zHAqqjvypbdPS1zUpo1Z7ls8ejI=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>S62Voi+Gs2Lz98jY9GysqEoilAcZUFSjbLSYCbqztT87dcPNDdt8Na74Jd7DTDQpLqUwM1Ak+QH+4Cb+LnaKf3k9/76u8nl029ns8cJy0fCWa8Cnq2s1im7tSVzzPu1jZHg4AqFtXjr6Hk45dPkq3KW1tINUvobOYuX1aU1X3JhEqPT/dVR/05SG/WLj00pqOBRI2NkbaDd9re28Ymb5josYMYAgIbaTby4ePkGlp2iryh2FrbuDB7i/f+qpgJ3ltZqEEr1SCZ08oEKrWr6K/lXx/WO3k/xzINbe5mauUoymdkbfKzxU+MM6o6oZqPmyvdlSqpYeb+l5tRD9pGZ0vw==</ds:SignatureValue><ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIIDnDCCAoSgAwIBAgIGAYqXjkQaMA0GCSqGSIb3DQEBCwUAMIGOMQswCQYDVQQGEwJVUzETMBEG
   ...
   ...

Session Affinity and Confluence DC

In a Confluence DC instance with 2 or more nodes, when the SP sends SAMLRequest (step 3 above), it also saves the ID attribute of the Request in the local session. When Confluence receives the SAML <Response> (step 7 above), it verifies that the InResponseTo attribute is equal to the local ID saved earlier.

The following entry can be found in the DEBUG logs when the login session is saved in one specific Confluence node: 

2023-10-10 09:48:28,000 DEBUG [http-nio-8090-exec-84 url: /plugins/servlet/external-login/1; user: admin] [authentication.impl.web.SessionDataService] setSessionData Saved login session data SessionData{authenticationRequest=com.atlassian.plugins.authentication.impl.web.saml.provider.SamlRequest@5e70a9c8[id=ONELOGIN_a67bead3-dd5f-4cef-a616-b68298876380,loginRequestUrl=https://IDP_PROVIDER_URL/.../.../sso/saml?SAMLRequest=fVLLbsIwEPyVyPeQp4BYBImWPpAoIEh76AU5ZoGUxE69NkX9%2BppABT0UyZK165nRzMg9ZFVZ04HRWzGHTwOonUNVCqTNQ0qMElQyLJAKVgFSzeli8DKmYcuntZJaclmSK8ptBkMEpQspiDMapmQ6eRhPn0aTZRzxxE8S380DxtyYJ7HbjfzIzXMGftBer/MciPMGCi03JVbKCiAaGAnUTGi78sPIDXx7siCicZeGnXfiPErFoQmXEq2M1RjahIVgutHZal0j9TxWrRBlS%2B40a3FZeayuz7ulvbgU69KA4LAMPDjsOh9fBqGch9vge1O0k45ngd4xPHFm50ruCrEqxOZ2G/kJhPQ5y2bubLrIiDP4beheCjQVqAWofcHhdT6%2B%2BL04all/jeW6NJtCoGfZ%2BxJ0Y4efJUi/dxxp05jq/6/S865xp%2Bnv5%2Bj/AA%3D%3D&RelayState=6804f8f0-f463-4c5b-89ec-a7c7ef367d3f,relayState=6804f8f0-f463-4c5b-89ec-a7c7ef367d3f], targetUrl=null, idpConfigId=1} in user session: 996697F7DE07D6D8244CC9864B6DEA07 using key 6804f8f0-f463-4c5b-89ec-a7c7ef367d3f

If the SAML <Response> is received in a different node, the SSO flow is broken and the user will receive a message as "Something went wrong" in the Confluence UI. In most of the cases, this problem occurs because the load balancer redirects the SAML Response to a different node that doesn't have the ID attribute stored in the local session and then it is marked as invalid. 

2023-10-10 09:48:41,296 DEBUG [http-nio-8090-exec-275 url: /plugins/servlet/samlconsumer; user: admin] [onelogin.saml2.authn.SamlResponse] isValid SAMLResponse invalid --> 
<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response 
Destination="https://CONFLUENCE_URL/plugins/servlet/samlconsumer" 
ID="id3652322626225772431717045" InResponseTo="ONELOGIN_a67bead3-dd5f-4cef-a616-b68298876380" 
IssueInstant="2023-10-10T13:48:40.335Z" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
...
...

To avoid this situation, it is required to use Session affinity or "sticky sessions" to route requests from the same session to the same node in the cluster.  Our recommendation is to use Confluence cookies, which are issued by the Atlassian application itself.

The steps for implementing this feature in the Load Balancer (LB) side differ from vendor to vendor, but we suggest you strongly to check our official documentation about the required configuration in Confluence and Atlassian products: 

• Load balancer configuration options > Sticky Sessions
• Clustering with Confluence Data Center > Load Balancers

Troubleshooting and Support

There might be multiple factors that can trigger invalid SAML flows related to the LB configuration, such as: 

• Some customers prefer to use a cookie generated by the LB and, occasionally, some of these cookies might be blocked or not present in the request. 
• There are situations where the LB cookies are not preserved during the SAML flow, so we suggest you to test and validate the same scenario using Confluence application cookies. 
• The session persistence and the timeouts configured at LB level may have expired for long running Confluence sessions, which could potentially route the SSO response to a different node than the original session.  

If you and your Load Balancer team has ruled out the LB configuration as a root cause of the SSO issues, we strongly advice you to upgrade the SSO for Atlassian Server and Data Center App to the latest version available. 

If the issue is reproducible even with the latest version of this App, further troubleshooting will be necessary. Please, open a new case with Atlassian Support and we will help you further.