How to set-up Single Sign-On using SAML

Getting SSO setup requires an in depth understanding of the technical framework being used and how it should be configured. The following is an in-depth explanation on how to setup Single Sign On (SSO) via SAML 2.0

In an SSO configuration, the standard Zapnito log in and registration user journeys are disabled and delegated to another system. In such cases, the Zapnito community site delegates it’s responsibility for authentication and account confirmation to your chosen Identity Provider (IDP) system.

Some SSO Background

This article will use standard terminology that is often used in an SSO setup. Here are some important concepts to cover off before we delve into how to actually setup SSO with SAML:

Identity Provider (IDP) – this is the system which is retains the primary responsibility for managing the identity of the end user. This means it knows how to verify that the user is who they say they are, i.e. it knows how to authenticate the user.   

To do this you must:

• know the username and password of the user
• allow the user to confirm their identity via a login process
• allow the user to create a new account via a new account registration process
• allow the user to reset their password
• allow the user to confirm ownership of their email address

Often the IDP is a capability within a Content Management System (CMS) or Customer Relationship Management (CRM) tool, or as is more often the case it could actually be a dedicated IDP platform in its own right. Examples include Salesforce Identity, OneLogin and Auth0.

Service Provider (SP) – the Service Provider is the platform that is responsible for serving the content, or providing the end service, and relies on the IDP to provide user authentication services and account setup services as described above. In an SSO configuration the Zapnito platform does not host any login or registration forms. As soon as a visitor tries to login or register they are redirected back to the IDP login and registration forms.

SAML SSO Setup Fundamentals

Step 1 - Add your Zapnito site as a Service Provider in the IDP

Your Zapnito expert community site will need to be setup as a Service Provider under the SAML IDP configuration. The Service Provider metadata is available at the following URL if you have SAML SSO switched on: https://[your-domain.com]/user...

From the Service Provider metadata:

• The entityId attribute in the EntityDescriptor element must be:
  entityID="https://[your-domain.com]"
  
  
• The NameId format must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, for example:

  <nameid format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
  fred@my-company.com
  </nameid>

• The Assertion Consumer Service callback should be:

  <md:assertionconsumerservice 
  binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
  location="https://[your-domain.com]/users/auth/saml/callback"
  index="0" isdefault="true"></md:assertionconsumerservice>

• There must also be three attributes returned in the SAML Response Assertion, these provide the first name, last name and email address of the user that is logging in. These must use the correct name attributes listed below in order for them to mapped correctly.
  

  <attributestatement>
    <attribute name="urn:oid:0.9.2342.19200300.100.1.3">
      <attributevalue>fred@my-company.com</attributevalue>
    </attribute>
    <attribute name="urn:oid:2.5.4.42">
      <attributevalue>Fred</attributevalue>
    </attribute>
    <attribute name="urn:oid:2.5.4.4">
      <attributevalue>Perry</attributevalue>
    </attribute>
  </attributestatement>

Below is a full example SAML Response that needs to be returned for a successful login.

<?xml version="1.0"?>
<samlp:response destination="https://[your-domain.com]/users/auth/saml/callback" id="_a0f12d0362a2ca93" inresponseto="_e32e240f-0fd68e104e2" issueinstant="2019-04-11T09:52:26Z" version="2.0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml:issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://idp-url.com</saml: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:canonicalizationmethod>
            <ds:signaturemethod algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:signaturemethod>
            <ds:reference uri="#_a0f123fa8003d0362a2ca93">
                <ds:transforms><ds:transform algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:transform><ds:transform algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:transform></ds:transforms><ds:digestmethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:digestmethod>
                <ds:digestvalue>LtqLVH9tAF2E0wxoc=</ds:digestvalue>
            </ds:reference>
        </ds:signedinfo>
        <ds:signaturevalue>a0ziDeY9VIkrqYbdmExPRl9i6JI60goDKciKI=</ds:signaturevalue>
        <ds:keyinfo>
            <ds:x509data>
                <ds:x509certificate>MIIDWzCCAkKgAwIBesRNaxDHXqM=</ds:x509certificate>
            </ds:x509data>
        </ds:keyinfo>
    </ds:signature>
    <samlp:status><samlp:statuscode value="urn:oasis:names:tc:SAML:2.0:status:Success"></samlp:statuscode></samlp:status>
    <assertion id="_450effff294caafae38c5213d5c7d49c8a21bc86b6" issueinstant="2019-04-11T09:52:26Z" version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
        <issuer>https://idp-url.com</issuer>
        <subject>
            <nameid format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">fred@my-company.com</nameid>
            <subjectconfirmation method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><subjectconfirmationdata inresponseto="_e32e240f-0fd6-04e2" notonorafter="2019-04-11T09:53:26Z" recipient="https://[your-domain.com]/users/auth/saml/callback"></subjectconfirmationdata></subjectconfirmation>
        </subject>
        <conditions notbefore="2019-04-11T09:52:26Z" notonorafter="2019-04-11T09:53:26Z">
            <audiencerestriction>
                <audience>https://[your-domain.com]</audience>
            </audiencerestriction>
        </conditions>
        <attributestatement>
            <attribute name="urn:oid:0.9.2342.19200300.100.1.3">
                <attributevalue>fred@my-company.com</attributevalue>
            </attribute>
            <attribute name="urn:oid:2.5.4.42">
                <attributevalue>Fred</attributevalue>
            </attribute>
            <attribute name="urn:oid:2.5.4.4">
                <attributevalue>Perry</attributevalue>
            </attribute>
        </attributestatement>
        <authnstatement authninstant="2019-04-11T09:42:26Z" sessionindex="_some_session_index">
            <authncontext>
                <authncontextclassref>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</authncontextclassref>
            </authncontext>
        </authnstatement>
    </assertion>
</samlp:response>

Step 2 - Send your Identity Provider configuration back to Zapnito Support

Once you have completed Step 1 above, please send the following details back to us at support@zapnito.com to complete the setup.

1. IDP Login URL
2. IDP Registration URL
3. IDP Password reset URL
4. IDP SSO Target URL (once SP has been setup)
5. IDP x.509 Certificate