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.
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.
Start by configuring SAML in Cyberwatch, go to Administration > Identity provider.
- 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
- In the “SP Entity ID” field, provide your IDP relying party trust identifier for example
- In the “IDP SSO target URL” field, provide the SSO authentication URL of the ADFS. It should match the format
- For the “Name identifier format”, enter
- For the “IDP Certificate”, provide the public certificate previously exported
- (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:
- (OPTIONAL) Provide LDAP groups for which your users will be created as Cyberwatch Administrator, these groups must match to the users’ LDAP groups.
- 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.
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.
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 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.