Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Documentation

SAML configuration example using the component Active Directory Federation Services (ADFS)

This documentation provides steps to configure SAML authentication in Cyberwatch using a Microsoft ADFS Identity Provider.

This should serve as a simplified example, to setup a minimal working configuration of SAML authentication in Cyberwatch.

Prerequisites

This procedure assumes the following prerequisites:

  • a running Windows Server 2019;
  • an Active Directory instance where the attribute “email” of all users is defined;
  • an SSL certificate for the ADFS login page;
  • ADFS installed on the Windows server.

These prerequisites can obviously be adapted to your environment, the procedure will for example work just as well with a Windows Server 2016 instead of 2019.

Getting the IDP certificate

First of all, get the IDP certificate that will be used for the step 5°) of the Cyberwatch configuration.

Download the IDP XML metadata file from the URL: https://[IDP_URL]/federationmetadata/2007-06/federationmetadata.xml

Two certificates should be present in the <X509Certificate> fields. Extract the first certificate contained in the <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> section of the XML.

Keep the certificate, it will be used in the next step for the SAML configuration in Cyberwatch.

SAML configuration in Cyberwatch

Start by configuring SAML in Cyberwatch, go to Administration > Identity provider.

  1. In the “Label” field, provide a value of your choice, for example ADFS authentication. This string will be used to create the connection button on the Cyberwatch signin page
  2. In the “SP Entity ID” field, provide your IDP relying party trust identifier for example CYBERWATCH
  3. In the “IDP SSO target URL” field, provide the SSO authentication URL of the ADFS. It should match the format https://[IDP_URL]/adfs/ls
  4. For the “Name identifier format”, enter urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  5. For the “IDP Certificate”, provide the public certificate previously exported
  6. (OPTIONAL) For the “Roles attribute” field, provide the claim to be used for users’ rights management. In our case, we configured it so that the outgoing claims provide groups. ADFS documentation regarding SAML specifies the value sent is the following: http://schemas.xmlsoap.org/claims/Group
  7. (OPTIONAL) Provide LDAP groups for which your users will be created as Cyberwatch Administrator, these groups must match to the users’ LDAP groups.
  8. Save the configuration

Once the configuration saved, the Cyberwatch SP metadata URL provides a link to download the XML metadata file of the Cyberwatch application named saml_metadata. Download it, the file will be used to help configure the settings in ADFS.

ADFS configuration

Creating a Relying Party Trust

From the ADFS server, open the snap-in “ADFS management”.

Add a relying party trust by following the steps below:

  1. Open the folder “AD FS” in the navigation pane on the left of the snap-in
  2. Right click “Relying Party Trusts”
  3. Select “Add Relying Party Trust…”, the Relying Party Trust wizard opens
  4. On the “Welcome” screen of the wizard, choose the option “Claims aware”
  5. On the “Select Data Source” screen, select “Import data about the relying party from a file” and import the file saml_metadata generated earlier
  6. On the “Specify Display Name” screen, assign a name to your relying party trust; for example Cyberwatch SAML
  7. On the “Choose Access Control Policy” screen, select “Permit everyone” or any other option you may want to configure
  8. On the “Ready to Add Trust” screen, review and validate your settings
  9. On the “Finish” screen, select “Configure claims issuance policy for this application” and close

Creation of Claim Rules

Once the relying party trust has been created, add claim rules to send Cyberwatch required information to handle the authentication.

This example demonstrates how to create two rules that will make the SAML authentication functional, following the steps below:

  1. On the relying party trust Cyberwatch SAML just created, right click “Edit claim issuance policy…”
  2. A configuration wizard opens, offering to create “Issuance Transform Rules”
  3. Click on “Add Rule…”
  4. On the step “Choose Rule Type”, select “Send LDAP Attributes as Claims”

  5. On the step “Configure Claim Rule”:

    • name the claim rule
    • select “Active Directory” as the Attribute Store
    • on the table of mapping of LDAP attributes to outgoing claims, select E-Mail-Addresses for the LDAP attribute and Email for the outgoing claim type
    • for permissions management later in Cyberwatch, select the entry Token-Groups - Unqualified names for the LDAP attribute and Group for the outgoing claim type
    • confirm rule creation

  6. Add another rule, this time by selecting Transform an Incoming Claim for the rule template. For the rule configuration:

    • name the claim rule
    • select Email for the “Incoming claim type”
    • leave Unspecified for the “Incoming Name ID format”
    • select Name ID for the “Outgoing claim type”
    • select Email for the “Outgoing name ID format”
    • select the option Pass through all claim values
    • finish

Configuration regarding ADFS is now done and should be valid.

Checking everything is working and troubleshooting

Open a new private navigation window and go to the Cyberwatch authentication page.

A new blue button ADFS authentication should be present (depending on the value entered on the step 1°) of the configuration in Cyberwatch).

Click on this button, if the configurations in both ADFS and Cyberwatch are valid, the browser should redirect to an ADFS authentication page.

Provide your LDAP account credentials in order to authenticate to the SAML ADFS service. Assuming everything is working, you will be redirected to Cyberwatch and connected with your user.

N.B. Make sure you do not already have a local/LDAP account in Cyberwatch using the same e-mail address provided for the SAML authentication, as you will encounter an error trying to connect.

Troubleshooting

Troubleshooting can be necessary, and is greatly facilitated by being able to visualize SAML requests.

Consulting these requests can generally be done using a browser extension, such as SAML-tracer for example.

Feel also free to contact us at support@cyberwatch.fr for any technical help regarding configuration.