Studio Security
Authentication
Users are authenticated by Studio through the internal database by default. CrafterCMS can be configured so that users are authenticated using an external authentication protocol such as Lightweight Directory Access Protocol (LDAP), Security Assertion Markup Language (SAML), or integrate with any Single-Sign-On (SSO) solution that can provide headers to Studio to indicate successful authentication.
Here’s a list of security providers supported by CrafterCMS for accessing the repository:
Internal database (users are stored in database)
To configure an external authentication method, please follow one of the guides below:
When using an external authentication method, user accounts are automatically created in the internal database upon each user’s first successful login, using the attributes from the responses received. Users added to the internal database after the user’s first successful login through external authentication are marked as Externally Managed.
Configure Authentication Chain
CrafterCMS supports multiple security providers and allows configuration of multiple authentication providers in a chain that are then iterated through until either the user is authenticated and granted access or authentication fails and an HTTP 401 Unauthorized is returned to the user. This allows Studio to support multiple security providers that appears like a single authentication module to users.
The following authentication providers can be configured in a chain:
Headers
LDAP
Internal database
Note
SAML2 authentication cannot be configured in a chain. SAML2 authentication is a standalone authentication provider.
When an authentication chain is configured, when a user logs in, Studio will try to authenticate the user using the first security provider in the chain as defined in the studio-config-override.yaml file. If authentication fails, it will then move on to the next authentication provider in the list and try to authenticate the user again. It will continue moving on to the next security provider in the chain until the user is authenticated or the authentication fails.
To setup the authentication chain, open the file studio-config-override.yaml under CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension. Another way to access the studio-config-override.yaml file is by clicking on the 
Navigation Menu from the context nav in Studio, then clicking on Global Config.
Below is a sample configuration for the authentication chain. There are four authentication providers in the example below: (1) Headers Authentication (2) LDAP1 (3) LDAP2 (4) Internal database
1 # Studio authentication chain configuration
2 studio.authentication.chain:
3 # Authentication provider type
4 - provider: HEADERS
5 # Authentication via headers enabled
6 enabled: true
7 # Authentication header for secure key
8 secureKeyHeader: secure_key
9 # Authentication headers secure key that is expected to match secure key value from headers
10 # Typically this is placed in the header by the authentication agent
11 secureKeyHeaderValue: secure
12 # Authentication header for username
13 usernameHeader: username
14 # Authentication header for first name
15 firstNameHeader: firstname
16 # Authentication header for last name
17 lastNameHeader: lastname
18 # Authentication header for email
19 emailHeader: email
20 # Authentication header for groups: comma separated list of groups
21 # Example:
22 # site_author,site_xyz_developer
23 groupsHeader: groups
24 # Enable/disable logout for headers authenticated users (SSO)
25 # logoutEnabled: false
26 # If logout is enabled for headers authenticated users (SSO), set the endpoint of the SP or IdP logout, which should
27 # be called after local logout. The {baseUrl} macro is provided so that the browser is redirected back to Studio
28 # after logout (https://STUDIO_SERVER:STUDIO_PORT/studio)
29 # logoutUrl: /YOUR_DOMAIN/logout?ReturnTo={baseUrl}
30 # Authentication provider type
31 - provider: LDAP
32 # Authentication via LDAP enabled
33 enabled: false
34 # LDAP Server url
35 ldapUrl: ldap://localhost:389
36 # LDAP bind DN (user)
37 ldapUsername: cn=Manager,dc=my-domain,dc=com
38 # LDAP bind password
39 ldapPassword: secret
40 # LDAP base context (directory root)
41 ldapBaseContext: dc=my-domain,dc=com
42 # LDAP username attribute
43 usernameLdapAttribute: uid
44 # LDAP first name attribute
45 firstNameLdapAttribute: cn
46 # LDAP last name attribute
47 lastNameLdapAttribute: sn
48 # Authentication header for email
49 emailLdapAttribute: mail
50 # LDAP groups attribute
51 groupNameLdapAttribute: crafterGroup
52 # LDAP groups attribute name regex
53 groupNameLdapAttributeRegex: .*
54 # LDAP groups attribute match index
55 groupNameLdapAttributeMatchIndex: 0
56 # Authentication provider type
57 - provider: LDAP
58 # Authentication via LDAP enabled
59 enabled: false
60 # LDAP Server url
61 ldapUrl: ldap://localhost:390
62 # LDAP bind DN (user)
63 ldapUsername: cn=Manager,dc=my-domain,dc=com
64 # LDAP bind password
65 ldapPassword: secret
66 # LDAP base context (directory root)
67 ldapBaseContext: dc=my-domain,dc=com
68 # LDAP username attribute
69 usernameLdapAttribute: uid
70 # LDAP first name attribute
71 firstNameLdapAttribute: cn
72 # LDAP last name attribute
73 lastNameLdapAttribute: sn
74 # Authentication header for email
75 emailLdapAttribute: mail
76 # LDAP groups attribute
77 groupNameLdapAttribute: crafterGroup
78 # LDAP groups attribute name regex
79 groupNameLdapAttributeRegex: .*
80 # LDAP groups attribute match index
81 groupNameLdapAttributeMatchIndex: 0
82 # Authentication provider type
83 - provider: DB
84 # Authentication via DB enabled
85 enabled: true
In the configuration above, when a user tries to authenticate, the user’s credentials will be passed first to the headers authentication provider. If the authentication succeeds, the processing in the chain is done and the user is allowed to proceed. If the authentication fails, the user credentials will then be passed to LDAP1. If authentication is successful, processing in the chain is done, otherwise, the user credentials are then passed on to LDAP2. LDAP2 will then try to authenticate user. If successful, processing in the chain is done, otherwise, the user credentials are then passed to the final provider in the chain, the internal database. The final provider in the chain then determines whether the user is successfully authenticated or rejected and sent an HTTP 401 Unauthorized message. Below is a diagram showing the authentication chain process using the above configuration:
Studio SAML2 Configuration 
Since
4.0.3
Crafter Studio can be configured to support SAML2 SSO out of the box without using any additional plugin.
Important
This document only applies to CrafterCMS version 4.0.3 and later
Please see here for version 4.0.2 and earlier.
Requirements
A SAML2 compatible Identity Provider (IdP) properly configured, this configuration will not be covered here
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.crtTake 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.locationpropertyout: The value used for this option will be used in the
studio.security.saml.rp.certificate.locationproperty
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:
# -------------------- 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 setup 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):
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 notThe following are attributes that Studio expects from the Identity Provider:
studio.security.saml.attributeName.emailstudio.security.saml.attributeName.firstNamestudio.security.saml.attributeName.lastNamestudio.security.saml.attributeName.group
studio.security.saml.rp.privateKey.location: The path of the relying party (SP) private key in the classpathstudio.security.saml.rp.certificate.location: The path of the relying party (SP) certificate in the classpathstudio.security.saml.ap.entityId: The asserting party (IdP) entity IDstudio.security.saml.ap.single.signOn.service.location: The asserting party (IdP) single sign on URLstudio.security.saml.ap.single.logout.service.location: The asserting party (IdP) single logout URLstudio.security.saml.ap.certificate.location: The path of the asserting party (IdP) certificate in the classpathstudio.security.saml.webSSOProfileOptions.passive: Indicates if user is authenticated silentlystudio.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.
# 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.
Configure Header-Based Authentication
Crafter Studio is able to integrate with any authentication system that sends custom HTTP headers containing information that will be used to authenticate the user in Studio. This section details how to setup Studio for header-based authentication.
Configure Studio for Header-Based Authentication
Configuring Studio for header-based authentication is very simple: in your Authoring installation, go to CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension and add the following lines to studio-config-override.yaml (of course, make any appropriate configuration changes according to your system):
1# Studio authentication chain configuration
2# studio.authentication.chain:
3 # Authentication provider type
4 # - provider: HEADERS
5 # Authentication via headers enabled
6 # enabled: false
7 # Authentication header for secure key
8 # secureKeyHeader: secure_key
9 # Authentication headers secure key that is expected to match secure key value from headers
10 # Typically this is placed in the header by the authentication agent
11 # secureKeyHeaderValue: secure
12 # Authentication header for username
13 # usernameHeader: username
14 # Authentication header for first name
15 # firstNameHeader: firstname
16 # Authentication header for last name
17 # lastNameHeader: lastname
18 # Authentication header for email
19 # emailHeader: email
20 # Authentication header for groups: comma separated list of sites and groups
21 # Example:
22 # site_author,site_xyz_developer
23 # groupsHeader: groups
24 # Enable/disable logout for headers authenticated users (SSO)
25 # logoutEnabled: false
26 # If logout is enabled for headers authenticated users (SSO), set the endpoint of the SP or IdP logout, which should
27 # be called after local logout. The {baseUrl} macro is provided so that the browser is redirected back to Studio
28 # after logout (https://STUDIO_SERVER:STUDIO_PORT/studio)
29 # logoutUrl: /YOUR_DOMAIN/logout?ReturnTo={baseUrl}
From the above configuration, here are the attributes that Studio expects from the headers to be provided:
username
firstname
lastname
email
groups
The attribute secure_key is placed by the authentication agent in the header.
The attribute enabled enables/disables headers authentication, make sure this is set to true for header-based authentication
Configuring Logout
The Sign out button link is disabled/hidden by default when header-based authentication is enabled.
To enable Sign out for users signed in using header-based authentication, change the following lines (as described from the above configuration) in your studio-config-override.yaml file (of course, make any appropriate configuration changes according to your system):
# Enable/disable logout for headers authenticated users (SSO)
# logoutEnabled: false
# If logout is enabled for headers authenticated users (SSO), set the endpoint of the SP or IdP logout, which should
# be called after local logout. The {baseUrl} macro is provided so that the browser is redirected back to Studio
# after logout (https://STUDIO_SERVER:STUDIO_PORT/studio)
# logoutUrl: /YOUR_DOMAIN/logout?ReturnTo={baseUrl}
Configure LDAP Authentication
To configure LDAP authentication, in your Authoring installation, go to CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension and uncomment the
following lines to the studio-config-override.yaml file.
Note
The values for the parameters listed below are just examples. Remember to make any appropriate configuration changes according to your directory service in use.
1# Studio authentication chain configuration
2studio.authentication.chain:
3 # Authentication provider type
4 - provider: LDAP
5 # Authentication via LDAP enabled
6 enabled: true
7 # LDAP Server url
8 ldapUrl: ldap://localhost:389
9 # LDAP bind DN (user)
10 ldapUsername: cn=Manager,dc=my-domain,dc=com
11 # LDAP bind password
12 ldapPassword: secret
13 # LDAP base context (directory root)
14 ldapBaseContext: dc=my-domain,dc=com
15 # LDAP username attribute
16 usernameLdapAttribute: uid
17 # LDAP first name attribute
18 firstNameLdapAttribute: cn
19 # LDAP last name attribute
20 lastNameLdapAttribute: sn
21 # LDAP email attribute
22 emailLdapAttribute: mail
23 # LDAP groups attribute
24 groupNameLdapAttribute: crafterGroup
25 # LDAP groups attribute name regex
26 groupNameLdapAttributeRegex: .*
27 # LDAP groups attribute match index
28 groupNameLdapAttributeMatchIndex: 0
Some notes on the properties above:
enabledenables/disables LDAP authentication, make sure this is set to true for LDAP authenticationserverUrlis just the URL where the LDAP server is listening for requests.bindDNandbindPasswordare basically the credentials used to connect initially to the LDAP server.baseContextis the LDAP tree root where the user entries can be located.username,firstName,lastNameandemailare basic user attributes.groupNameindicates the groups the user belongs to (can have multiple values). You can specify a regex to extract the group name of a user.
Studio will then do a query against the LDAP server whenever a user attempts to log in and the user is not yet in the DB. If there’s a match in LDAP, the user is created in the database with the imported LDAP attributes, and finally added to the groups specified in LDAP.
Also, please note that Studio needs all the attributes listed in the config to be present in the LDAP user’s attributes, otherwise, Studio is not able to authenticate the user. When an attribute is missing, an error message will be displayed in the login screen: A system error has occurred. Please wait a few minutes or contact an administrator. Please look at the tomcat log to check which attribute was not found. Here’s an example log:
[WARN] 2017-10-11 12:42:57,487 [http-nio-8080-exec-2] [security.DbWithLdapExtensionSecurityProvider] | No LDAP attribute crafterGroup found for username jbloggs
Here are a few things to take note of when configuring LDAP authentication in Studio:
Make sure that at least one of the groupName attribute of the LDAP user exists in Studio and has Roles and Permission setup. If there is no groupName attribute setup in Studio with Roles and Permissions, please make sure that the system administrator assigns a role to at least one group in Studio so the user can access the site, otherwise, once the user gets into the Sites screen and tries to Preview the site or view the dashboard, the user will get a notification that the site is invalid.
To assign a role to a group, please follow the guide Role Mappings. To assign permissions to a role, please see Permission Mappings
For an example of setting up LDAP, see Setting up a Simple LDAP Server using Apache Directory Studio
Other Security Configuration
Configure Studio Password Requirements
Password requirements validation allows the admin to setup rules that ensures users create passwords based on an organization’s password security policy.
Crafter Studio uses zxcvbn for password strength management.
Since 4.0.3The password strength configured here are displayed to the user when resetting a password or creating a user.
To configure the password strength, click on Main Menu then click on Global Config.
Scroll to the section Security and change the value of studio.security.passwordRequirements.minimumComplexity
to desired minimum password complexity required:
1# Password requirements minimum complexity
2# This is based on https://github.com/dropbox/zxcvbn
3# The minimum complexity corresponds to the password score
4# You can try this out here https://lowe.github.io/tryzxcvbn/
5# score # Integer from 0-4 (useful for implementing a strength bar)
6# 0 # too guessable: risky password. (guesses < 10^3)
7# 1 # very guessable: protection from throttled online attacks. (guesses < 10^6)
8# 2 # somewhat guessable: protection from unthrottled online attacks. (guesses < 10^8)
9# 3 # safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10^10)
10# 4 # very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10^10)
11# The default value is 3
12studio.security.passwordRequirements.minimumComplexity: 3
Crafter Studio’s default minimum password complexity required is set to 3 (which translate to a score
of 80 in the UI), and until the user setting/changing the password has met the minimum required,
the Submit button will not be enabled. Also, once the minimum password strength score has been
reached, the score will be displayed in green.
Below, are some of the messages displayed as a user is inputting a new password:
Timeouts
1##################################################
2## Security ##
3##################################################
4# Time in minutes after which active users will be required to login again
5# studio.security.sessionTimeout: 480
6# Time in minutes after which inactive users will be required to login again
7# studio.security.inactivityTimeout: 30
8#
9# Salt for encrypting
10studio.security.cipher.salt: ${env:CRAFTER_SYSTEM_ENCRYPTION_SALT}
11# Key for encrypting
12studio.security.cipher.key: ${env:CRAFTER_SYSTEM_ENCRYPTION_KEY}
13
14# The key used for encryption of configuration properties
15studio.security.encryption.key: ${env:CRAFTER_ENCRYPTION_KEY}
16# The salt used for encryption of configuration properties
17studio.security.encryption.salt: ${env:CRAFTER_ENCRYPTION_SALT}
18
19# The path of the folder used for the SSH configuration
20studio.security.ssh.config: ${env:CRAFTER_SSH_CONFIG}
21
22# Defines name used for environment specific configuration. It is used for environment overrides in studio. Default value is default.
23studio.configuration.environment.active: ${env:CRAFTER_ENVIRONMENT}
Cipher Configuration
1##################################################
2## Security ##
3##################################################
4# Time in minutes after which active users will be required to login again
5# studio.security.sessionTimeout: 480
6# Time in minutes after which inactive users will be required to login again
7# studio.security.inactivityTimeout: 30
8#
9# Salt for encrypting
10studio.security.cipher.salt: ${env:CRAFTER_SYSTEM_ENCRYPTION_SALT}
11# Key for encrypting
12studio.security.cipher.key: ${env:CRAFTER_SYSTEM_ENCRYPTION_KEY}
13
14# The key used for encryption of configuration properties
15studio.security.encryption.key: ${env:CRAFTER_ENCRYPTION_KEY}
16# The salt used for encryption of configuration properties
17studio.security.encryption.salt: ${env:CRAFTER_ENCRYPTION_SALT}
18
19# The path of the folder used for the SSH configuration
20studio.security.ssh.config: ${env:CRAFTER_SSH_CONFIG}
21
22# Defines name used for environment specific configuration. It is used for environment overrides in studio. Default value is default.
23studio.configuration.environment.active: ${env:CRAFTER_ENVIRONMENT}
Access Tokens
Since 4.0.0The following section of Studio’s configuration overrides allows you to configure settings for the Studio access tokens. Access tokens can then be used to invoke Crafter Studio’s REST APIs, or used in Crafter CLI to perform operations on Studio.
1##################################################
2## Access Tokens ##
3##################################################
4
5# Issuer for the generated access tokens
6studio.security.token.issuer: ${env:STUDIO_TOKEN_ISSUER}
7# List of accepted issuers for validation of access tokens (separated by commas)
8studio.security.token.validIssuers: ${env:STUDIO_TOKEN_VALID_ISSUERS}
9# The audience for generation and validation of access tokens (if empty the instance id will be used)
10studio.security.token.audience: ${env:STUDIO_TOKEN_AUDIENCE}
11# Time in minutes for the expiration of the access tokens
12studio.security.token.timeout: ${env:STUDIO_TOKEN_TIMEOUT}
13# Password for signing the access tokens (needs to be equal or greater than 512 bits in length)
14studio.security.token.password.sign: ${env:STUDIO_TOKEN_SIGN_PASSWORD}
15# Password for encrypting the access tokens
16studio.security.token.password.encrypt: ${env:STUDIO_TOKEN_ENCRYPT_PASSWORD}
17# Name of the cookie to store the refresh token
18studio.security.token.cookie.name: ${env:STUDIO_REFRESH_TOKEN_NAME}
19# Time in seconds for the expiration of the refresh token cookie
20studio.security.token.cookie.maxAge: ${env:STUDIO_REFRESH_TOKEN_MAX_AGE}
21# Indicates if the refresh token cookie should be secure (should be true for production environments behind HTTPS)
22studio.security.token.cookie.secure: ${env:STUDIO_REFRESH_TOKEN_SECURE}