• Document Up to Date

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.

Static Assets - Authentication Chaining

The following authentication providers can be configured in a chain:

  • LDAP
  • headers
  • internal database

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 mainMenu Main 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:

Static Assets - Example Authentication Chain Process