ADFS SAML Integration

Introduction

This article describes how to configure an ADFS server to use Sentry to replace the standard Active Directory authentication. This allows a suitably configured environment to support Swivel authentication for Office 365, for example.

Requirements

ADFS integration requires version 4.x of Sentry.

Configuration Procedure

In Swivel Core

ADFS requires the username to be in the format domainusername. To do this, you need to create a Swivel attribute that includes the prefix.

In the Swivel admin console, under the repository details for the relevant AD repository, set the domain qualifier to be the short-form domain name, followed by “” - don’t forget the backslash at the end.

Under Repository -> Attributes, create an attribute - for example, call it “windowsaccountname”. In the definition for the AD repository, put the AD attribute name “sAMAccountName”, and under domain qualifier, select “As Prefix”.

Finally, synchronise the AD repository, to ensure that all users have an attribute in the form domainusername.

In Swivel Sentry

Edit settings.properties

Note

This step is not usually necessary when using version 4.0.3 or later: the correct settings are chosen automatically for ADFS, and can be overridden in the configuration anyway. This assumes that you have added a domain prefix to the repository, and have created an attribute that uses it.

This file is located under /home/swivel/.swivel/sentry on an appliance. Check the following entries:

• certificateIssuer – this must be in the form of a valid URI. It is recommended that you use the public URL of Sentry, but it doesn’t have to be a real web location.
• windowsaccountnamefield=username. This configures the Swivel attribute field to be used to import the username for ADFS. If you have configured a prefixed attribute above, use the name of that attribute. Otherwise, use an attribute mapped to sAMAccountName without a prefix, and set the prefix below. This latter option is the only possibility for Swivel version 3.10.5 or earlier.
• windowsdomainprefix=domain. This configures the domain name to be prefixed to the ADFS username. If the attribute above already has a prefix, this should be blank. If not, make sure the “” is included. Do not set a prefix if your attribute is already prefixed.

Application settings

In the Sentry admin console, create a new application with the following settings:

• Service Provider = ADFS
• Endpoint URL = https://<ADFS_HOST>/adfs/ls/
• Entity ID = http://<ADFS_HOST>/adfs/services/trust

Replace <ADFS_HOST> with the public host name of your ADFS server / proxy. Other than that, the format should not be changed: Endpoint URL should have a / on the end, Entity ID should not. Also, note that Entity ID starts with “http”, “NOT” “https”.

Create SAML Keys on CMI

Keys are used within SAML to create a trust relationship between Sentry (acting as an IDP) and a SAML-compliant service provider. It is important that you create your own keys for this integration and keep the private key secure.

Generating Keys

From the CMI Main Menu select the Appliance Option, then select Sentry Menu option.

You will see the keys that are currently being used by Sentry (if any).

Select Option 1 to Generate New Keys

Give the key a name eg SentryProductionKey Select the key type, RSA or DSA (RSA is recommended for wider compatibility).

Some integrations require keys of a specific type so refer to the appropriate integration guides.

You then need to enter the information required to generate the key. These parameters are:

• Country Name e.g. US. This should be the standard 2-letter ISO country code.
• State or Province e.g. Washington.
• Locality: e.g. Seattle.
• Organisation: Your Company or Organisation Name.
• Organisation Unit: Relevant unit, e.g. Information Technology.
• Common Name: The full server hostname, e.g. sentry.domain.com.
• Email Address: contact email address for the certificate.

Once you have entered all the details the new keys and certificate will be created.

You will be asked if you want to start using the new key immediately. If you say NO you can select the key at a later date.

Warning

Changing the key being used will impact any existing SAML-based integrations. The existing service providers will need to be updated with the new keys.

Selecting a Key

Select the Select New Key option will list all the keys that have been created on the appliance. You can select the key you wish to use.

Note

You need to restart tomcat for the changes to take effect.

In ADFS Management

Claims Provider Trust

Create a new Claims provider trust.

If you can import the metadata directly from the Sentry URL: that is simplest, but it may not work, due to SSL handshaking issues. In which case, download the metadata to a file

and import the settings from that file.

Once you have created the new trust, you will be given the opportunity to add claim rules:

Claim Rules

Create two rules using the template “Pass Through or Filter an Incoming Claim”, as follows:

• Incoming claim type = Name ID: it is recommended that you specify the format as Email, and only pass through claims matching your domain suffix.

• Incoming claim type = Windows Account Name. There is no need to specify any other restrictions on this claim rule.

Settings

You will need to edit the properties of this trust:

• Under Advanced, Secure hash algorithm must match the signing algorithm for the Sentry certificate. Version 4 supports SHA-256, but if you have an older version of Sentry SSO, you must select SHA-1.

• Under Endpoints, there should be two endpoints configured.

If not, create them as follows. If they have been created, check that they match the following. Both are SAML endpoints:

• Endpoint Type = SAML Single Sign-On, Binding = redirect, Trusted URL = https://<sentry_URL>/sentry/saml20endpoint

• Endpoint Type = SAML Logout
• Binding = redirect
• Trusted URL = https://<sentry_URL>/sentry/singlelogout
• Response URL = https://<sentry_URL>/sentry/singlelogout

• Under Certificates:

View the imported certificate:

Then click on “Install Certificate”.

Select “Local Machine” on the next page:

and on the following page, “Place all certificates in the following store”. Browse and select “Trusted Root Certification Authorities”.

Disable Active Directory authentication

As ADFS is currently configured, you will now have a choice of Active Directory or Swivel authentication. To disable Active Directory authentication:

• Edit C:WindowsADFSMicrosoft.IdentityServer.Servicehost.exe.config.

Note that you must open your text editor (for example Notepad) as administrator, or you will not be able to save the changes.

• Search for “<localAuthenticationTypes” and set enabled to “false”.
• Restart ADFS.

Implement Sentry Authentication Selectively

If you don’t want to use Sentry authentication for all ADFS applications, or in all scenarios, you can use the PowerShell cmdlets to control it. Some examples are given in the following link:

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/home-realm-discovery-customization

Potentially the most useful scenarios would be to bypass Sentry for intranet login:

Set-AdfsProperties -IntranetUseLocalClaimsProvider $true

or to use Sentry for selected relying parties only:

Set-AdfsRelyingPartyTrust -TargetName "Office 365" -ClaimsProviderName @("Sentry SSO")