ADFS Setup

ADFS Setup#

This guide explains how to set up Squirro Single Sign-On with Microsoft Active Directory Federation Services (ADFS).

Configure AD FS#

This walk-through assumes AD FS 2019, and the screenshots are from Windows Server 2019. The process is very similar on earlier versions.

Relying Party Trust#

  1. Open the AD FS Console and “Add Relying Party Trust…”

    image1

  2. Select the “Claims aware” option

    image2

  3. Enter data about the relying party manually

    image3

  4. For display name enter any name, for example: “Squirro”

    image4

  5. Enable support for the SAML 2.0 WebSSO protocol. The service URL is https://SQUIRRO/sso/callback (URL of your Squirro installation plus the path /sso/callback)

    image5

  6. For the relying party trust identifier enter https://sso.squirro.com/o/saml2/entity

    image6

  7. Decide on an Access Control Policy. For example limited to a given Active Directory group

    image7

  8. In the last step confirm that you want to configure claims issuance policy

    image8

Claim Rules#

  1. Add a new Rule

    image9

  2. Choose the claim rule template “Send LDAP Attributes as Claims”

    image10

  3. Select the “E-Mail-Address” attribute and send it as the “Name ID”. Additionally send the “Given Name” and “Surname”.

    image11

  4. To pass over group memberships, create another claim rule - this one of type “Send Group Membership as Claim”

    image12

  5. Fill out the parameters as follows:

    • Claim rule name: Can be freely chosen, use for example “Group - <groupname>”

    • User’s group: Select the AD group to pass over

    • Outgoing claim type: Group

    • Outgoing claim value: put in the name of the group

      image13

  6. The group membership claim rule can be added more than once, in case multiple groups should be sent over. A good idea is to have a administrator group (e.g. “Squirro_Admins” that is sent as a claim value).

Exchange Mailbox GUID#

If you are going to use the Squirro for Microsoft Outlook integration, Squirro needs to map the user’s Exchange mailbox GUID identifier. This needs to be passed on as an additional Claims Rule.

Edit the claim rule you created earlier, or create a new one, and add the LDAP attribute “msExchMailboxGuid”. As the outgoing claim type also use “msExchMailboxGuid”.

Export Federation Metadata#

Download the FederationMetadata.xml file. This can be downloaded from the ADFS server at https://ADFS_SERVER/FederationMetadata/2007-06/FederationMetadata.xml.

Configure SAML Metadata#

To configure SAML Single Sign-On with the federation metadata file, go to the Server space in Squirro and in the navigation on the left select Single Sign-On (SAML).

Press the red plus button on the top right. Fill out the form:

  • Domain: *

  • Enabled: Check

  • Entity ID: leave empty for the default

  • Metadata file: upload the FederationMetadata.xml file

  • Certificate file: can be left empty

  • User group: Select a user group which should be assigned to all SSO users - this is optional

  • Group names field: put in the value http://schemas.xmlsoap.org/claims/Group

  • Mapping of groups to Squirro roles:
    this defines the server-wide permissions for SSO users based on the group names that were retrieved from the claims
    Example value: Squirro_Admins=admin; Squirro=user; reject
    This example gives admin rights to all users in the Squirro_Admins group, normal access to all users in the Squirro group and rejects all other logins.
  • If passing through the “msExchMailboxGuid” claim, then enter the following value in “Fields to map in as user values”: msExchMailboxGuid

    image14

Enable SSO#

For security reasons, the final configuration needs to be done directly on the server. Log into the server using SSH or similar means and edit the file /etc/squirro/frontend.ini. Then append the following lines at the end:

[security]
sso_enabled = true
sso_endpoint = http://localhost:81/studio/extauth_saml/extauth

Reduce HTTP Session#

With Single Sign-On enabled, Squirro recommends reviewing the session expiration parameters. See Reducing Session Lifetime for information.

Contents