• Document Up to Date
  • Since 4.0.3

Studio SAML2 Configuration Enterprise only feature

Since 4.0.3

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

Important

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

Requirements

  1. A SAML2-compatible Identity Provider (IdP) 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 Studio:

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

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

Note

IdP is the asserting party and SP is the relying party (Studio)

Configure

To configure Studio SAML2, in your Authoring 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.studio.samlSecurity:

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

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

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

where

  • studio.security.saml.enabled: Indicates if SAML2 is enabled or not

  • The following are attributes that Studio expects from the Identity Provider:

    • studio.security.saml.attributeName.email

    • studio.security.saml.attributeName.firstName

    • studio.security.saml.attributeName.lastName

    • studio.security.saml.attributeName.group

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

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

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

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

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

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

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

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

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

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

Restart your Authoring installation after configuring the above.