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.

To achieve this, 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 this 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. For the “Name identifier format”, enter urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  2. In the “Text of the login button” 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
  3. In the “SP Entity ID” field, name the relying party trust identifier of your IDP, for example CYBERWATCH
  4. OPTIONAL It is possible to provide the “IDP Entity ID” with the value of the entityID field extracted from the IDP metadata file, it format should look like http://[IDP_URL]/adfs/services/trust
  5. 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
  6. For the “IDP Certificate”, provide the public certificate previously exported
  7. Save the configuration

Once the configuration saved, the Cyberwatch SP metadata URL is activated and 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 automatically in ADFS.

OPTIONAL - Configure the attributes in Cyberwatch

Display attributes configurations details and explanations

Attribute configuration is optional, it allows to automatically attribute users’ roles, groups, e-mail address, etc. and other attributes specific to Cyberwatch such as one’s ability to access Kibana or see all assets.

The following explains and provides configuration examples of all these options for using these attributes with SAML ADFS.

Roles configuration

The “Roles attribute” field allows to set an attribute used to automatically assign roles to SAML users in Cyberwatch.

Depending on this attribute value, users will be assigned a role choosing from Administrator, System administrator, Security Administrator, Auditor depending on the value of the attribute set in the Cyberwatch configuration for each of these roles.

In this example, we will be using users Active Directory groups in order to define their roles in Cyberwatch.

  1. For the « Roles attribute » field, set the value to http://schemas.xmlsoap.org/claims/Group
  2. For the « Administrator » field, set the value to cbw_admin
  3. For the « System Administrator » field, set the value to cbw_admin_sys
  4. For the « Security Administrator » field, set the value to cbw_admin_secu
  5. For the « Auditor » field, set the value to cbw_audit

With this configuration, an user who belongs to one of the LDAP groups provided as a value will be automatically assigned to the role associated to this value.

A LDAP user which does not belong to any of the specified groups will be assigned the Auditor role.

A LDAP user which belongs to more than one of these groups will be assigned the role with the most privileges.

Groups configuration

The “Groups attribute” field allows to set an attribute which will be used to automatically assign groups to SAML users in Cyberwatch.

In the “Groups attribute” field, provide the value http://schemas.xmlsoap.org/claims/Group.

An user connecting with SAML will automatically be assigned to the AD groups to which he belongs, provided these groups already exist in Cyberwatch.

It is necessary that the groups be already created in Cyberwatch and that their names be identical to the AD/LDAP groups names.

Access to all assets / Access to Kibana

The way the “Access to all assets” and the “Access to Kibana” work is identical.

It consists in setting an attribute that will be used to automatically allow the access to all assets or the access to Kibana to SAML users.

Keeping the LDAP groups example, it is for instance possible to use the http://schemas.xmlsoap.org/claims/Group attribute.

A working example could be:

Access nameAttributeincluded in
Access to all assetshttp://schemas.xmlsoap.org/claims/Groupcbw_all_assets
Access to Kibanahttp://schemas.xmlsoap.org/claims/Groupcbw_kibana

Email address, Description and Full name attributes

These three attributes work the same way. They provide a way to define a SAML attribute, which value’s will be used to respectively populate the user e-mail address, description and full name.

Working with these attributes may require complementary claim rules configuration 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.

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.

Back to top