SAML 2.0 and the SME Enterprise File Fabric

last updated Sept. 25 2018

The Enterprise File Fabric supports users logging-in via the SAML 2.0 protocol. The SAML 2.0 protocol is increasing in popularity, and there are a number of different flavours and variations provided by different identity providers (IDPs), like Active Directory Federation Services (ADFS) and Google Suite (GSuite).

This guide covers how a SAML 2.0 configuration can be configured from the File fabric interface, and the specifics relating to each platform.

To begin configuring the SAML 2.0 connection, you will need to ensure that SAML is enabled in your Package. To do this login as the ApplAdmin user, visit the User Packages screen, find the package that your Organization uses, and ensure that SAML 2 Login System is highlighted in the “Extra options” section

Next, login as the Organization Administrator account, and visit the Auth Systems screen from the Organization menu.

Under Add Auth System, select SAML 2 from the dropdown beside Auth System.

On this screen, you are now required to enter the specific details about your particular SAML 2 Identity Provider. The following list describes the meaning of each field.

• Auth System Name - Each authentication system has a name which is provided for your reference. Enter a name you can use to identify this later on.
• Login button label - Instead of users supplying the File Fabric with usernames and passwords, the users will be shown a button for them to click to perform the login. The text you supply here will be used on the button, for example you may wish to enter “Login with AcmeCorp AD”
• The Service provider entity ID - Your Identity Provider will either ask you to supply an Entity ID or will generate one for you. You should enter what your Identity Provider supplies you with here.
• SSO entry point - Your Identity Provider will provide you with a URL that begins the login flow for your users with the File Fabric service. This can commonly be referred to as the SSO URL or SSO Login Endpoint.
• The logout service endpoint - Your Identity Provider will provide you with the Logout URL, where SME will send users to when they wish to logout of the Enterprise File Fabric.
• Certificate data - Your Identity Provider will provide you with a certificate when configuring your SAML Service Provider. You should download that certificate and paste its entire contents into this field.
• Fetch user Role/Group - If you are using Azure Active Directory FS services, you will need to tick this option. Otherwise leave it unchecked.
• Auto create user on login - Manual user import is not possible with SAML, so this option should be checked.
• Update user roles/groups on login - The File Fabric can refresh a user's role/group membership each time they login. Check this to ensure that this happens.
• Update user info on login - The File Fabric can refresh a users personal information, such as their name, each time they login. Check this to ensure that this happens.
• User Import Fields - The File Fabric requires certain pieces of information when linking a user to the platform. Since there are no field name standards with the File Fabric, you will need to supply the mappings.

For specific details on configuring different platforms, follow our guides below.

Once you have completed the configuration you can use the Test Settings button, and complete this by clicking Add Auth System.

From the AD FS management screen, click Add Relying Party Trust… from the sidebar.

This will open a wizard like below.

Click Start

Click the radio button Enter data about the relying party manually and click Next

Enter an appropriate Display name so that you can recognise it in the future and click Next

Select the AD FS profile radio button and click Next.

Under the Configure Certificate, leave the settings as their default settings and click Next.

On the Configure URL screen, tick the Enable support for the SAML 2.0 WebSSO protocol checkbox.

In the Relying party SAML 2.0 SSO service URL field, you will need to enter your appliances base URL, with “/saml.htm” appended to it. For example, if your appliace is hosted at “https://sme.example.com” you would enter “https://sme.example.com/saml.htm” in this field.

Click Next.

On the Configure Identifiers screen, you will need to enter the base URL for your appliance in the Relying party trust identifier field. For example we could enter “https://sme.example.com” then click Add

You will then be asked if you wish to Configure Multi-factor Authentication for this relying party trust. You may do so, but it is out of scope for this guide.

Click Next

On the Choose Issuance Authorization Rules screen, select the Permit all users to access this relying party radio button.

Click Next

On the Ready to Add Trust screen, review the settings you have entered.

Click Next

On the final screen, ensure that the Open the Edit Claim Rules dialog for this relying part trust when the wizard closes is ticked, and click Close

From the Issuance Transform Rules screen, click Add Rule…

From the Claim rule template drop down, select Send LDAP Attributes as Claims and click Next.

Enter a friendly name under Claim rule name.

Select Active Directory from the Attribute store

Configure the Mapping of LDAP attributes as per the image below.

Next, add another Claim Rule.

From the CLaim rule template select Send Group Membsership as a Claim. Provide a Claim rule name.

Select the User's group that this applies to

Select the Outgoing claim type as Group

Input the Outgoing claim value as “group”

Close the Claim Rules dialog.

Next, visit the Certificates folder under Service

Double click on your certificate under the Token-signing section.

Click on the Details tab and click Copy to File

Click Next when the dialog opens.

Select Base-64 encoded X.509 (.CER) as the export format.

Click Next

Select the location on disk to store the certificate and follow the prompts to complete the export.

Finally, click on the AD FS folder on the left hand side. From the Action menu, select Edit Federation Service Properties.

Copy the value from the Federation Service identifier field and save this.

Now we will configure the Auth System inside SME. Given the guide at the top of this document, the relevant fields from AD FS are as follows:

