During the past few years there has been an increasing customer interest to integrate Atlassian applications, especially Atlassian Confluence, with Active Directory Federation Services (ADFS).
Active Directory Federation Services is a Web-based identity management service with Single Sign-On capabilities. It is compatible with the SAML 2.0 standard, which might be familiar at least to those working with academic institutions, many of which (including pretty much all the Finnish universities via HAKA, https://confluence.csc.fi/display/HAKA/In+English) utilize the open source relative of ADFS, Shibboleth.
Integrating Confluence with ADFS proves to be a bit tricky undertaking, mostly due to lack of up-to-date documentation. The Shibboleth project has some useful information documented in their Wiki, here: https://wiki.shibboleth.net/confluence/display/SHIB2/MicrosoftInterop, especially in the attachments. Also, if you are unfamiliar with the concepts and vocabulary of SAML, it might be quite a lot to consume at once. Of course, in a very interoperability-friendly move, Microsoft has decided to use different names for certain components.
I will not provide instructions on how to install or configure the ADFS service itself, but suffice to say that you need at least version 2.0 of ADFS in order to get the integration going. Prior versions of ADFS don’t support SAML 2.0.
In order to integrate with ADFS (or any other SAML 2.0 compatible IdP), your application has to run a so called Service Provider which represents the application to the identity provider, in this case, the ADFS Federation Server. Confluence does not natively provide one, although to my understanding there are third-party plug-ins that provide this functionality. However, the solution I describe here does not rely on such plugins. Instead, we are going to use the Service Provider provided by the Shibboleth project. The Shibboleth Service Provider consists of a system daemon, shibd and an Apache httpd module, mod_shib which in turn communicates with the shibd daemon. The openSUSE project provides yum repositories which you can use to install the required components, also for RHEL based systems. Just configure the relevant subdirectory of http://download.opensuse.org/repositories/security:/shibboleth/ as a yum repository on your server and install the package “shibboleth”. Note that this setup requires the use of Apache httpd as a frontend web server which proxies requests to Confluence since we are relying on mod_shib to provide authentication information to Confluence.
mod_shib is a authentication module (similar to mod_auth_kerb or mod_auth_ldap) that provides the name of the authenticated user via an environment variable called REMOTE_USER which is present in the HTTP request. This information can be utilized by a custom Seraph authenticator (Seraph is the pluggable authentication framework utilized by Confluence and JIRA) such as the Pixelpark’s SSOAuthenticator, downloadable here: https://maven.atlassian.com/content/repositories/atlassian-contrib/com/pixelpark/seraph/customauth/1.0/ or the Confluence HTTP Authenticator, downloadable here https://marketplace.atlassian.com/plugins/shibauth.confluence.authentication.shibboleth — the latter provides more configuration options but in turn (duh) requires more configuration. Refer to Step 4 in this page https://confluence.atlassian.com/display/SPCON/Configuring+Confluence+to+use+Jespa+for+NTLM+Authentication on how to change the authenticator used by Confluence.
The main idea here is that the request is pre-authenticated by the Apache module before it arrives to Confluence. Confluence can then utilize the information provided by the mod_shib and set up the user session accordingly. Note that this integration does not replace the need to configure your Active Directory as a User Directory in Confluence. The user accounts need to be present in Confluence in order to create sessions for them.
Now, with Confluence configured with Active Directory user accounts and the custom authenticator set up, we’ll have to set up the Shibboleth Service Provider to talk to the ADFS Federation Server. In the ADFS end, we will configure the Claim Rules for the Relying Party so that the LDAP-attribute SAM-Account-Name is sent as “Common Name” (later referred to as the attribute “cn”).
I will not provide very detailed instructions on how to configure the Service Provider, but in short, you have to configure the following:
– Map requests to https://confluence.server/login.action to Shibboleth authentication using RequestMapper
– Configure ApplicationDefaults so that cn-attribute is passed to REMOTE_USER instead of eppn
– Within <Sessions> configure your ADFS IdP with the correct entityID and of type SAML2 using a <SSO>-element
– Within <Sessions> set Handler of type “AttributeChecker” to the check for “cn” attribute instead of eppn
– Fetch your ADFS metadata from https://your.adfs.server/FederationMetadata/2007-06/FederationMetadata.xml and configure a MetadataProvider element that points to the file you fetched
– Create a RSA key pair and configure it using the CredentialResolver-element. If you already have a SSL key/cert pair you can use that.
Last but not least, add the following to the beginning of attribute-map.xml so that your Service Provider understands the attributes sent in the claim by ADFS:
<Attribute name=”http://schemas.xmlsoap.org/claims/CommonName” id=”cn”>
<AttributeDecoder xsi:type=”StringAttributeDecoder” caseSensitive=”false”/>
Modify your Apache virtual host so that Shibboleth-authentication is activated in /login.action, for example:
ShibRequestSetting requireSession 1
Also, if you are using mod_proxy, make sure not to proxy anything below /Shibboleth.sso to the Confluence.
Now, next you have to configure the Service Provider as a relying party in ADFS. Shibboleth metadata can be downloaded from https://confluence.server/Shibboleth.sso/Metadata. This should be a fairly straightforward process with only one Claim Rule to be configured for the relying party. It is of type Send LDAP Attributes as Claims and should send SAM-Account-Name as Common Name.
With this configuration in place, your ADFS integration should work by accessing https://confluence.server/login.action, which should automatically log in to Confluence using your workstation login credentials. You may have to alter your browser settings, for example, in Internet Explorer the Confluence site (https://confluence.server/) has to be added to the “Local Intranet” for the authentication to work seamlessly.
The picture attempts to clarify the relationships between different components: