EasySSO with header-based authentication configuration

Configure EasySSO

Custom authentication is used when a reverse proxy or external appliance performs the authentication and passes the user identity to Atlassian application via a value of HTTP header or some custom code running inside the application sets the value of a request attribute. See EASYSSO WITH HEADERS for more details.

To start using custom authentication

1. Type: select Header or Attribute from the drop down box
2. Name: enter the name of the header or attribute
3. Check the Get Username checkbox if you want the value of the header or attribute to be used as the user identity during SSO
4. Check disable NTLM/Kerberos if the presence of the header or the attribute should disable NTLM/Kerberos authenticator.
5. IP Filter: enter allowlist values for sources that should be considered when supplying header values, as a comma-separated IP addresses, IP ranges x.x.x.x-y.y.y.y, or networks CIDR notation
6. If you have additional headers or attributes you wish to inspect click on the plus under Type and repeat steps 1 - 6 until all required rules for the attributes and headers are set up (consider a use case when a header should stop NTLM/Kerberos, but needs to be pre-processed first by the custom code, so the real identity will be set via attribute – see EASYSSO WITH HEADERS for more details)
7. Click Save.

Security Notice for Headers Use Case

EasySSO HTTP Headers authenticator is a very "low level" integration component in terms of security. Any header value that EasySSO is configured to rely on MUST be delivered to EasySSO in a secure manner.

EasySSO does provide capability to allowlist IP addresses to indicate sources from which the header value will be considered. However, the allowlist is intended as an "integration" feature only. The trust guarantee needs to be provided by the infrastructure i.e. by correct configuration of proxy and firewalls preventing the headers to be set by arbitrary external clients. 

In our view the only way to guarantee the values can be trusted is to perform checks in a reverse proxy or a similar appliance fronting the application. The IP address of the proxy is the one that must be allowlisted. The proxy if it actually performs the authentication MUST reject/remove the headers it is supposed to set, when they are instead set by the external (malicious)  client. Any logic of letting through the headers set externally, possibly based on the client ip or some other criteria thus also falls on the proxy. The firewalls on the host that runs the Atlassian application MUST prevent any access circumventing the proxy.

Example of Apache configuration

Below is an example of Apache configuration where Apache does Kerberos-based authentication (lines 2-11), verifies against LDAP (lines 14-18) and simply passes the username to EasySSO in Confluence via a header X-REMOTE-USER set from the variable REMOTE_USER (line 20).

Please note the emphasis here is on line 20, setting the header using mod_headers after the user is identified by some other means, so the rest of the example should not be taken as is.

<Location /confluence>
        AuthType Kerberos
        AuthName "Please enter password for Confluence"
        KrbAuthRealms TEST.YOURDOMAIN.COM
        KrbMethodNegotiate On
        KrbMethodK5Passwd Off
        KrbAuthoritative on
        Krb5KeyTab /etc/apache2/httpd.keytab
        KrbServiceName HTTP/wiki.yourdomain.com@TEST.YOURDOMAIN.COM
        KrbLocalUserMapping On
        require valid-user


        AuthLDAPUrl "ldap://dc.yourdomain.com/DC=yourdomain,DC=com?samaccountname"
        AuthLDAPBindDN *****************
        AuthLDAPBindPassword *************
        AuthLDAPGroupAttributeIsDN on
        require ldap-group CN=confluence-users@yourdomain.com,OU=security-groups,DC=yourdomain,DC=com

        RequestHeader set X-REMOTE-USER %{REMOTE_USER}s

</Location>