• Document Up to Date
  • Since 4.0.3

Engine SAML2 Configuration Enterprise only feature

Since 4.0.3

Important

This document only applies to CrafterCMS version 4.0.3 and later
Please see here for version 4.0.2 and earlier.

Note

This guide includes SAML2 specific configuration only, for a general guide see Engine Project 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 private key and certificate. This can be generated like so:

    openssl req -newkey rsa:2048 -nodes -keyout rp-private.key -x509 -days 365 -out rp-certificate.crt

    Take note of the values of the following options used to generate your key and certificate that will be used later for configuring Crafter Engine:

    • keyout: The value used for this option wil be used in the crafter.security.saml.rp.privateKey.location property

    • out: The value used for this option will be used in the crafter.security.saml.rp.certificate.location property

Update the Project Configuration

To configure Engine SAML2, in your Delivery installation, we need to enable SAML security then we’ll setup the required SAML configuration properties.

To enable SAML security, go to CRAFTER_HOME/bin, open the crafter-setenv.sh file and uncomment the line export SPRING_PROFILES_ACTIVE=crafter.engine.samlSecurity:

CRAFTER_HOME/bin/crafter-setenv.sh
# -------------------- Spring Profiles --------------------
...
# Uncomment to enable SAML security
export SPRING_PROFILES_ACTIVE=crafter.engine.samlSecurity
# For multiple active spring profiles, create comma separated list

Next we’ll setup SAML configuration properties. Go to CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension and add/uncomment the following lines to server-config.properties (of course, make any appropriate configuration changes according to your system):

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties
 1#############################
 2# SAML2 Security Properties #
 3#############################
 4# SAML attributes mapping
 5crafter.security.saml.attributes.mappings=DisplayName:fullname,Avatar:profilePicture
 6# SAML roles mapping
 7crafter.security.saml.roles.mappings=editor:ROLE_EDITOR
 8# SAML attribute role key
 9crafter.security.saml.attributeName.role=Role
10###############################################################
11##         SAML Security Relying Party (SP) configuration    ##
12###############################################################
13# {baseUrl} and {registrationId} are pre-defined macros and should not be modified
14# SAML relying party (SP) registration ID. {registrationId} macro will be replaced with this value
15crafter.security.saml.rp.registration.id=SSO
16# SAML relying party (SP) entity ID and metadata endpoint
17crafter.security.saml.rp.entity.id={baseUrl}/saml/metadata
18# SAML relying party (SP) login processing url. Must end with {registrationId}
19crafter.security.saml.rp.loginProcessingUrl=/saml/{registrationId}
20# SAML relying party (SP) assertion consumer service location. Must end with {registrationId}
21crafter.security.saml.rp.assertion.consumer.service.location={baseUrl}/saml/{registrationId}
22# SAML relying party (SP) assertion consumer service biding (POST or REDIRECT)
23crafter.security.saml.rp.assertion.consumer.service.binding=POST
24# SAML relying party (SP) logout URL
25crafter.security.saml.rp.logoutUrl=/saml/logout
26# SAML relying party (SP) single logout service location
27crafter.security.saml.rp.logout.service.location={baseUrl}/saml/logout
28# SAML relying party (SP) logout service binding (POST or REDIRECT)
29crafter.security.saml.rp.logout.service.binding=POST
30# SAML relying party (SP) metadata endpoint
31crafter.security.saml.rp.metadata.endpoint=/saml/metadata
32# SAML relying party (SP) private key location
33crafter.security.saml.rp.privateKey.location=classpath:crafter/engine/extension/saml/rp-private.key
34# SAML relying party (SP) certificate location
35crafter.security.saml.rp.certificate.location=classpath:crafter/engine/extension/saml/rp-certificate.crt
36###############################################################
37##      SAML Security Asserting Party (IdP) configuration    ##
38###############################################################
39# SAML asserting party (IdP) entity ID:
40crafter.security.saml.ap.entityId=https://ap.example.org/ap-entity-id
41# SAML asserting party (IdP) single sign on service location
42crafter.security.saml.ap.single.signOn.service.location=https://ap.example.org/sso/saml
43# SAML asserting party (IdP) single sign on service binding (POST or REDIRECT)
44crafter.security.saml.ap.single.signOn.service.binding=POST
45# SAML asserting party (IdP) logout service location
46crafter.security.saml.ap.single.logout.service.location=https://ap.example.org/slo/saml
47# SAML asserting party (IdP) logout service binding (POST or REDIRECT)
48crafter.security.saml.ap.single.logout.service.binding=POST
49# SAML asserting party (IdP) want authn request signed
50crafter.security.saml.ap.want.authn.request.signed=false
51# SAML asserting party (IdP) certificate location
52crafter.security.saml.ap.certificate.location=classpath:crafter/engine/extension/saml/idp-certificate.crt
53###############################################################
54##            SAML Security other configuration              ##
55###############################################################
56# SAML Web SSO profile options: authenticate the user silently
57crafter.security.saml.webSSOProfileOptions.passive=false
58# SAML Web SSO profile options: force user to re-authenticate
59crafter.security.saml.webSSOProfileOptions.forceAuthn=false

where

  • crafter.security.saml.attributes.mappings: 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

  • crafter.security.saml.roles.mappings: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

  • crafter.security.saml.rp.privateKey.location: The path of the relying party (SP) private key in the classpath

  • crafter.security.saml.rp.certificate.location: The path of the relying party (SP) certificate in the classpath

  • crafter.security.saml.ap.entityId: The asserting party (IdP) entity ID

  • crafter.security.saml.ap.single.signOn.service.location: The asserting party (IdP) single sign on URL

  • crafter.security.saml.ap.single.logout.service.location: The asserting party (IdP) single logout URL

  • crafter.security.saml.ap.certificate.location: The path of the asserting party (IdP) certificate in the classpath

  • crafter.security.saml.webSSOProfileOptions.passive: Indicates if user is authenticated silently

  • crafter.security.saml.webSSOProfileOptions.forceAuthn: Indicates if user will be forced to re-authenticate

The classpath is located in your CrafterCMS installation, under CRAFTER_HOME/bin/apache-tomcat/shared/classes. As shown in the example above, the relying party private key is located in your CrafterCMS installation under CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/saml folder.

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties
# SAML relying party (SP) private key location
crafter.security.saml.rp.privateKey.location=classpath:crafter/engine/extension/saml/rp-private.key

Restart your installation after configuring the above.

You should now be able to test the SAML2 authentication and 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 project 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.