You can configure CONFLUENCE to get authentication through certificates. For this CONFLUENCE should be configured as a "CAS enabled" service, that is: a client for a Central Authentication Service server. It also brings common authentication with Single Sign On (SSO) with others "CAS enabled" services. That is, once authenticated with CAS, a user doesn't need to authenticate again when accessing others "CAS enable" services, its authenticated identity is passed to the client service. It is common to use LDAP directory in addition to get more attributes like groups membership. CONFLUENCE is written in JAVA, but not open source, although freely available for non profit organizations. It runs in a servlet container like tomcat. CAS client is open source JAVA.
This document focuses on HOW TO setup CAS for CONFLUENCE, especially when using X509 certificates to authenticate.
The configurations were tested on the following environment, for others check working path, and available tested release.
See our best practices to install services and keep them up to date.
fedora-release-6-4
confluence-2.4.2
soulwing-casclient-0.3.jar
tomcat5-5.5.17-6jpp.2
ant-1.6.5-2jpp.2 # used to rebuild CAS war
java-1.6.0-sun-compat-1.6.0-1jpp # non default jpackage for SUN
jdk-6-linux-i586.bin # non default SUN package
java-1.6.0-sun-jce-policy-1.6.0-1jpp # unlimited strength for certificate keys
jpackage-utils-1.7.3-1jpp.2.fc6 # used for SUN java install
rpmdevtools-5.3-1.fc6 # used for SUN java install
selinux-policy-targeted-2.4.6-1.fc6
fedora-release-5-5
confluence-2.4.2
soulwing-casclient-0.3.jar
tomcat5-5.5.15-1jpp_6fc
ant-1.6.5-1jpp_7fc # used to rebuild CAS war
java-1.5.0-sun-1.5.0.09-1jpp # non default jpackage for SUN
jdk-1_5_0_09-linux-i586.bin # non default SUN package
jce_policy-1_5_0.zip # unlimited strength for certificate keys
jpackage-utils-1.6.6-1jpp_2rh # used for SUN java install
rpmdevtools-5.2-1.fc5 # used for SUN java install
selinux-policy-targeted-2.3.7-2.fc5
PERMISSIONS
Check file permissions on tomcat paths
[root@examle-host webapps ]# cd /var/lib/tomcat5/
[root@examle-host webapps ]# ls -l
drwxr-xr-x 6 root root 4096 Oct 4 2006 common
drwxr-xr-x 4 root root 4096 Oct 4 2006 server
drwxr-xr-x 4 root root 4096 Oct 4 2006 shared
drwxrwxr-x 4 root tomcat 4096 Oct 5 2006 webapps
[root@examle-host webapps ]# cd /usr/local/tomcat/webapps
[root@examle-host webapps ]# ls -l
drwxr-xr-x 8 tomcat tomcat 4096 May 9 11:38 cas
Handy Hint
It is wise to run tomcat in a chroot environment. It is out of the scope of this document to describe how. But keep in mind that when you copy (or mount --bind) your directories and files, you should keep permissions and SELinux context. The recommended chroot path for tomcat is "/var/tomcat5/chroot" (for tomcat5 and tomcat55). Note that CONFLUENCE MAY use Mysql, in that case you MUST install MySQL in the same chroot jail.
SELINUX context
See our best practices to keep correct file paths and remember that SELinux context is inherited from the directory level. It means that if you change a default directory, you should check the context of the newly created one.
Check files context on path /usr/lib/jvm/java/jre/lib/security
[root@example-host tls]# ls -lZ
...
-rw-r-r- root root system_u:object_r:lib_t cacerts
Others security features
Be Careful
Remember that with certificates, acceptance is controlled by the Certification authorities (CA) certificates you store in your CA path (i.e: /usr/lib/jvm/java/jre/lib/security). A default bundle file of CA certs is located at "/usr/lib/jvm/java/jre/lib/security/cacerts". A custom bundle file of CA certs could be located at "/etc/tomcat5/cacerts.trust"
There is a new java cas client, you can use with CONFLUENCE. I have not yet tested it. I don't see how configuring access to the different SSL ports of CAS server. Also note that in latest confluence release there is no more default web.xml configuration file.
CONFLUENCE with x509 certificates authentication
Configuring CONFLUENCE to allow authentication with X509 certificates, allows you to use certificates to authenticate with potentially all CAS enabled services, including others CONFLUENCE. Of course each of these services needs to be properly configured to use your CAS server, unless you participate in an Identity federation using other's CAS servers accepting certificates.
When you want to configure CAS for CONFLUENCE, these are the basic steps:
Update the following file:
/opt/confluence-2.4.2/confluence/WEB-INF/classes/seraph-config.xml
Replace ConfluenceAuthenticator by ConfluenceCasAuthenticator
Example
Comment ConfluenceAuthenticator and add ConfluenceCasAuthenticator
Update the following file:
/opt/confluence-2.4.2/confluence/WEB-INF/web.xml
Add CONFLUENCE CAS filter configurations elements among others <filter> elements in the file, before <filter-mapping> elements.
Where:
CAS server name is "caserver.example.com"
CAS server SSL port with certificate check is 8443
CAS server SSL port without certificate check is 8444
CONFLUENCE server name is "confluenceserver.example.com"
Example
<!-- Start of CAS configuration --><filter><filter-name>ConfluenceCasFilter</filter-name><filter-class>org.soulwing.confluence.cas.ConfluenceCasFilter</filter-class>
<!--
These are the usual CASFilter parameters
-->
<init-param><param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name><param-value>https://caserver.example.com:8443/login</param-value></init-param><init-param><param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name><param-value>https://caserver.example.com:8441/proxyValidate</param-value></init-param>
<!-- Change this to the server that the CAS client is running on
NOTE: This is REQUIRED. If there is a comma/space delimited list, this is automatically
matched from the HTTP Host header. If no match is found, the first entry is used. If only
a single entry is present, that is always used. -->
<init-param><param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name><param-value>confluenceserver.example.com</param-value></init-param>
<!--
These are parameters specific to the ConfluenceCasFilter
-->
<init-param>
<!--
This parameter specifies the Confluence path used for login. If this
parameter is set, a user can navigate to the normal Confluence login
page to bypass CAS and be authenticated via Atlassian-user.
-->
<param-name>org.soulwing.confluence.cas.filter.loginPath</param-name><param-value>/login.action</param-value></init-param><init-param>
<!--
This parameter specifies the Confluence path used for logout. If this
parameter and the next parameter is set, clicking the Log Out link in
Confluence causes a global CAS logout.
-->
<param-name>org.soulwing.confluence.cas.filter.logoutPath</param-name><param-value>/logout.action</param-value></init-param><init-param>
<!--
This parameter specifies the global logout URL for your CAS service. It's
used only if the previous logoutPath parameter is also configured.
-->
<param-name>org.soulwing.confluence.cas.filter.logoutUrl</param-name><param-value>https://caserver.example.com:8443/logout</param-value></init-param><init-param>
<!--
This parameter specifies a comma-delimited list of other Confluence paths that
should bypass CAS authentication. The value shown here DO NOT bypassses CAS
for the SOAP/XML-RPC API.
-->
<param-name>org.soulwing.confluence.cas.filter.bypassPrefixes</param-name><param-value>/images, /createrssfeed.action</param-value></init-param></filter><!-- End of CAS configuration -->
Warning
I do NOT RECOMMEND to bypass CAS authentication for /rpc path, because this raise serious security issues. Note that xml-rpc confluence API will NOT WORK if you follow this recommendation. Bypass CAS for rpc at your own risks, if you know what you are doing.
Update your Java Key Store with CA certificates either:
The default JKS cacerts for all default trusted CA
/usr/lib/jvm/java/jre/lib/security/cacerts
A newly created JKS cacerts.trust for a set of trusted CA
/etc/tomcat5/cacerts.trust
How to update your cacerts.trust with CA certificate single file
Where openosiCA3-EU.crt is the CA Root certificate in DER format returned by the CA
Where openosiCA1-DC.crt is the CA intermediate certificate in DER format returned by the CA
Replace where appropriate for others CA
How to update your cacerts.trust with CA certificate bundle file
Where file bundle is in PKCS7 format (.p7b or .p7c extension)
Where file name bundle is openosiCA1-DC.p7b
Replace where appropriate for others CA
Your signed certificate and the CA certificates openosiCA1-DC and openosiCA3-EU are imported simultaneously.
How to extract the CA certificate from the JKS cacerts.trust
Where openosiCA1-DC is the alias of openosi Intermediate CA of class 1
Where openosiCA3-EU is the alias of openosi Root CA of class 3
Where JKS password is changeit
Replace where appropriate for others CA
Then you can import these CA certificates in the Java JVM wide default CA file cacerts
Where default cacerts location is /usr/lib/jvm/java/jre/lib/security/cacerts
Where the cacerts jks password is changeit
Replace where appropriate for others CA
If the alias (arbitrary name you choose) does not exist in the keystore (no private key entry), keytool creates a trusted certificate entry with the specified alias, and associates it with the imported certificate. This is a general rule concerning CA certificates as well as external user's certificate.
Importing CA
Avoid confusion about trustcacerts option of the keytool import command; it has nothing to do with import of a CA certificate file!
LDAP for CONFLUENCE with x509 certificates authentication
There is no mandatory coupling between CONFLUENCE allowing authentication with X509 certificates, and LDAP use. But LDAP (X500 standard) and certificates (X509 standard) are in the same mainstream. Specifically there are common issues. When you have a coherent scheme to fit your needs, you may set LDAP - CONFLUENCE integration:
Note that LDAP directories include Microsoft Active directory.
You have groups managed by CONFLUENCE, and you MAY have groups in your LDAP directory, either static or dynamic.
Define CONFLUENCE groups if needed
Define LDAP static groups
Example of an LDIF file for a static group
Where ou=groups
Where group name is cn=Group1,ou=groups,dc=example,dc=com
Where first member is cn=test_user,ou=People,dc=example,dc=com
# LDIF example
# create FIRST Level groups branch
# Generic OU groups
dn: ou=groups,dc=example,dc=com
objectclass:organizationalunit
ou: groups
description: generic groups branch
# Group1 is ....
dn: cn=Group1,ou=groups,dc=example,dc=com
cn: Group1
objectClass: top
objectClass: groupOfNames
description: IT security group
member: cn=test_user,ou=People,dc=example,dc=com
Example of an LDIF file for adding member in static group
Where added member is cn=user_test2,ou=People,dc=example,dc=com
version: 1
dn: cn=Group1,ou=groups,ou=People,dc=example,dc=com
changetype: modify
add: member
member: cn=test_user2,ou=People,dc=example,dc=com
There is an interesting use of LDAP directories for certificates when storing these certificates and their revocation list (CRL) in the directories. Therefore you MAY imagine a scheme that facilitate directory searching for your certificate retrieval. You MAY also enhance security when the certificate subject (DN), is the same as the DN of the corresponding LDAP entry.
I suggest the following DIT (Directory Information Tree) schemes:
When using DC scheme
When holding real users in ou=people
When in addition holding virtual users (nicknames) in ou=virtualpeople
When using unique cn names (organisation scope)
When using locally unique cn names AND globally unique uid
The public certificate MAY be store in the user entry, and the certificate DN MAY be equal to LDAP DN.
Example
with unique cn names
Where cn objectclass entry is "top;person;organizationalPerson;inetOrgPerson"
# LDAP DIT
dc=com
dc=example
ou=people
cn="unique name"
cn="unique name2"
...
# LDAP and Certificate DN
cn="unique name",ou=people,dc=example,dc=com
Example
with unique cn names AND globally unique uid
Where cn objectclass entry is "top;person"
Where uid objectclass entry is "top;person;organizationalPerson;inetOrgPerson"
Multiple uid entries MAY exist under a same cn entry
The value "unique_name_in_global_scope" MAY be "email address"
# LDAP DIT
dc=com
dc=example
ou=people
cn="unique name in local scope"
uid="unique_name_in_global_scope"
cn="unique name2 in local scope"
uid="unique_name2_in_global_scope"
uid="unique_name3_in_global_scope"
...
# LDAP and Certificate DN
uid="email address",cn="unique name",ou=people,dc=example,dc=com
Note that groups are in another DIT.
email address
Email addresses in certificate subjects (DN) has been deprecated by the Internet profile for X.509 public key certificates (RFC3280) and are discouraged for a range of reasons. Old style DN looks like "Email=emailAddress,cn=unique_name,ou=people,dc=example,dc=com". Now, email address should be in certificate's subjectAltName (subject alternative name). Unfortunately many software can only retrieve the certificate's subject DN. I recommend putting email address both in uid value of certificate's DN and in subjectAltName. Of course you MAY use any other appropriate value in uid.
Example where:
host is directory.openosi.org
"cn=confluence,ou=Services,dc=openosi,dc=org" is allowed to read LDAP directory
securityProtocol is ssl otherwise your password is transmitted in plain text
baseContext is dc=openosi,dc=org
baseUserNamespace is ou=virtualpeople,dc=openosi,dc=org
baseGroupNamespace is ou=groups,ou=virtualpeople,dc=openosi,dc=org
userSearchAllDepths is true
groupSearchAllDepths is true
OSI stands for "Open Standards for Interconnection" from ISO / ITU
an OSI name is called a "Distinguished name" which is used in all OSI related technologies such as
Certificates (X509)
LDAP directories including Microsoft Active directory (X500)
Military and aeronautical messaging systems (X400)
A "Distinguished name" (DN) is a collection of one or more of the following components
CN Common name
OU Organisation Unit
O Organization
C Country
and many others like "givenname","sn surname","l location" ......
Example DN
DN: cn=My_full_name,ou=Related_Organisation_Unit,ou=other_related_unit,o=Company_name,c=country
or with the alternate DC scheme mostly used in directories.
If you want to participate in the openLDAP referral service (ldap://root.openldap.org) you MUST use the DC scheme and set appropriate SRV records in your DNS.
Common meanings of OU are as follows:
OU=Hosts
OU=People # users
OU=Services # Daemons
openOSI also uses in its naming scheme:
OU=VirtualHosts
OU=VirtualPeople # nicknames
OU=PKI # Certification authorities
In principle you are free to use what you want as DN components value, unless you request a certification authority to certify these values. That is unless you intend a public use of these names to participate in an Internet of trust (similarly to the dns - Domain name system).
You MUST use a "Distinguished name" to generate a certificate request.
There could be links between DNS and OSI naming scheme, especially when domain components are used for distinguished names. Some people stores DNS DB in an LDAP directory (like Microsoft optionally). Most people don't in order to keep loosely coupling between DNS and Directories. There is an interesting use of LDAP directories for certificates when storing these certificates and their revocation list (CRL) in the directories. Therefore you MAY imagine a scheme that facilitate directory searching for your certificate retrieval. That is unless you use a third part directory like openOSI (directory.opensosi.org). openOSI practice is to store your certificate in virtual OU unit according the openOSI naming scheme without relying on the distinguished name of the certificate.
Filling your certificate subject
Warning
You should be careful when choosing your certificate subject (DN). When authenticating with your certificate you will no more be asked for username and password. Very often you will be uniquely identified by your embedded e-mail address, but you also may be identified by your certificate subject. You cannot change your certificate's subject once it's signed by a CA.
The certificate subject is bind to the cryptographic material of your certificate (the private key). Here is the real nature of a certificate. Therefore a certificate for a user should be bind to some acceptable user ID. Check "Understanding OSI names" tab in topJXPLORER
Assign a user name to common name component. ie: cn=FirstnameLastname
The others, optional, parts of the subject are
Either a set of Organisation name and Country code_ ie: o=My_Organisation, c=US
Either a set of many Domain Components ie: "dc=example,dc=com" standing for example.com
Optionally you may have organisation units ie: ou=Finance or ou=people or ou=services
Optionally you may have additional cn as used by Microsoft naming scheme (cn=MyName,cn=Users,..)
Finally you obtain your subject value called a Distinguished Name abreviated as DN
example 1: cn=FirstnameLastname
example 2: cn=FirstnameLastname,o=My_Organisation,c=US
example 3: cn=FirstnameLastname,dc=example,dc=com
example 4: cn=FirstnameLastname,ou=people,dc=example,dc=com
This is the OSI naming scheme, also used in LDAP directories (like Microsoft AD) and X400 mail systems. If your certificate is stored in an LDAP directory, it could be stored in the same DIT (Directory Information Tree) as the one of its Distinguished name, or it could be stored under another DIT. openOSI stores the public signed certificates this way for class 1
cn=FirstnameLastname - The cn value of certificate subject
sn=Lastname (default to cn value)
mail=My.Name@example.com (default to verified e-mail address of the request)
userCertificate="Binary form of your public certificate"
OTIONS
givenName=Firstname
That is, if requesting an openOSI signed certificate, there is no need to fill something else than the common name as your user name, because openOSI will not certify additional information for its class 1 certification. Others parts like "o=My_Organisation, c=US" will be removed from the certificate unless you require a class 2 certificate (not available for now and subject to peer agreement).
Uniqueness of cn component in DN
Most of the time it is useful to have a unique value in that field, although, unique is always in a "local" context. The certificate subject alternative name refine (or replace) the subject (i.e: with e-mail address), but some authentication mechanisms like SASL EXTERNAL only uses the subject DN.
It is possible to put an e-mail address in the cn value, but many applications will fail (i.e: Liferay portal). Therefore, avoid this solution because you may have unpredictable situations with a given application.
Finaly, I recommend, when possible, to insert an "uid" component in the DN, which may look like this;
SASL_User_Name="dn:uid=My_name1234,cn=My_name,o=My_company,c=us"
Where "uid" in example, MAY be build like follows:
FirstName: John
LastName: SMITH
Last 4 digit of social security number: 1234 (or whatever algorytm)
uid=JohnSmith1234
cn="John SMITH"
This uid is supposed to be unique in the scope of a given directory (MUST be unique if you enforce controlled uid delivery). The email address remains the only worldwide unique id, if present in the subject alternative name. Note that a person MAY have multiple virtual identities, one for each of its email addresses. This is defaults for openosi.org online certification authority. The pre-registration for the certificate retrieval enforces uniqueness of the UID in the openosi directory
