There are many scenarios where it's useful for a site to have a single sign-on (SSO) authentication system. Ingeniux CMS 9.0 supports SSO via SAML (Secure Assertion Markup Language), a federated, asynchronous authentication protocol. Ingeniux CMS supports SAML 2.0, for both SSO and single logout (SLO) configurations. The CMS supports ADFS, Azure AD, Ping, Okta, Shibboleth, and Salesforce based SAML 2.0 identity providers for authentication.

When a site uses SAML as its authentication protocol, the CMS acts as a service provider (SP) that validates against an identity provider (IdP) that contains users' credentials. This IdP can be any number of sources, and its exact configuration varies by provider. Each user that is authenticated via SAML SSO must also be configured as a user in the CMS and be a member of a group.

Once an IdP has been configured, there are two files that must be configured to start using SAML: saml.config and local-membership.config. 

Configuration of saml.config

Located in the \site\ folder, saml.config needs to be configured with the values provided from your IdP vendor. Sometimes, these are supplied in an XML format called metadata and other systems provide them online.

The saml.config file installed with the CMS contains two main areas that require configuration:

1. The root ServiceProvider element has Name, Description, and AssertionConsumerServiceUrl values that an IdP will require for configuring SSO. The AssertionConsumerServiceUrl is always in the format "https://path-to-cms-instance/SAML/AssertionConsumerService". The AssertionConsmerServiceUrl is sometimes referred to as the "Single Sign On URL" in other IdP systems.
2. Several PartnerIdentityProvider elements, which are examples of different types of IdP authentication sources. Ingeniux CMS supports multiple IdP sources in one configuration.

The following is an example of an Okta configuration with SingleLogOut configured. Note the Okta-specific values that need to be captured from the Okta configuration:

<?xml version="1.0"?>
<SAMLConfiguration xmlns="urn:componentspace:SAML:2.0:configuration">
    <ServiceProvider Name="IngeniuxCMS"
        Description="Ingeniux CMS Site"
        AssertionConsumerServiceUrl="~/SAML/AssertionConsumerService"/>
    
    <PartnerIdentityProviders>
        
        ...
        
        <!-- Okta -->
        <PartnerIdentityProvider Name="http://www.okta.com/exk5xsht7oII4vg2R0h7"
                             Description="Okta"
                             SignAuthnRequest="true"
							 SignLogoutRequest="true"
                             WantSAMLResponseSigned="true"
                             WantAssertionSigned="false"
                             WantAssertionEncrypted="false"
                             DigestMethod="http://www.w3.org/2001/04/xmlenc#sha256"
                             SignatureMethod="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
                             SingleSignOnServiceUrl="https://dev-144911.oktapreview.com/app/componentspacedev144911_exampleserviceprovider_1/exk5xsht7oII4vg2R0h7/sso/saml"
							 SingleLogoutServiceUrl="https://dev-144911.oktapreview.com/app/componentspacedev144911_exampleserviceprovider_1/exk5xsht7oII4vg2R0h7/slo/saml"
							 SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                             PartnerCertificateFile="Certificates\okta.cer"/>
        
        ...
        
    </PartnerIdentityProviders>
</SAMLConfiguration>

If your IdP requires a signature certificate for SAML requests, you can configure the ServiceProvider element block with the LocalCertificateFile and LocalCertificatePassword attributes for this scenario. When providing signature certificates for your IdP, it's recommended that you consult with your system administrator to find out which certificates are available for distribution and configuration within the CMS.

For IdPs that support SLO, you'll also need to provide the value for the Single Logout URL of your CMS. This value consists of the base URL of your CMS with the /SAML/SLOService path appended. An example is https://path-to-cms-instance/SAML/SLOService

Setting up local-membership.config

Each SAML IdP must be added as an ASP.NET membership provider in the \site\local-membership.config file. The XML node looks like this:

The name attribute is used as the provider name and label when selecting an authentication method from the Log in to menu on the CMS login page. As with any other provider configured for Ingeniux CMS, it can be used as the defaultProvider value; this attribute is ocated near the top of local-membership.config.

The idpPartner attribute keys to the name of the partner attribute within your configured saml.config file. In the Okta example from above, it would be:

After deploying these changes, the CMS application pool must be recycled.

Other Notes

If you configure Ingeniux CMS with SAML as the only provider and also set as the defaultProvider value, the user is automatically redirected to the SAML login page.

To troubleshoot SAML login issues, you can enable SAML logging by adding the following XML to your CMS web.config. This creates an idp.log file at your CMS site root's App_Data/DesignTimeLogs folder path, which can be modified via the initializeData attribute: