:orphan: ********************* 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 domain\username. 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. .. image:: images/Integration/SAML/Microsoft_ADFS/CoreRepositoryQualifier.png 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". .. image:: images/Integration/SAML/Microsoft_ADFS/CoreWindowsUsernameAttribute.png Finally, synchronise the AD repository, to ensure that all users have an attribute in the form domain\username. 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/ls/ * Entity ID = \http:///adfs/services/trust Replace 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". .. image:: images/Integration/SAML/Microsoft_ADFS/AdfsApplication.jpg .. include:: HowToCreateSAMLKeysOnCMI.rst """""""""""""""""" In ADFS Management """""""""""""""""" Claims Provider Trust """"""""""""""""""""" Create a new Claims provider trust. .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider1.PNG 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 .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_Metadata.png 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: .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider2.png * Incoming claim type = Name ID: it is recommended that you specify the format as Email, and only pass through claims matching your domain suffix. .. image:: images/Integration/SAML/Microsoft_ADFS/ClaimsProvider3.png * Incoming claim type = Windows Account Name. There is no need to specify any other restrictions on this claim rule. .. image:: images/Integration/SAML/Microsoft_ADFS/ClaimsProvider4.png 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. .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Advanced.png * Under Endpoints, there should be two endpoints configured. .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Endpoints.png 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/saml20endpoint .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Endpoint1.png * Endpoint Type = SAML Logout * Binding = redirect * Trusted URL = \https:///sentry/singlelogout * Response URL = \https:///sentry/singlelogout .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Endpoint2.png * Under Certificates: .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Certs.png View the imported certificate: .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Cert_View.png Then click on "Install Certificate". .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Cert_Install1.png Select "Local Machine" on the next page: .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ClaimsProvider_Cert_Install2.png 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:\Windows\ADFS\Microsoft.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. .. image:: images/Integration/SAML/Microsoft_ADFS/Sentry_ADFS_ServiceConfig.png * Search for “