ZVM Appliance

ZVM Appliance

© 2023 Zerto All rights reserved.

Information in this document is confidential and subject to change without notice and does not represent a
commitment on the part of Zerto Ltd. Zerto Ltd. does not assume responsibility for any printing errors that may
appear in this document. No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any
purpose other than the purchaser's personal use, without the prior written permission of Zerto Ltd. All other marks
and names mentioned herein may be trademarks of their respective companies.
The scripts are provided by example only and are not supported under any Zerto support program or service. All
examples and scripts are provided "as-is" without warranty of any kind. The author and Zerto further disclaim all
implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a
particular purpose.
In no event shall Zerto, its authors, or anyone else involved in the creation, production, or delivery of the scripts be
liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business
interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the
sample scripts or documentation, even if the author or Zerto has been advised of the possibility of such damages. The
entire risk arising out of the use or performance of the sample scripts and documentation remains with you.

2
Table of Contents
IDP Using SAML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3
ZVM Appliance

IDP Using SAML

The following is the required method to connect ZVM Appliance Keycloak with Active Directory (AD) using SAML
IDP.

Note: Select the Zerto or ZSSP realm depending on which you are defining users for.

Prerequisites
• Active Directory Federation Services (ADFS) server that is reachable fromZVM Appliance. ADFS is a Microsoft
product that enables SAML authentication on top of Active Directory.
• Access to manage the ADFS server.
Create IDP in Keycloak
1. Browse to your ZVML with the following URL: https://<zvml_ip>/auth/ and click Administration Console to
enter the Keycloak administration console.

2. Enter admin user credentials: username - admin, password - admin

3. In the upper left drop-down, select the relevant realm that you are creating users for: Zerto or ZSSP
4. Go to Identity Providers and select SAML v2.0

4
ZVM Appliance

5. Add a SAML provider.

6. Fill in the following:

• Alias: unique name for this IDP.
• Display Name: The name that will be displayed in the login page.

5
ZVM Appliance

7. Download the SAML configuration from your ADFS server by browsing to the following URL: https://
<adfs_server>/FederationMetadata/2007-06/FederationMetadata.xml
*<adfs_server> = ADFS server DNS name. This will download an XML file to your browser.
8. Save the XML file.
9. In Keycloak under SAML settings:
• Uncheck Use entity descriptor.
• Select Browse and navigate to the XML you downloaded.

6
ZVM Appliance

10. Scroll down and enable Want AuthnRequests Signed.

11. In SAML Signature Key Name, select CERT_SUBJECT.
12. Enable Validate Signature.
13. Open the XML file and search for <KeyDescriptor> with use="signing" attribute.
14. Copy your <X509Certificate> value. For example:

15. Paste it in the Validating X509 Certificates field and click Add.

Configure ADFS for Keycloak

Get Required Descriptor File from Keycloak:
1. In Keycloak, go to Identity Providers and edit your newly created IDP.
2. In Endpoints, click the link.

7
ZVM Appliance

3. A new tab with an XML opens. Save this XML to your desktop.
4. Log in to your ADFS server in RDP.
5. Copy the Keycloak XML file to your ADFS server desktop.
Configure ADFS 2016
1. Open AD FS Management from your Windows Start menu.
2. In the left navigation tree click Access Control Policies.

8
ZVM Appliance

3. In Actions, click Add Access Control Policy… A wizard opens.

4. Fill in as follows:
• Name: Enter a name for the access control policy, for example: Permit everyone with credentials at sign in.
• Check Require users to provide credentials each time at sign in.
5. Click Add and the Rule Editor window opens.
6. Under Permit select everyone.

9
ZVM Appliance

7. In the left navigation tree, open Trust Relationships > Relying Party Trusts.

10
ZVM Appliance

8. In the Welcome page click Start.

9. In the Select Data Source tab, select Import data about the relying party from a file.
10. Click the Browse button and locate the Keycloak XML file in the desktop and click Next.
11. In the Specify Display Name tab, enter display name for the Keycloak relying party trust. Can be Keycloak
12. In the Choose Access Control Policy tab, select the Access Control policy added earlier and click Next.

11
ZVM Appliance

13. In the Ready to Add Trust tab click Next.

14. In the Finish tab, uncheck the checkbox and click Close.
Configure ADFS 2012
1. Open AD FS Management from your Windows Start menu.
2. In the left navigation tree click Relying Party Trusts.
3. In Actions, click Add Relying Party Trust to open the wizard.