Service provider entity ID - This is the value from the Federation Service identifier field

SSO entry point - For AD FS this is typically the base URL of the service appended with “/adfs/ls”, for example “https://ad.example.com/adfs/ls”

Logout service endpoint - For AD FS this is typically the SSO endpoint with the additional query string of “?wa=wsignout1.0”, for example “https://ad.example.com/adfs/ls?wa=wsignout1.0”

Certificate data - Open the exported certificate you obtained from the AD FS system into Notepad, and copy the whole contents into this field.

Ensure the field mappings are as follows:

• Unique user attribute ⇒ username
• User Login Field ⇒ username
• User Name Field ⇒ fullname
• User Email Field ⇒ email
• Role\Group Name Field ⇒ role
• User Phone Field ⇒ phone

As the administrative user for your G Suite domain, login to the Gsuite Admin panel.

Then Select Apps > SAML Apps from the menu on the left hand side of the screen (“hamburger menu”).

On the following screen, click the yellow plus (+) symbol in the bottom left to add a new SAML Application. Then select “Setup my own custom app”

On the next screen you will want to save the SSO URL, Entity ID and download the certificate.

On the next page enter an Application Name that matches your File Fabric system, and use any Description or Logo you would like, and click next.

Next fill out the “Service Provider Details” like so:

ACS URL = File Fabric URL + “/saml.htm” - ex: https://filefabric.fileserverapp.com/saml.htm

Entity ID = File Fabric URL - ex: https://filefabric.fileserverapp.com/

Start URL = File Fabric URL - ex: https://filefabric.fileserverapp.com/

Name ID = Leave as Default: Basic Information > Primary Email

Name Format = Leave as Default: Unspecified

We will setup the following mappings in the Attribute Mapping Section:

Username > Basic Information > Primary Email

email > Basic Information> Primary Email

fullname > Basic Information > First Name

groups > Employee Details > Department

phone > Contact Information> Phone Number

upn > Basic Information > Full Name

Click Finish to complete the setup of the SAML App.

Finally select the three dot menu for the app and select “ON for everyone” to enable all of your GSuite users to use this app.

As the Org admin, we will now enable the SAML Authentication.

Click on: Organization > Auth Systems.

Select: Auth System > SAML 2

Fill in the following details:

Auth System Name - G Suite SAML

Login Button label - This text field will be what is displayed in the login button on the File Fabric login page. Use something that the users will understand like “Login with Google”

The service provider entity ID - Enter the Entity ID you saved from the Google SAML App setup screen

SSO Entry point - Enter the SSO URL you saved from the Google SAML App setup screen

Logout Service Endpoint - https://accounts.google.com/Logout

Certificate Data = Enter the certificate text you downloaded from the Google SAML App setup screen

Fetch User Role\Group Name by id - Leave unchecked

Auto create user on login - Check if you would like users to be auto provisioned when logging in via SAML

Update user roles/groups on login - Check if you would like File Fabric roles to be updated on user login

Update user info on login - Check to update all user information on SAML login

User Import Fields

Ensure the following mappings are set:

Unique user attribute > username

User login field > username

User Name field > fullname

User email field > email

Role\Group name field > groups

User Phone field > phone

Click Test and then Update to save these settings

From your Administrative Okta account, click on Applications from the top menu, and then click Add Application. From the left menu click on the Create New App button.

For the Platform option, select Web.

For the Sign on method, select SAML 2.0.

Then click Create.

On the next screen we need to supply some basic information for the application.

For the App Name, provide a friendly name for the SME service, e.g. Enterprise File Fabric. Optionally you can also provide an App logo that users would recognize.

Click Next.

On the SAML settings screen we want to configure the fields as follows:

• Single sign on URL - This should be the URI of your SME appliance, appended by “/saml.htm”. For example “https://sme.example.com/saml.htm”
• Audience URI - This should be the URI of your SME Appliance, e.g. “https://sme.example.com”
• Default RelayState - This should be left blank
• Name ID format - Select Email Address
• Application username - Select Okta Username

Under Attribute Statements configure the mappings as follows:

• Name “email”, Name format “basic”, Value “user.email”
• Name “fullname”, Name format “basic”, Value “user.login”
• Name “username”, Name format “basic”, Value “user.login”

Under Group Attribute Statements, you will need to choose which groups need to be exposed to the File Fabric.

A Groups Entry will need to be added with a name of “groups”. The Value is dependant on what you would like to expose to the File Fabric. Some examples are below:

• Contains: IT - Matches groups containing the word “IT”
• Regex: “^.*$” - Matches all groups

Follow the on-screen steps to save the changes.

On the Application Details screen, under Sign On, click the View Setup Instructions button.

On the File Fabric SAML Auth System screen, enter the following values:

• The Service provider entity ID - The URI entered earlier from the Audience URI field
• SSO entry point - Enter the Identity Provider Single Sign-On URL found on the Okta setup instructions screen
• The logout service endpoint - TBC
• x509 Certificate - Enter the X.509 Certificate found on the Oka setup instructions screen

Before users are able to access the Okta application, Users or Groups must be assigned the application for it to be available to them.