Alfresco Certificate Based SSO
In the past few weeks, two of our customers requested us to implement a certificate based Single Sign On (SSO) for Alfresco. So we thought it would be good idea to write a blog about it.
Before we get into details of setting certificate based SSO for Alfresco, let us have a look at the pros and cons of using certificate based authentication for Alfresco.
Advantages of Certificate Based SSO
· Most organisations already have client certificates in place. Organisations using Active directory for user management have the ability to generate client certificates easily with the out of the box Active Directory Certificate Enrolment service.
· User Authentication is black boxed from Alfresco and is controlled by an external software layer; hence any issue in regards to authentication is restricted to the external software layer and can be managed independently of alfresco.
Disadvantage of Certificate Based SSO
· Setting up Certificate Based SSO for Alfresco involves Alfresco accepting external authentication tokens which means anyone who can make http requests to the Alfresco repo could add in that header and impersonate anyone. So we need to make sure that there is no untrusted direct access to Alfresco’s HTTP or AJP ports.
· Alfresco AOS (Alfresco Office Service) which provides Edit Online functionality within Share, does not support use of Certificate based SSO for Single Sign On.
Alfresco Certificate Based SSO Implementation
Setting up Alfresco Certificate Based SSO involves two parts;
· Configuring the External Authentication software to forward the authenticated username to Alfresco Share
· Configuring Alfresco to accept external authentication tokens
External Authentication software
We had the opportunity to work with the following External Authentication software;
· Apache and Active Directory Enrolment Certificate Service
· F5 load balancer and EJBCA Certificate Authority software
Apache and Active Directory Enrolment Certificate Service
Apache was configured to get and append the authenticated username to the Request Header from the client certificate. We configured apache to add the username to a header field we called X-Alfresco-Remote-User. We then are proxying the requests to the alfresco server. See below apache config snippet.
SSLProxyEngine on
SSLEngine on
SSLCertificateFile /etc/apache2/certs/seed.crt
SSLCertificateKeyFile /etc/apache2/certs/seed.key
SSLCACertificateFile /etc/apache2/certs/seed-ca.crt
SSLOptions +StdEnvVars +ExportCertData
SSLVerifyClient require
RequestHeader append X-Alfresco-Remote-User “%{SSL_CLIENT_S_DN_Email}e”
RequestHeader edit X-Alfresco-Remote-User (.*)([@].*) $1
ProxyPass /share http://alfrescoserver:8080/share
ProxyPassReverse /share http://alfrescoserver:8080/share
ProxyPass /alfresco http://alfrescoserver:8080/alfresco
ProxyPassReverse /alfresco http://alfrescoserver:8080/alfresco
· As shown above we have SSLVerifyClient set to “require” which means the client needs a valid certificate to proceed with the requests.
· The %{SSL_CLIENT_S_DN_Email}e property is being used to extract the user email address from the client certificate and appending it to X-Alfresco-Remote-User, which means that the user needs to have an email address set and the username in the email is the same as the username used in Alfresco. Another important thing to note is that we are editing the RequestHeader using RegEx so that only the username is passed to Alfresco instead of the whole email. Using the user UID would have been ideal but unfortunately the out of the box Active Directory Enrolment Client Certificate generation template does not include the UID in the client certificate.
F5 load balancer and EJBCA Certificate Authority software
The F5 load balancer acts as a proxy between the client and the Alfresco server. F5 allows you to define rules (iRules) to manage what is being proxied. See snippet below;
when HTTP_REQUEST {
# Check if the client presented a cert for this session
if {[SSL::cert count] == 0}{
# Reset the connection
#reject
} else {
# Step 1 Check for X.509 Cert
if {[SSL::cert 0] eq “”}{
# Reset the connection
#reject
} else {
#Example Subject: UID=jsmith, CN=John Smith, GN=John, SN=Smith, OU=People, O=SEEDIM Pty Ltd, DC=staff
set subject_cn [X509::subject [SSL::cert 0]]
set uid [lindex [split $subject_cn “,”] 5]
set username [string range $uid 4 end]
HTTP::header remove X-Alfresco-Remote-User
#log local0. “Inserting HTTP header: X-Alfresco-Remote-User $username”
HTTP::header insert X-Alfresco-Remote-User $username
}
}
}
Compared to the Apache configuration described previously, in the F5 scenario, the generated client cert (EJBCA Certificate Authority software) already has the UID included in it and is being inserted directly in the X-Alfresco-Remote-User header.
Alfresco External Authentication Subsystem
Out of the box, Alfresco provides the ability to integrate with any external authentication system through its External Subsystem. The subsystem involves allowing Header based external Authentication that is; it allows requests to be made through a configured proxy user in the name of an alternative user, whose alfresco username is passed in a configured HTTP request header. In this case we are using the header configured in the load balancer, ie X-Alfresco-Remote-User.
Configuring External Authentication in Alfresco
Turning on the External Authentication subsystem is straight forward. We just need to add the following in alfresco-global.properties
authentication.chain=external1:external
external.authentication.proxyUserName=
external.authentication.enabled=true
external.authentication.defaultAdministratorUserNames=admin
external.authentication.proxyHeader=X-Alfresco-Remote-User
Note
Though we have not used it, external subsystem does provide the ‘external.authentication.userIdPattern’ property to edit the header based on RegEx. Although we have not tested this we assume that it is possible to change the X-Alfresco-Remote-User value to suit the userid needed to authenticate by using a RegEx pattern. In our case we did the manipulation of the email address to the userid in the apache configs.
Testing the Header Based External Authentication
A quick way to test that Header Based External Authentication is working is to use the curl command below;
curl -X GET -L -H "X-Alfresco-Remote-User:seed" http://localhost:8080/alfresco/wcservice/api/people
Configuring Share for External Authentication
Alfresco Share can be configured to accept a user name from an HTTP header provided by an external authentication system for Single Sign on. We only need to add the following in share-custom-config.xml
<config evaluator=”string-compare”condition=”Remote”>
<remote>
<connector>
<id>alfrescoCookie</id>
<name>Alfresco Connector</name>
<description>Connects to an Alfresco instance using cookie-based
authentication
</description>
<class>org.alfresco.web.site.servlet.SlingshotAlfrescoConnector</class>
</connector>
<connector>
<id>alfrescoHeader</id>
<name>Alfresco Connector</name>
<description>Connects to an Alfresco instance using header and
cookie-based authentication
</description>
<class>org.alfresco.web.site.servlet.SlingshotAlfrescoConnector</class>
<userHeader>X-Alfresco-Remote-User</userHeader>
</connector>
<endpoint>
<id>alfresco</id>
<name>Alfresco – user access</name>
<description>Access to Alfresco Repository WebScripts that require user
authentication
</description>
<connector-id>alfrescoHeader</connector-id>
<endpoint-url>http://localhost:8080/alfresco/wcs</endpoint-url>
<identity>user</identity>
<external-auth>true</external-auth>
</endpoint>
</remote>
</config>
Conclusion
Certificate based SSO provides a good alternative to implement SSO with Alfresco especially where client certificate are already in place or being used for other applications in an organisation and also in cases where NTLM based SSO (Passthru) does not work accordingly in certain scenario such when doing a search in Alfresco 5.0.2.5 from IE 10 and IE 11, with NTLM based SSO (Passthru) configuration, the security window pops up multiple times. (see https://issues.alfresco.com/jira/browse/MNT-15376 for more details).
