FSProtect Configuration

FSProtect can be integrated with any SAML-based SSO system. The configuration has two parts: SAML Connection Configuration and Role Mapping Settings.

SAML Connection Configuration:

SSO List Page

Existing SSO integrations are listed with options to edit or delete. A New Provider button is available for adding a new integration.

New SAML Provider Page

By clicking New Provider in previous screen, user can access initial provider configuration.

Step-by-step (Create a SAML Provider):

1. Click New Provider.

2. Fill in the Provider Name and enable/disable the provider using Status.

3. Select a Default Role (fallback role if no role mapping matches).

4. Enter Username Attribute Key (required).

5. Enter Role Attribute Key (optional but recommended for role-based authorization).

6. Upload the IdP metadata XML file (or paste metadata depending on UI).

7. (Optional) Add Role Mappings to map IdP roles/groups to FSProtect roles.

8. Click Save to activate the configuration.

You need to configure a SAML Idp Connection with the parameters below.

• Status: Status of the SAML Connection (Enabled or Disabled)

• Provider Name: The provider name displayed in the system. The ACS URL is derived from this name.

• Default Role: If a logged user doesn't have any of the mapped roles in their assertion, the selected default role is assigned to that user.

Default Role is only used when role-based assignment cannot be completed. Examples:

1. Role Attribute Key is empty or not provided in the assertion.

2. Role Attribute Key exists but returns an empty list.

3. Role values exist but none match the configured Role Mappings. In all these cases, the user still logs in successfully, but receives the Default Role.

• Username Attribute Key: The SAML attribute name that maps to the username in your system in order to get or create an user with that username. It is used to find users username from the SAML assertion. Usually looks something like this.

<saml2:Attribute Name="username">
    <saml2:AttributeValue xsi:type="xs:string">forestall</saml2:AttributeValue>
</saml2:Attribute>

• The IdP must be configured to send this attribute. nameId formats are not compatible.

• Role Attribute Key: The SAML attribute name that maps to the user’s role(s) in your system. It is used to assign the correct role to the user based on the value received in the SAML assertion. Typically, this attribute contains values like "admin", "user", or custom roles defined in organisation. Identity Providers must be configured to include this role information as an attribute in the SAML response. Usually looks something like this.

<saml2:Attribute Name="role">
    <saml2:AttributeValue xsi:type="xs:string">admin</saml2:AttributeValue>
</saml2:Attribute>

• If an user has multiple roles that maps to different FSProtect roles, user is assigned to the first role that SAML assertion include.To avoid unforeseen authorization behaviors, user roles and mappings must be reviewed in the FSProtect SAML configuration.

• ACS Url: The ACS URL is the endpoint where the Identity Provider (IdP) sends the SAML authentication response after a user successfully logs in. Once the IdP completes the authentication, it posts the SAML assertion to this URL. FSProtect receives the assertion, validates its signature and contents, and then establishes a local session for the authenticated user. This URL acts as the callback endpoint that finalizes the SSO login flow.

• Audience (entity ID): The unique identifier of FSProtect as a Service Provider. The IdP compares the “Audience” value inside the SAML assertion with this Entity ID to ensure the response is intended for FSProtect.

• XML Upload Field: This field is used for uploading the Identity Provider metadata in XML format that contains crucial configuration details such as entity ID, SSO URLs, and certificate information. Uploading this file allows the system to automatically parse and extract the necessary SAML settings to establish a trust relationship with the IdP. Clients can usually download this metadata file directly from their IdP’s admin portal. It's required for initiating and validating SAML authentication requests. Without a valid metadata XML, the SAML integration cannot function.

Role Mapping

Follow the steps below to configure role based access control:

1. Open the relevant SSO Provider from the SSO Providers list.

2. Navigate to the Role Mapping section on the provider detail page.

3. Ensure Role Attribute Key is set to the attribute name that your IdP uses to send role or group information (for example: role, roles, groups, memberOf).

4. Click Add New to create a new role mapping entry.

5. In IdP role value, enter the exact role or group value sent by the IdP (this value is case sensitive).

6. From the Assigned Role dropdown, select the corresponding FSProtect Role.

7. Click Save to apply the role mapping.