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.
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.
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.
Start by configuring SAML in Cyberwatch, go to Administration > Identity provider.
- For the “Name identifier format”, enter
- 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
- In the “SP Entity ID” field, name the relying party trust identifier of your IDP, for example
- OPTIONAL It is possible to provide the “IDP Entity ID” with the value of the
entityIDfield extracted from the IDP metadata file, it format should look like
- In the “IDP SSO target URL” field, provide the SSO authentication URL of the ADFS. It should match the format
- For the “IDP Certificate”, provide the public certificate previously exported
- 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.
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.
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.
- For the « Roles attribute » field, set the value to
- For the « Administrator » field, set the value to
- For the « System Administrator » field, set the value to
- For the « Security Administrator » field, set the value to
- For the « Auditor » field, set the value to
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.
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
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.
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
A working example could be:
|Access to all assets
|Access to Kibana
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.
From the ADFS server, open the snap-in “ADFS management”.
Add a relying party trust by following the steps below:
- Open the folder “AD FS” in the navigation pane on the left of the snap-in
- Right click “Relying Party Trusts”
- Select “Add Relying Party Trust…”, the Relying Party Trust wizard opens
- On the “Welcome” screen of the wizard, choose the option “Claims aware”
- On the “Select Data Source” screen, select “Import data about the relying party from a file” and import the file
- On the “Specify Display Name” screen, assign a name to your relying party trust; for example
- On the “Choose Access Control Policy” screen, select “Permit everyone” or any other option you may want to configure
- On the “Ready to Add Trust” screen, review and validate your settings
- On the “Finish” screen, select “Configure claims issuance policy for this application” and close
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:
- On the relying party trust
Cyberwatch SAMLjust created, right click “Edit claim issuance policy…”
- A configuration wizard opens, offering to create “Issuance Transform Rules”
- Click on “Add Rule…”
- On the step “Choose Rule Type”, select “Send LDAP Attributes as Claims”
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-Addressesfor the LDAP attribute and
- for permissions management later in Cyberwatch, select the entry
Token-Groups - Unqualified namesfor the LDAP attribute and
Groupfor the outgoing claim type
- confirm rule creation
Add another rule, this time by selecting
Transform an Incoming Claimfor the rule template. For the rule configuration:
- name the claim rule
Unspecifiedfor the “Incoming Name ID format”
Name IDfor the “Outgoing claim type”
- select the option
Pass through all claim values
Configuration regarding ADFS is now done and should be valid.
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 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
email@example.com for any technical help regarding configuration.