SAML SSO - Vanilla Success
<main> <article class="userContent"> <h2 data-id="sso-with-saml%3A-overview">SSO with SAML: Overview</h2><p>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).</p><p>SAML accounts are mapped to existing forum accounts by <strong>email address</strong>, or a new account is created if no match is found.</p><h2 data-id="mapping-claims">Mapping Claims</h2><p>Vanilla’s SAML mapping is as follows (the right value is the SAML key):</p><pre class="code codeBlock" spellcheck="false" tabindex="0">UniqueID => id Name => uid Email => mail Photo => photo // Optional Roles => roles // Optional </pre><p>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:</p><pre class="code codeBlock" spellcheck="false" tabindex="0"><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> </pre><p>You should, therefore, configure the Email field in the SAML Addon in your dashboard to be: <code class="code codeInline" spellcheck="false" tabindex="0">http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</code>. </p><p><code class="code codeInline" spellcheck="false" tabindex="0">UniqueID</code> is whatever you’re using to absolutely uniquely identify the user on your side that will never change.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Name</code> 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.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Email</code> 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.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Photo</code> is the url/path to the user’s photo and is optional.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Roles</code> consist of a comma-separated list of exact name matches to existing roles on your forum and is optional. e.g. ‘Member,MVP,Support’. By default Vanilla will re-assign the user's roles every time they log in over SSO, giving your authentication provider full control over the user's roles. Cloud customers who want to be able to assign roles to users in the Vanilla Dashboard <strong>and</strong> have roles <strong>added</strong> over SSO can ask support to configure their forum to work in this way. For more details on passing roles over SSO <a href="https://success.vanillaforums.com/kb/articles/179-managing-roles-with-sso" rel="nofollow noreferrer ugc">please see this article</a>.</p><h2 data-id="creating-a-new-saml-connection">Creating a new SAML connection</h2><p>When creating a new SAML connection you will need to fill the following fields:</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Connection ID</code> This field is the name of your connection and is used to distinguish it from other potential SSO connections.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Entity ID</code> The name of your SAML entity. It can be anything but is often the URL of your site.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Site Name</code> A short name for the site. This is displayed on the SSO Sign In button.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Sign In URL</code> Sign In URL that users will be redirected to.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Sign Out URL</code> Sign Out URL that users will be redirected to.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Registration URL</code> URL that users will be redirected to create a new account.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">IDP Certificate</code> Certificate of your provider.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">Identifier Format</code> Found under the name: NameIDFormat. Looks like this “urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified”</p><h2 data-id="certificates">Certificates</h2><p>There are three certificates that can be configured into your SAML connection. One is essential, the other two are optional.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">IDP Certificate</code> (required): This is a public certificate generated by your Identity Provider and is used to verify the signature on SAML response for <strong>Single Sign On.</strong> 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:</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/A357CBD5ULYC/screen-shot-2020-11-24-at-2-50-34-pm.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/A357CBD5ULYC/screen-shot-2020-11-24-at-2-50-34-pm.png" alt="Screen Shot 2020-11-24 at 2.50.34 PM.png" height="756" width="1604" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p><code class="code codeInline" spellcheck="false" tabindex="0">SP Private Key </code>and <code class="code codeInline" spellcheck="false" tabindex="0">SP Certificate</code> : If you need your users to log out of your Identity Provider (IDP) when they log out of your Vanilla forum (<strong>Single Log Out</strong>, or SLO), you will 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 an Sign Out Request coming from your IDP is valid. To do that, generate a private/public key pair. Paste them into the <code class="code codeInline" spellcheck="false" tabindex="0">SP Private Key</code> and <code class="code codeInline" spellcheck="false" tabindex="0">SP Certificate</code> fields of SAML Settings in the dashboard and send the <code class="code codeInline" spellcheck="false" tabindex="0">SP Certificate</code> to your IDP. Or generate the Metadata document and send it to your IDP.</p><h2 data-id="getting-your-metadata">Getting your metadata</h2><p>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.</p><p>Example:</p><pre class="code codeBlock" spellcheck="false" tabindex="0"><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> </pre><h2 data-id="generating-x509-private-public-key-pair">Generating x509 Private / Public Key Pair</h2><p>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:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">openssl genrsa -out private.key 1024 </pre><p>to generate a private key and then, </p><pre class="code codeBlock" spellcheck="false" tabindex="0">openssl req -new -x509 -key private.key -out publickey.cer -days 365 </pre><p>to generate the the public certificate. You will be prompted to add information concerning your organization. When you are finished, do an <code class="code codeInline" spellcheck="false" tabindex="0">ls</code> you should have two files: <code class="code codeInline" spellcheck="false" tabindex="0">private.key</code> and <code class="code codeInline" spellcheck="false" tabindex="0">publickey.cer</code> open them and copy their contents into the <code class="code codeInline" spellcheck="false" tabindex="0">SP Private Key</code> and <code class="code codeInline" spellcheck="false" tabindex="0">SP Certificate</code> respectively.</p><p>For more information on certificates please visit <a href="https://www.openssl.org/" rel="nofollow noreferrer ugc">www.openssl.org.</a></p><h2 data-id="seamless-connection-from-your-app-to-vanilla">Seamless Connection From Your App to Vanilla</h2><p>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:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">https://[your-forum-domain]/entry/connect/saml?authKey=[your-client-id] </pre><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/X8GDH0XLR2EO/screen-shot-2021-05-10-at-4-18-27-pm.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/X8GDH0XLR2EO/screen-shot-2021-05-10-at-4-18-27-pm.png" alt="Screen Shot 2021-05-10 at 4.18.27 PM.png" height="288" width="446" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="auto-connect">Auto-connect</h2><p>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.</p><p><strong>A word of caution</strong>: if your users can change their email addresses on your authentication application without being verified do not use auto-connect. This could allow them to choose an email address that already exists on the forum allowing them to log in as that forum user.</p><h2 data-id="single-sign-out-(slo)">Single Sign Out (SLO)</h2><p>You may want your users to log out of the identity provider (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 <strong>into</strong> your application through the IDP they can now connect to the forum or the blog without logging in again. Now when the user logs <strong>out</strong> of the forum you will want them to be logged out of the blog and your application as well.</p><p>In order to implement this behaviour on you Vanilla application you need to configure several things in your SAML addon in the Vanilla Dashboard.</p><ol><li>The <strong>Sign Out URL</strong> to point to the sign out endpoint of your IDP.</li><li>"<strong>Make this connection your default signin method.</strong>" checked so that there is only one method of logging in or out.</li><li><strong>SP Private Key </strong>To verify the signature of Log Out Requests coming from your IDP (see <a href="https://success.vanillaforums.com/kb/articles/32#certificates" rel="nofollow noreferrer ugc">Certificates</a>).</li><li><strong>SP Certificate, </strong>a public certificate that you give to your IDP for signing Log Out Requests (see <a href="https://success.vanillaforums.com/kb/articles/32#certificates" rel="nofollow noreferrer ugc">Certificates</a>).</li><li>"<strong>Only sign out with valid SAML logout requests.</strong>" checked.</li></ol><p>Your IDP will need 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 in the Meta Data document (<a href="https://success.vanillaforums.com/kb/articles/32#getting-your-metadata" rel="nofollow noreferrer ugc">see above</a>).</p><h2 data-id="troubleshooting">Troubleshooting</h2><p>If you find you are not able to connect try reading our <a href="https://success.vanillaforums.com/kb/articles/130-troubleshooting-saml-connections" rel="nofollow noreferrer ugc">SAML Troubleshooting docs.</a></p> </article> </main>