12
ZVM Appliance

4. In the Welcome tab, click Next.

13
ZVM Appliance

5. Select the data source tab, click Import data about the relying party from a file.
6. Click the Browse button and locate the Keycloak XML file in the desktop and click Next.
7. Specify Display Name - enter display name for the Keycloak relying party trust, can be Keycloak.
8. In the Configure Multi-Factor Authentication Now? tab, click Next. MFA can be configured separately.
9. In the Choose Issuance Authorization Rules tab, click Next.
10. In the Ready to Add Trust tab, click Next.
11. In the Finish step, uncheck the checkbox and click Close.
12. In the AD FS file explorer, navigate to Authentication Policies > Per Relying Party Trust and double-click
the one you just created.

14
ZVM Appliance

13. Select the Users are required to provide credentials each time at sign in checkbox and click OK.
Configure ADFS Claim Rules
1. In the AD FS file explorer, navigate to Trust Relationships > Relying Party Trusts, select the one you just
created. Click Edit Claim Rules…

15
ZVM Appliance

2. In Edit Claim Rules for Keycloak Relying Party Trust, click Add Rule to set Name ID rule

16
ZVM Appliance

3. From the drop-down list select Transform an Incoming Claim.

17
ZVM Appliance

4. Configure the claim rule.

18
ZVM Appliance

5. Fill in the following:

• Claim rule name: Name ID
• Incoming claim type: UPN
• Outgoing claim type: Name ID
• Outgoing name ID format: Email
6. Set AD Attributes rule:
a. Click Add Rule.
b. From the drop-down list select Send LDAP Attributes as Claims.

19
ZVM Appliance

c. Type in the following values for each field. The names of the outgoing claim types are based on the
OIDC claim naming.

•E-Mail-Addresses: email
•Given-Name: given_name
•Surname: family_name
•SAM-Account-Name: sub
•Token-Groups as SIDs: group_sid
•objectSid: primary_sid This field is not included and must be manually added.
7. In the Edit Claim Rules wizard, click OK.
Configure IDP Mappers
1. In Keycloak Administration, go to Identity Providers and edit your IDP.
2. Go to Mappers tab.

20
ZVM Appliance

3. Click Add Mapper to create an Email mapper.

4. Fill in the following:

• Name: Email mapper
• Sync mode override: Force
• Mapper Type: Attribute Importer
• Friendly Name: email

21
ZVM Appliance

• User Attribute Name: email

5. In the Mappers page, click Add mapper to create First Name mapper.

6. Fill in the following:

• Name: First Name mapper
• Sync mode override: Force
• Mapper Type: Attribute Importer
• Friendly Name: given_name
• User Attribute Name: firstName
7. In the Mappers page, click Add mapper to create Last Name mapper.
8. Fill in the following:
• Name: Last Name mapper
• Sync mode override: Force
• Mapper Type: Attribute Importer
• Friendly Name: family_name
• User Attribute Name: lastName
9. In the Mappers page, click Add mapper to create User SID mapper.
10. Fill in the following:
• Name: User SID mapper
• Sync mode override: Force
• Mapper Type: Attribute Importer
• Friendly Name: primary_sid
• User Attribute Name: userSid
11. In the Mappers page, click Add mapper to create Groups SIDs mapper.
12. Fill in the following:

22
ZVM Appliance

• Name: Groups SIDs mapper

• Sync mode override: Force
• Mapper Type: Attribute Importer
• Friendly Name: group_sid
• User Attribute Name: groupsSid
Configure Keycloak Client Mappers
1. In Keycloak Administration, go to the Clients tab and select zerto-client.

2. Go to the Client scopes tab and select zerto-client-dedicated.

3. In the Mappers page, click Add Mapper to create User SID mapper.

23
ZVM Appliance

4. Fill in the following:

• Mapper Type: User Attribute
• Name: User SID mapper
• User Attribute: userSid
• Token Claim Name: userSid
• Claim JSON Type: String
5. In the Mappers page, click Add Mapper to create Groups SID mapper.

24
ZVM Appliance

6. Fill in the following:

• Mapper Type: User Attribute
• Name: Groups SID mapper
• User Attribute: groupsSid
• Token Claim Name: groupsSid
• Claim JSON Type: String
• Add to ID token: ON
• Add to access token: ON
• Add to user info: ON
• Multivalued: ON
• Aggregate attribute values: ON
Verify Login
1. Browse to your ZVM Appliance at https://<zvml_ip>/.
2. In the login page click the IDP you have created.

25
ZVM Appliance

3. In the ADFS login page, enter the AD user credentials.

26
ZVM Appliance

You are then redirected to ZVM and logged in as the AD user.

Configure Groups in Active Directory for Roles and Permissions
Map the AD group to the Keycloak Zerto role, by adding a rule in ADFS and a matching mapper in Keycloak.
The available Zerto roles are:

• ZertoRole_Admin
• ZertoRole_Builder
• ZertoRole_User
• ZertoRole_FileLevelRestoreOperator
• ZertoRole_Viewer

1. Create a group for the specific role in Active Directory, in this example Zerto-Viewers.
2. Connect to ADFS server using a remote desktop and open AD FS Management from your Windows Start
menu.

27
ZVM Appliance

3. Navigate to Relying Party Trust and select the Keycloak relying party trust.
4. In Actions, click Edit Claim Issuance Policy…
5. Click Add Rule… and select Send Group Membership as a Claim from the drop-down list.

28
ZVM Appliance

6. Fill in the form as follows:

29
ZVM Appliance

• Claim rule name: zerto-viewers-role claim

• User’s Group: Browse to find your group in AD, (Zerto-Viewers group).
• Outgoing claim type: Group
• Outgoing claim value: zerto-viewers-role

7. Click Finish and then OK to exit the Edit Claim Rules wizard.

Configure Roles and Permissions for IDP in Keycloak

1. Browse to Keycloak Administration using https://<zvml_ip>/auth/.

2. Go to Identity Providers to edit your IDP.
3. Go to the Mappers tab.

30
ZVM Appliance

4. Click Add Mapper.

5. Fill in as follows
• Name: zerto-viewers role mapper
• Sync mode override: Force

31
ZVM Appliance

• Mapper Type: SAML Attribute to Role

• Attribute Name: http://schemas.xmlsoap.org/claims/Group
• Attribute Value: zerto-viewers-role
• Role: Part of zerto-client roles. Select ZertoRole_Viewer in this example, using the Select a role drop-
down list.
6. Click Save.
7. Log in to ZVM using one of the users associated to the group.

Configure Multi-Factor Authentication for AD Users (Optional)

1. In Keycloak Administration, navigate to Authentication > Required Actions tab.

2. For Configure OTP check the Set as default action checkbox.

32
ZVM Appliance

3. When you log in to Zerto, you will need to set up your one time password.

33
ZVM Appliance

34
ZVM Appliance

Access to Management Console with AD User

In order to perform actions in the ZVM Appliance Management Console, you need the Keycloak role called
admin.
1. Create a group in Active Directory for Zerto admins, for example zerto-admins.
2. Connect to ADFS server using RDP and open AD FS Management.
3. Navigate to Trust Relationships > Relying Party Trust. Select the Keycloak relying party trust and click Edit
Claim Rules…

4. Click Add Rule… and select Send Group Membership as a Claim from the list.

35
ZVM Appliance

5. Fill in the following:

36
ZVM Appliance

• Claim rule name: zerto-admins claim

• User’s Group: Browse to find your group in AD, in this case - zerto-admins group.
• Outgoing claim type: Group
• Outgoing claim value: zerto-admins
6. Click Finish and then OK to exit the Edit Claim Rules screen.
7. Browse to Keycloak Administration using https://<zvml_ip>/auth/.
8. Go to Identity Providers and edit your IDP.
9. Go to the Mappers tab and click Add mapper.

37
ZVM Appliance

10. Fill in the following:

• Name: zerto-admins role mapper
• Sync mode override: Force
• Mapper Type: SAML Attribute to Role
• Attribute Name: http://schemas.xmlsoap.org/claims/Group
• Attribute Value: zerto-admins
• Role: admin (select using the Select a role drop-down)
11. Click Save.
12. Browse to the ZVM Appliance Management Console at https://<zvml_ip>/management/ with an AD user that
part of the zerto-admins group to perform relevant actions.
Known Issues
• Clock mismatch between ZVM Appliance and ADFS server can cause an assertion exception in Keycloak
when trying to login through ADFS.
Impact: user login fails on timeout.
Resolution: Match the server clocks accordingly. Alternatively, edit the IDP settings in Keycloak, and in
Allowed clock skew enter the number of seconds that is allowed for the clock mismatch between the
servers.

38
ZVM Appliance

39