Architecture for Authentication

Introduction

This page provides an overview of how SSO and/or External Authentication and Authorization works and how it can be customized to fit your needs. A common method to automatically authenticate and authorize users is to use the Integrated Windows Authentication method (using NTLM/Kerberos) in combination with an Active Directory Service.

While Squirro ships with a web server (called Nginx) that supports integration with Active Directory Service, OpenLDAP etc, NTML/Kerberos support is not directly possible.

If you require SSO via NTML/Kerberos, Squirro recommends a third-party solution.

This also gives your IT team full control over the process, which is a major benefit.

For example CA Single Sign On (formerly known as Site Minder) has been successfully deployed for Squirro. But any solution that provides SSO capabilities and can proxy HTTP/S traffic to the Squirro installation should work as well. This includes the well-known Microsoft IIS/ARR solution.

There are other ways to achieve SSO without the need for NTLM/Kerberos, such as oAuth, OpenID, or Client Side Certificate Authentication. These are not covered on this page, but can be configured. Contact Squirro Support for help.

Overview

Below is a graphical overview of authentication and authorization. In the next chapter, you’ll see how it works step by step.

Workflow

1 - Client Device

For SSO to work, the end user’s client (e.g. Browser) must be integrated into the directory service. Typically this is Microsoft Active Directory Service. How this is done is beyond the scope of this document and might vary based on the solution you’ll use.

2 & 3 - Security Appliance

All client traffic for Squirro is routed via the security appliance (e.g. SiteMinder or Microsoft IIS/ARR or other webservers like Apache or Nginx with LDAP integration). This appliance detects the browser’s SSO information (kerberos token or client certificate) and validates/authenticates the user automatically using the Directory Service. If the user cannot be authenticated, then the user cannot access Squirro.

If access is granted, the client’s traffic is forwarded to the Squirro cluster, and the current user’s information is added to the HTTP/S request headers (a unique user id, optionally account name, email, common name, etc.)

In some scenarios, all data is added, in others, only a session id is added which then allows the external authentication service (see step 6) to retrieve more data about the user.

4 - Squirro NGINX

The authenticated traffic arrives a the Squirro NGINX server. Here the HTTPS / SSL connection is terminated. Nginx should be configured so that it only accepts traffic from the security appliance.

You can also validate the user’s SSL certificate and reject any unknown clients, adding another layer of security.

5 - Squirro Frontend Service

The NGINX webserver invokes the Frontend Service to handle the requests.

The frontend service consults the user service to see if the users already has a valid Squirro session. Since there is none present, the frontend service is configured to fall back to the external authentication service. The frontend service forwards the request metadata including the HTTP/S request headers to the external authentication service.

6 Phase 1 - Squirro External Authentication Service

The external authentication service is an extendable web-service that can integrate with any 3rd party directory service, including ADS and OpenLDAP. If your directory is a custom-built solution, e.g. a SQL database or available via a custom API, please contact us. The external authentication service can easily be extended to support your solution.

The external authentication service now decides if the user is allowed to access the system and if so, what group memberships are granted to the user for this session. See step 6 Phase 2 below.

7 - Validate the User

Based on the HTTP/S headers injected by the security appliance the external authentication service connects to the directory service to validate that the users exists and retrieves additional data, e.g. group memberships and roles.

This step is fully optional, if the security appliance provides already all information needed via the HTTP/S headers, this step can be skipped.

6 Phase 2 - Squirro External Authentication Service

With the user validated and the additional metadata available, the external authentication service makes the final decision if access is granted.

If not, the user is denied access.

If yes, the external authentication service instructs the users service to create / update the required user and which group memberships to grant to the user for this session.

8 - Squirro User Service

With the information from the external authentication service, the user service now creates and entitles the user. Session information is sent back with the HTTP/S response.

Further requests with this session will pass the security appliance as well as the Squirro frontend / user services. The external authentication service will not be consulted for each request, only once the Squirro session expires, the entire workflow repeats. Session expiration time can be configured, defaults to 60 minutes.

At this stage you’ve successfully authenticated and authorized the users without the need to log in manually (SSO).

Based on the group memberships granted temporarily by the directory service / external authentication service, the user will now have access to the projects with the roles granted by the groups.

9 - Squirro Topic Service / Row-Based Access Control

This step is only required if you want to implement row-based access controls.

The Squirro topic services handles all the data queries that are run against the Elasticsearch cluster. In order to enforce row-based filtering, it can be configured so that any search query that is sent to Elasticsearch is extended with a mandatory query.

This is best explained with an example:

If the user issues this query:

"product offerings" AND state:MA

Then the topic service can be configured to use a query filter template to turn this into:

("product offerings" AND state:MA) AND (group:partners OR users:joe)

The values for the group and for the users are of course retrieved from the security appliance (step 2) or the directory service (step 7).

In the above example, user joe will now only see matching documents that have a group facet that contains the value partners or that have a users facet that contains his user id.

As a result every user only sees those documents which she/he is entitled to.

For this to work, access control lists (ACL) have to be indexed with the data. Squirro supports multiple freeform ACL’s and the query filter template language allows you to build highly complex rules on how the filters react to the users metadata. In addition Squirro offers a specialised facet type for ACL’s which are not available through the UI or the API for additional security.