EasySSO How to get the logs
What is Custom Authentication: Header and Attributes?
When a user accesses an Atlassian Product the browser sends HTTP requests to the application. These HTTP requests contains HTTP header values, which provide the Atlassian application with information about the request.
Often SSO-related headers are set by reverse proxies or VPN appliances or mobile gateways, where this trusted external entity does the real authentication and merely passes the identity to the Atlassian Product.
HTTP Headers authenticator allows EasySSO to detect and act on the presence of such headers in the request. Further, during the handling of the request inside the Atlassian Product custom code may pre-process the header values and additionally set request attribute values for EasySSO to act on.
You can configure EasySSO to search for the presence of a certain header or attribute and, if they are present, take one or both of the following actions:
- Disable NTLM/Kerberos authenticator for this request
- Read the value of the header/attribute and use this information as the username to sign the user onto the Atlassian Product.
You can combine the two actions and configure EasySSO Custom Authentication to:
- Search for a header called "user" and if this header is found disable the NTLM/Kerberos authentication, and
- take the value of the "user" header and use this value to authenticate the request and sign the user on.
Headers Use Case
When you have an intermediary such as a proxy between Jira Software (for example) and your user, instead of Jira Software redirecting to the login page to prompt for login with username/password, EasySSO with Headers can take the user's identity (which the proxy has already established) and use that instead. As long as the proxy can add the Jira Software exact username to an HTTP header on the request, EasySSO can be configured to authenticate with the value of this header instead of showing the login screen or attempting to use another SSO type.
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.
Attributes Use Case
EasySSO can do a similar thing with attributes. In this case the intermediary doesn't sit between the user and JIRA but rather inside JIRA itself, for example another plugin which does authentication or pre-processes the headers. This plugin can add an attribute to an HTTP request, which EasySSO can use to authenticate a user.
You can combine header-based and attribute-based rules and configure EasySSO Custom Authentication to:
- Search for a header called "user" and if this header is found disable the NTLM/Kerberos authentication, and
- take the value of the "user" attributed and use this value to authenticate the request and sign the user on, on assumption that custom code will take the header value, pre-process it to extract the username and set that as a value of the attribute
How to Configure
Please see EasySSO with Headers - Configuration on how to configure HTTP Headers authenticator