If you are trying so set up Single Sign-On using Vanilla's SAML SSO plugin against your own authentication provider or a third-party authentication provider you will find that there are a many possible points of failure. SAML is a very secure method of authentication and, as such, requires a very precise configuration and is not necessarily easy to troubleshoot. This document tries to expose the sources of the pain points, and what can be done.
SAML Overview
SAML is an acronym for Security Assertion Markup Language. It is a protocol for exchanging user data securely between a Service Provider (in our case Vanilla) and an Identity Provider (either your authentication server or a third-party server that you are using). SAML delivers the data in XML document containing Assertions. Assertions are claims, or data, concerning the user being authenticated.
The Basic SAML 2.0 Flow
ONE: On a Vanilla site a user will click on the 'Sign In' prompt. The browser will be instantly redirected to the sign in page of the Identity Provider that you have configured in the SAML addon in the Vanilla Dashboard with the GET variable "SAMLRequest". The SAMLRequest is a compressed, base64encoded XML document that tells the Identity Provider which Service Provider is making the request.
TWO: The Identity Provider presents the user with a Sign In form. Once the user has been authenticated, the Identity Provider POSTs back the Response to the ReturnURL. The Response, like the SAMLRequest, is a compressed, base64encoded, signed XML document with either an error message or, if successful, all the 'Assertions' (also known as 'Claims' or user data) for the user.
THREE: The Service Provider (Vanilla) will decode the SAMLResponse, read the Assertions, verify the signature and translate the Assertions into useable data for either starting a session for an existing (by matching the UniqueID or, if there isn't one, the Email in the Assertions with an existing user), or creating a new user.
For more information on how to configure your Vanilla SAML Single Sign On connection you should read this article.
Troubleshooting
You may want to ask your Customer Success Manager to turn on the DB Logger addon so that you can create and see the Event Logs. If you find there are too many logs, try filtering the Event Logs on saml_response .
Common Error Messages
The SAML response was not valid.
This is a generic error that covers multiple possible points of failure. It could be:
- The signature could not be located in the Response.
- No References node was found in the Response. The Response node is expected to be found as a child of the SignedInfo node.
- Your Response has more than one set of Assertions. Vanilla expects everything to be the child of one Assertion node.
- Timing issues. SAML Responses MUST have 'NotBefore' and 'NotOnOrAfter' values that protect from replay attacks. Possibly your server's clocks are not properly synchronized.
Invalid Certificate
The IDP Certificate configured in the SAML Addon in the Dashboard MUST be a valid x509 Certificate. If your connections are failing you can test your certificate using OpenSSL's command line utility. If your certificate is called certificate.crt perform the following command:
openssl x509 -in certificate.crt -pubkey -noout -outform pem
Missing Email or Name
You may be passing the Email or Name in your SAML response, and yet users are still prompted to enter and Email or a Name to identify themselves on the forum.
Click on the Event Log link under Technical in the Dashboard's left hand menu (if you don't have one, contact support). Filter on "saml_response_received" to see what is being passed. Make sure the saml:Attribute Names are mapped properly in the SAML Addon. The Name attribute has to be an exact match. If this is what is being passed:
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/photo" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string"></saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">johndoe@gmail.com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">JohnDoe</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
Then in the SAML Addon you would have to map the names like this:
