Engine SAML2 Configuration Enterprise only feature

Note

This guide includes SAML2 specific configuration only, for a general guide see Engine Site Security Guide

Crafter Engine can be configured to support SAML2 SSO out of the box without using any additional plugin.

Requirements

  1. A SAML2 compatible Identity Provider properly configured, this configuration will not be covered here

  2. A Java KeyStore file containing all needed keys & certificates, this can be generated with the Java Keytool or any other compatible tool. For example:

    keytool -genkey -alias CREDENTIAL_NAME -keystore keystore.jks -storepass STORE_PASSWORD

    Note

    Some versions of the Keytool support a different password for the keystore and the key generated, you will be prompted for one or you can add the -keypass KEY_PASSWORD parameter.

  3. XML descriptors for the Identity Provider and the Service Provider (Crafter Engine). The descriptor for Crafter Engine can be generated following these steps:

    1. Export the X509 certificate from the key store file:

      keytool -export -alias CREDENTIAL_NAME -keystore keystore.jks -rfc -file CREDENTIAL_NAME.cer

    2. Create the XML descriptor, either using a third party tool or manually. The descriptor should look like this:

      Example SAML 2.0 Service Provider Metadata
      <?xml version="1.0" encoding="UTF-8" standalone="no"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="<Entity ID>">
        <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" 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><Certificate></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><Certificate></ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
          </md:KeyDescriptor>
          <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="<Logout URL>"/>
          <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
          <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<SAML URL>" index="0" isDefault="true"/>
        </md:SPSSODescriptor>
      </md:EntityDescriptor>
      

      Replacing the following values:

      • Entity ID: Unique identifier for the service provider

      • AuthnRequestsSigned: indicates if the service provider will sign authentication requests

      • WantAssertionsSigned: indicates if the service provider requires signed assertions

      • Certificate: The content of the certificate obtained in the previous step

      • Logout URL: The full URL for the service provider logout endpoint (ENGINE_URL/saml/logout)

      • SAML URL: The full URL for the service provider SSO processing endpoint (ENGINE_URL/saml/SSO)

Note

If Crafter Engine will be behind a load balancer or proxy server, the XML Service Provider descriptor needs to use the public URL for the Identity Provider to be able to communicate

Update the Site Configuration

SAML2 authentication can be enabled by updating the site configuration to include the following properties:

Example SAML2 configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<security>
   <saml2>
      <enable>true</enable>
      <attributes>
        <mappings>
          <mapping>
            <name>DisplayName</name>
            <attribute>fullName</attribute>
          </mapping>
        </mappings>
      </attributes>
      <role>
         <mappings>
            <mapping>
               <name>editor</name>
               <role>ROLE_EDITOR</role>
            </mapping>
         </mappings>
      </role>
      <keystore>
         <defaultCredential>my-site</defaultCredential>
         <password>superSecretPassword</password>
         <credentials>
            <credential>
               <name>my-site</name>
               <password>anotherSecretPassword</password>
            </credential>
         </credentials>
      </keystore>
      <identityProviderName>My IDP</identityProviderName>
      <serviceProviderName>Crafter Engine</serviceProviderName>
   </saml2>
</security>

Properties Details

Property
Description
Default Value

enable

Indicates if SAML2 is enabled or not

false

attributes.mappings.mapping

List of mappings to apply for attributes, every attribute sent by the IDP will be compared against this list and will be available as described in Access User Attributes

role.key

Name of the role attribute sent by the IDP

Role

role.mappings.mapping

List of mappings to apply for roles, every role sent by the IDP will be compared against this list

keystore.defaultCredential

The name of the default credential to use

keystore.path

The path of the keystore file in the repo

/config/engine/saml2/keystore.jks

keystore.password

The password of the keystore file

keystore.credentials.credential

List of credentials in the keystore

identityProviderName

The name of the identity provider to use

identityProviderDescriptor

The path of the identity provider metadata XML descriptor in the repo

/config/engine/saml2/idp.xml

serviceProviderName

The name of the service provider to use

serviceProviderDescriptor

The path of the service provider metadata XML descriptor in the repo

/config/engine/saml2/sp.xml

Note

If your keystore does not support different passwords for each key, then you should use the same value provided for -storepass in keystore.password and keystore.credentials.credential.password

Commit the required files

You will need to add & commit the keystore and descriptor files manually to the site repository, the location will depend on the configuration used. The following example uses the default locations:

Adding the SAML2 files
1
2
3
4
5
6
7
cd <PATH TO SITE REPOSITORY>
mkdir config/engine/saml2
cp ~/keystore.jks config/engine/saml2/
cp ~/idp.xml config/engine/saml2/
cp ~/sp.xml config/engine/saml2
git add .
git commit -m "Add SAML2 config files"

After completing those steps you should be able to test the SAML2 authentication, if there are no configuration or communication errors you will be redirected to the SSO login page when trying to access a secured page and then automatically return to your site in Crafter Engine.

Note

If you are configuring SAML2 authentication in an authoring environment, you need to make sure that your IDP is configured to allow the login to be displayed in an iframe element by setting the right values for the Content-Security-Policy header. You can find more information here.