SSO setup on Filestash using SAML

This document provides a detailed guide on how to set up the SAML connector in Filestash. It is divided into 3 main sections:

1. Technical Requirements: the prerequisites to follow this guide
2. Basic Setup: step by step instructions for the most basic SAML integration
3. Advanced Setup: describes how to use SAML attributes to generate dynamic storage connections

Requirements

Filestash integrates with SAML compliant IDPs including AWS Cognito, okta, auth0, ping, onelogin, duo, Microsoft Entra ID, Oracle …etc. To test the SAML connector, you first need to register the Filestash app in your IDP. To do that we first need to “establish trust” in between the IDP and Filestash. This process is different on various IDP, but in our test setup where the app is running via HTTP on port 8334, if your IDP asks you to fill some details, it would look something like this:

- entityID: http://localhost:8334/saml/metadata
- assertion consumer service (acs): http://localhost:8334/saml/acs
- single logout service (slo): http://localhost:8334/saml/slo

If you’re asked the XML metadata of Filestash, you can download it by visiting: /saml/metadata. For the sake of testing this integration locally, we will be using a dummy SAML test server locally and inject our app metadata via environment variables, to do so, we just need to run this command:

Basic Setup

A basic setup involves 3 steps:

STEP 1: Configure the IDP metadata in Filestash. Your IDP should give you a scary looking XML document that need to be copy pasted in the IDP metadata field:

STEP 2 (optional): Depending on your IDP, if you haven’t set the ACS, SLO and entity ID in your IDP yet, you might need to upload some XML metadata back onto the IDP to establish the trust. This XML metadata document can be found by accessing /saml/metadata in your instance. It looks like this:

STEP 3: Link your IDP to the choosen storage:

Once configured, users logging in via SFTP will be greeted with the IDP login page which in the case of our testing IDP is:

Once authenticated, users will see the storage you have configured:

Advanced Setup

Now that we’ve covered the basics, let’s dive into the cool stuff: using the SAML attributes to create dynamic connection rules. The first step is understanding the attributes your SAML server provides. These attributes will be visible in the logs if you set the logging level to DEBUG within /admin/logs:

In my case with the simple test SAML IDP, the log looks like this:

...
2024/12/09 17:41:34 SYST DEBUG SAML Attributes => email[user1@example.com] uid[1] eduPersonAffiliation[group1]
...

All these attributes can be utilised to configure the connection to your storage. For this example, let’s setup rules where users in group1 have full access to the entire filesystem, while others are read only users:

- authorization: ls,cat{{ if .eduPersonAffiliation | contains "group1" }},touch,mkdir,mv,rm{{ end }}

The possibilities are endless. Behind the scenes, you can leverage the entire Go templates ecosystem, enhanced with custom functions to support a wide range of use cases.

If you encounter any issues, feel free to reach out to support, and we’ll help resolve them.