SSO with SAML: Overview
Vanilla has implemented the parts of the SAML 2.0 spec required for SSO. This is done by enabling the SAML SSO addon, and configuring it via its Settings page (Dashboard → Addons → SAML SSO → Settings button).
SAML accounts are mapped to existing forum accounts by email address, or a new account is created if no match is found.
Mapping Claims
Vanilla’s SAML mapping is as follows (the right value is the SAML key):
UniqueID => id
Name => uid
Email => mail
Photo => photo // Optional
Roles => roles // Optional
Be careful when mapping 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 could be:
<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 in your dashboard to be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
UniqueID is whatever you’re using to absolutely uniquely identify the user on your side that will never change.
Name is 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 is the url/path to the user’s photo and is optional.
Roles consist of a comma-separated list of exact name matches to existing roles on your forum and is optional. e.g. ‘Member,MVP,Support’
Creating a new SAML connection
When creating a new SAML connection you will need to fill the following fields:
Connection ID This field is the name of your connection and is 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 Found under the name: NameIDFormat. Looks like this “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 Identity Provider and is used to verify the signature on SAML responses. 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 need your users to log out of your Identity Provider (IDP) when they log out of your Vanilla forum, you may have to provide a public certificate to your IDP so that your IDP can verify that the log out request came from us. To do that, generate a private/public key pair. Paste them into the SP Private Key and SP Certificate fields of SAML Settings in the dashboard and send the SP Certificate to your IDP. Or generate the Metadata document and send it to your IDP.
Getting your metadata
Once the connection is created you will be able to get the Metadata for that particular connection by clicking on the link in the Instructions section at the top of the SAML Settings Form.
Example:
<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 its 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 please visit www.openssl.org.
Troubleshooting
If you find you are not able to connect try reading our SAML Troubleshooting docs.
