SSO with SAML: Overview
Vanilla has implemented the parts of the SAML 2.0 specification that are required for SSO. This is done by enabling the SAML SSO addon and configuring its Settings (Dashboard > Addons > SAML SSO > Settings button).
SAML accounts are mapped to existing forum accounts by email address. If a matching account is not found, a new account is created; this is known as Just-In-Time Provisioning (JIT).
Mapping claims
The Vanilla SAML addon offers the ability to map most of the claims that your Identity Provider (IDP) sends to match Vanilla's user profile requirements. Vanilla's SAML mapping is as follows (the values on the right side are the defaults that you can configure):
UniqueID => id
Name => uid
Email => mail
Photo => photo // Optional
Roles => roles // Optional
Be careful when mapping claims. Your IDP might use Claim Types in the Names of claims. Often, your SAML Authentication Provider interface will indicate that the Name of a claim is, for example, "emailaddress" but in reality, what is being passed in the SAML XML Response for the user is:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
For example:
<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>
You should, therefore, configure the Email field in the SAML addon as:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- UniqueID - the only claim you cannot configure in the Vanilla addon. The UnqueID that Vanilla extracts from your SAML response is the NameID value.
- Name - the username. We recommend keeping it within the normal rules (alphanumerics and underscores only, 50-character limit, must be unique) but we do not validate its formatting on our side over SSO because we don’t want to fail a login. It would just make @mentions impossible to use if it had spaces or special characters in it. However, in the case where there’s a duplicate name or none provided, it will send the user to a “Connect” page to provide a valid, unique username which will then also be validated for formatting.
- Email - is not validated on our side either. In general, we are assuming you’ve done the data validation on your side and adding more would gum up the works.
- Photo - the URL/path to the user’s photo; this is optional.
- Roles - consist of a comma-separated list of exact name matches to existing roles on your forum and is optional (for example, ‘Member,MVP,Support’). By default, Vanilla will re-assign the users' roles every time they log in via SSO, giving your authentication provider full control over the users' roles. Cloud customers who want to be able to assign roles to users in the Vanilla Dashboard and have roles added over SSO can ask support to configure their forum to work in this way.
For information on passing roles via SSO, see:
Creating a new SAML connection
When creating a new SAML connection, complete the following fields:
- Connection ID The name of your connection; used to distinguish it from other potential SSO connections.
- Entity ID The name of your SAML entity. It can be anything but is often the URL of your site.
- Site Name A short name for the site. This is displayed on the SSO Sign In button.
- Sign In URL Sign In URL that users will be redirected to.
- Sign Out URL Sign Out URL that users will be redirected to.
- Registration URL URL that users will be redirected to create a new account.
- IDP Certificate Certificate of your provider.
- Identifier Format This is found under the name NameIDFormat and resembles urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified
Certificates
There are three certificates that can be configured into your SAML connection. One is essential, the other two are optional.
IDP Certificate (required): This is a public certificate generated by your IDP and is used to verify the signature on SAML response for Single Sign On. Ask your identity provider if you don't know where to get it. For example, at Auth0, it can be found in the Advanced settings of your Authentication Application:
SP Private Key and SP Certificate: If you want your users to log out of your IDP when they log out of your Vanilla forum (Single Log Out, SLO), you have to provide a public certificate to your IDP so that your IDP can verify that the log-out request came from us and so that we can verify that a Sign Out Request coming from your IDP is valid. To do this:
- Generate a private/public key pair.
- Paste them into the SP Private Key and SP Certificate fields of SAML Settings in the Dashboard.
- Send the SP Certificate to your IDP.
Or generate the Metadata document and send it to your IDP.
Getting your metadata
Since your Metadata document contains information about your connection, you can only access the Metadata once the connection is created.
Here is an example of a metadata document without the SP Certificate:
<?xml version="1.0"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="$validUntil" entityID="{$this->_settings->spIssuer}"> <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="{$this->_settings->spReturnUrl}" index="1"/> </md:SPSSODescriptor></md:EntityDescriptor>
Here is an example of a metadata document with the SP Certificate:
<md:EntityDescriptor entityID="2EfeCyTcI5WuCqE46qHzJlTyCJ7qd4eD" validUntil="2025-11-24T20:37:38Z" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"><md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIICszCCA....6L9bELqYc37DNA7O4g=</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:KeyDescriptor use="encryption"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIICszCCA....6L9bELqYc37DNA7O4g=</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://dev.vanilla.localhost/entry/signout"/><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</md:NameIDFormat><md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dev.vanilla.localhost/entry/connect/saml?authKey=secondsaml" index="1"/></md:SPSSODescriptor></md:EntityDescriptor>
Generating x509 Private-Public Key pair
There are many ways of generating x509 Private-Public Key pairs. You can install Open SSL on any Mac, Linux, Unix, Windows environment and use it's command line tool. Create a directory on your personal computer, cd into it type:
openssl genrsa -out private.key 1024
to generate a private key and then,
openssl req -new -x509 -key private.key -out publickey.cer -days 365
to generate the the public certificate. You will be prompted to add information concerning your organization. When you are finished, do an ls you should have two files: private.key and publickey.cer open them and copy their contents into the SP Private Key and SP Certificate respectively.
For more information on certificates, visit www.openssl.org.
Seamless connection from your app to Vanilla
If you have users logged into your web application and you want to provide a link from your application to your Vanilla application without prompting them to login again route your users through:
https://[your-forum-domain]/entry/saml/[your-client-id]
Auto-connect
If you want a user to be able to log in through SSO and connect them with their existing user account on Vanilla, you can. Not all of our settings are accessible through user interface. The auto-connect setting can be set by contacting your CSM or support.
🛑 WARNING: Do not use auto-connect if your users can change their email addresses on your authentication application without being verified. This could allow them to choose an email address that already exists on the forum and then log in as that forum user.
Single Sign Out (SLO)
You may want your users to log out of the IDP when they log out of the Vanilla application and to log out of the Vanilla application whenever they log out of the IDP. This is known as Single Sign-Out. The idea here is if you have multiple applications using your IDP to authenticate sessions; for example your application, your blog, and your forum. When a user logs into your application through the IDP they can now connect to the forum or the blog without logging in again. Now when the user logs out of the forum you will want them to be logged out of the blog and your application as well.
In order to implement this behaviour on your Vanilla application, you must configure several things in your SAML addon in the Vanilla Dashboard.
- The Sign Out URL to point to the sign out endpoint of your IDP.
- Make sure that Make this connection your default signin method. is checked so that there is only one method of logging in and out.
- SP Private Key To verify the signature of Log Out Requests coming from your IDP (see Certificates).
- SP Certificate a public certificate that you give to your IDP for signing Log Out Requests (see Certificates).
- Make sure that Only sign out with valid SAML logout requests. is checked.
Your IDP has to know where to send Log Out Requests on the forum, the binding, the NameID format, and the public certificate from your Vanilla SAML addon configuration. All of this is available above in Getting your metadata. As you will see in your metadata, the SingleLogoutService binding is an HTTP-Redirect, which means that we only accept GET requests for signing out.
Troubleshooting
If you are not able to connect, check out:
