Adobe Granite SSO Authentication Handler

What is SSO

Single sign-on (SSO) is a access-control method for allowing access to multiple, also independent, systems with a single authentication.
The user authenticates once in one system and is automatically allowed to access to all other systems in the SSO environment.
So he doesn’t have to authenticate each time he switch from a system to another.

A list of SSO implementations can be found here.

In websites or web applications world, a separate and trusted system (trusted authenticator) performs the authentication mechanism and provides the credentials putting them into the request.
In AEM, the authentication handler purpose is to extract credentials from the request and to create an object containing those credentials to pass to the login modules. The credentials consist only in the username.
So the login process with user and password is performed always before the request comes to the AEM instance. In AEM, only the user existence is checked.

How configure SSO in AEM

In AEM 6.2, the Adobe Granite SSO Authentication Handler is contained in the bundle 168.

The figure below shows the related configuration in the system console:

According to the specific SSO implementation, the credentials can be stored in the request in different ways: within headers, within cookies or within parameters.
The order of execution is:

1. headers
2. cookies
3. parameters

Attention: suppose that header and a cookie are found the request and both match with their related configurations (referring to the above figure, header cq5-user and cookie cqpsso). In this case, only the header is considered (because of the order of execution), so if the header value is invalid the SSO authentication fails even if the cookie value would be valid.

The most important fields of the configuration dialog are:

• Path: the repository path at which the SSO authentication handler is applied. For example, if the field value is set to /content/geometrixx/en and a request to /content/geometrixx/it arrives with valid SSO credentials the SSO authentication is skipped anyway, because of the SSO authentication handler is disabled for that path.
• Header names: one or more header names containing the username. If more entries are set, they are tried in order until one header is found in the request and it’s value is taken. Attention: if two configured headers are present in the request, only the first one is considered, so if the first is invalid the SSO authentication fails even if the second would be valid.
• Parameter names: one or more parameter names containing the username. If more entries are set, they are tried in order until one parameter is found in the request and it’s value is taken. Attention: if two configured parameters are present in the request, only the first one is considered, so if the first is invalid the SSO authentication fails even if the second would be valid.
• Cookie names: one or more cookie names containing the username. If more entries are set, they are tried in order until one cookie is found in the request and it’s value is taken. Attention: if two configured cookies are present in the request, only the first one is considered, so if the first is invalid the SSO authentication fails even if the second would be valid.
• User map: list of mapping of kind user request → mapped user. Referring to the figure above, this functionality can be used for example to map the not existing user dummy over the existing user author. Also impersonation could be done in this way (pay attention).
• Format: the format of the value retrieved in header, cookie or parameter. Field values can be:
  • Basic: (default) the value is encoded in the HTTP Basic Authentication format;
  • AsIs: the value is not encoded (plain text).
  • regular expression: the value should match against a regular expression.
• Trusted Credential Attribute: deprecated.

More info about SSO configuration in AEM can be found here.

Security problems

Because of the login process is performed in front of AEM in the request process, it’s recommended to not public expose an AEM instance with SSO authentication handler enabled, otherwise someone how knows or guesses the valid header/cookie/parameter could access to AEM even if he’s not allowed. To ensure security it’s suggested to put in front of AEM a web server with its specific SSO module activated. So only that module will add the valid header/cookie/parameter to the request in order to be retrieved and used in the AEM SSO authentication handler.

Also the dispatcher, if present, must be configured in the proper way.

More info about SSO configuration on web server and dispatcher can be found here.

Authors

Aldo Caruso, Fernando Díaz Martín