• Document Up to Date

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.

    Take note of the values of the following options used to generate your keystore that will be used later for configuring Engine:

    • alias: The value used for this option wil be used in the keystore.defaultCredential and keystore.credentials.credential.name properties

    • storepass: The value used for this option will be used in the keystore.password property

    • keypass: The value used for this option will be used in the keystore.credentials.credential.password property

  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<security>
 2   <saml2>
 3      <enable>true</enable>
 4      <reverseProxy>true</reverseProxy>
 5      <context>
 6        <forwardedProtoHeaderName>X-Forwarded-Proto</forwardedProtoHeaderName>
 7        <forwardedHostHeaderName>X-Forwarded-Host</forwardedHostHeaderName>
 8        <forwardedPortHeaderName>X-Forwarded-Port</forwardedPortHeaderName>
 9        <scheme>https</scheme>
10        <serverName>myproxy</serverName>
11        <serverPort>80</serverPort>
12        <contextPath>/app</contextPath>
13      </context>
14      <profile>
15        <passive>true</passive>
16        <forceAuthN>true</forceAuthN>
17        <includeScoping>false</includeScoping>
18      </profile>
19      <attributes>
20        <mappings>
21          <mapping>
22            <name>DisplayName</name>
23            <attribute>fullName</attribute>
24          </mapping>
25        </mappings>
26      </attributes>
27      <role>
28         <mappings>
29            <mapping>
30               <name>editor</name>
31               <role>ROLE_EDITOR</role>
32            </mapping>
33         </mappings>
34      </role>
35      <keystore>
36         <defaultCredential>my-site</defaultCredential>
37         <password>superSecretPassword</password>
38         <credentials>
39            <credential>
40               <name>my-site</name>
41               <password>anotherSecretPassword</password>
42            </credential>
43         </credentials>
44      </keystore>
45      <identityProviderName>My IDP</identityProviderName>
46      <serviceProviderName>Crafter Engine</serviceProviderName>
47   </saml2>
48</security>

Properties Details

Property
Description
Default Value

enable

Indicates if SAML2 is enabled or not

false

reverseProxy

Indicates if the site is running behind a reverse proxy or load balancer and the request to the IdP should use the context.* properties

false

context.forwardedProtoHeaderName

The name of the header for the protocol (set by the reverse proxy/load balancer)

X-Forwarded-Proto

context.forwardedHostHeaderName

The name of the header for the host (set by the reverse proxy/load balancer)

X-Forwarded-Host

context.forwardedPortHeaderName

The name of the header for the port (set by the reverse proxy/load balancer)

X-Forwarded-Port

context.scheme

The protocol to use http or https (overwrites the forwarded header)

context.serverName

The name of the server (overwrites the forwarded header)

context.serverPort

The port of the server (overwrites the forwarded header)

0

context.contextPath

The context path of the application

profile.passive

Sets the value for IsPassive in the SAML request

false

profile.forceAuthN

Sets the value for ForceAuthn in the SAML request

false

profile.includeScoping

Indicates if scoping element should be included in the requests sent to IdP

true

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. Each mapping is comprised of the original name of the attribute, sent by the IDP, and attribute which will be the new name of the attribute in Engine

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. Each mapping is comprised of the original name of the role, sent by the IDP, and role which will be the new name of the role in Engine

keystore.defaultCredential

The name of the default credential to use (should also be defined in keystore.credentials.credential)

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. Each credential is comprised of a name and a password

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
1cd <PATH TO SITE REPOSITORY>
2mkdir config/engine/saml2
3cp ~/keystore.jks config/engine/saml2/
4cp ~/idp.xml config/engine/saml2/
5cp ~/sp.xml config/engine/saml2
6git add .
7git 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.