Enroll Windows machines with the Windows Cloud Agent

This topic describes how to enroll Windows machines with the Windows Cloud Agent to enforce adaptive MFA without depending on direct connectivity (LAN or VPN) to the directory source (for example, Active Directory).

Configure adaptive MFA for Windows users

Before you enroll any Windows machines, you should create a policy set to configure adaptive MFA for your Windows users. The Windows Cloud Agent supports the following authentication mechanisms:

  • Mobile Authenticator

    The number matching feature of the Mobile Authenticator is not supported by the Windows Cloud Agent. Please disable Endpoint Policies > Common Settings > Mobile Settings > Security Settings > Require number matching for mobile authenticator to prevent accidental approvals within your Windows Cloud Agent policy set.

  • Email

  • Phone call

  • SMS

  • OATH OTP (HOTP)

  • QR Code (Multiple Authentication Mechanisms)

  • QR Code (Single Authentication Mechanism)

    This is an early access feature. Early access features are made available on a case-by-case basis by request. Early access features might see more frequent updates compared to GA features. Contact your account representative to enable this feature.

  • Security questions

Select passwordless authentication mechanisms to provide your users with a seamless log in experience. Refer to CyberArk Identity Windows Cloud Agent for more information about passwordless authentication, and other benefits of enrolling with the Windows Cloud Agent.

Remember to complete the Prerequisites for deploying the Windows Cloud Agent first.

Step 1: Enable authentication policy controls for Endpoint Authentication

  1. Sign in to the Identity Administration portal.

  2. Go to Core Services > Policies, and then select the policy that you want to edit or click Add Policy Set to create a new one.

    The Policy Settings page opens.

  3. Select the Specified Roles or the Sets option in the Policy Assignment area.

  4. Click Add, find and select the role or set that contains the relevant users or endpoints, then click Add.

  5. Go to Authentication Policies > Endpoint Authentication, then select Yes in the Enable authentication policy controls drop-down menu.

Step 2: Create authentication rules

Configure an authentication policy to enforce adaptive MFA when users log in to their enrolled Windows machines. For example, you could use additional authentication mechanisms if a user tries to log in from outside of your corporate IP range.

  1. Click Add Rule to specify conditional access.

  2. From the Authentication Rule window, click Add Filter

  3. Define the filters and conditions using the drop-down menus.

  4. Click OK

For more information on adding authentication rules, see Create authentication rules.

  • If you configure one-time-passcode (OTP) as an authentication method for your users, as long as endpoint authentication is enabled in your policy setting your users can authenticate using the passcode when their machines are offline. Offline OTP requires that users first log in to User Portal with an internet connection to get the offline code. Direct users to Set up OTPs to authenticate to the User Portal for information on setting up offline OTP.

  • If your users also have an enrolled Android or iOS device, after they successfully authenticate to their cloud agent-enrolled machine, they can refresh the Passcodes section of the CyberArk Identity mobile app to automatically create an offline OTP code.

Step 3: Configure the MFA grace period

From the policy, select Endpoint Policies > Common Settings > Agent Settings > Lock Screen, then make selections for the following grace period settings.

The grace period is the amount of time that an active user session can be accessed without MFA challenges. Examples of accessing an active user session include unlocking the screen or switching between logged on users. If the user session is terminated, the grace period timer restarts.

Multi-factor authentication grace periods

Setting

Description

MFA grace period for OS X and Windows screen unlock

To specify a grace period, select one of the minute or hour values from the drop-down menu. To specify no grace period, select Immediately. In this case, a locked device immediately requires MFA challenges for unlocking. The default value is Immediately.

Any change in the grace period setting takes effect only after the period defined in the Update device information frequency (default 12 hours) setting in Endpoint Policies > Device Management Settings, or if policies are manually pushed, or on device restart.

Enable MFA grace period when device is offline

Use this setting to control whether the MFA grace period is applied for offline devices. This allows you to choose between user convenience or a strict security posture.

There is no limit to authentication attempts or lockout with offline authentication. If MFA is not applied, then an attacker has unlimited password attempts within the grace period to sign in.

The default is equivalent to No, where MFA is always enforced on offline devices.

Self-service password reset is unavailable inside the MFA grace period.

Continue the procedure to configure the optional self-service options, or save the policy set.

Step 4: (Optional) Configure self-service options

See self-service password reset and self-service account unlock for more information.

Enroll Windows machines with the Windows Cloud Agent

You can either enroll a machine individually, or for AD-joined machines you can enroll in bulk.

Step 1: Generate an enrollment code.

You need a randomly generated enrollment code to enroll machine. You must be a member of the System Administrator role to generate enrollment codes.

  1. Sign in to the Identity Administration portal.

  2. Click Settings > Endpoints > Enrollment Codes.

  3. Click the Add button.

    The Generate Bulk Enrollment Codes window appears.

  4. (Optional) Select the details to be used to generate the enrollment code.

    • Set an expiration date if the code should expire.

    • Specify the maximum number of devices that can be enrolled or leave Unlimited selected.

    • Enter a description.

  5. (Optional) Limit the enrollment code to an IP range.

    Only computers with either a Cloud Agent or Device Trust installed and an IP address within the ranges specified can be added to CyberArk Identity using the enrollment code.

    1. Click IP Range Restrictions to specify the IP addresses where the registration code is valid.

    2. Click Add to specify IP ranges manually.

    3. Click Import Secure Zones to automatically add your existing network IP range.

      4. You can also add addresses after importing your corporate IP addresses. For example, you might want to add IP addresses that are outside of the corporate firewall.

  6. Click Save to generate the enrollment code.

  7. Click Copy to copy it to the clipboard.

Step 2: Download and install the Windows Cloud Agent on Windows machines in your organization.

The procedure for installing on an individual machine is appropriate if you are enrolling a server. Use one of the bulk install procedures to deploy the Windows Cloud Agent on workstations throughout your organization.

A bulk deployment that maps one user per machine requires Windows Cloud Agent version 21.3 or higher.

  1. Log-in to the Identity Administration portal.

  2. In the Identity Administration portal, go to Downloads and select Agents from the software list.

    All the agents available for download are displayed.

  3. Download Windows Cloud AgentWindows Device Trust.

  4. When the download completes, use the Windows native package manager to install.

  5. Enter values for the following parameters.

    Mandatory parameters

    Parameter Description

    Tenant URL

    Your tenant URL. You can find it in the Identity Administration portal, Settings > Customization > Tenant URLs.

    Enrollment Code

    Paste the value of the enrollment code generated previously (In the Identity Administration portal, Settings > Endpoints > Enrollment Codes.

    Optional parameters

    Parameter

    Description

    -l <role>

    Specify the role containing the users who you want to be able to sign in to the machine.

    This should be the same role that the policy set enabling Endpoint Authentication is assigned to. Remember to use quotes around role names with spaces.

    If you are setting permissions for a Windows server, add the AD group listed in the server's Remote Desktop Users list to enforce your authentication policies via RDP connections.

    Although users who received permission via role assignment can authenticate to the machine and generate offline OTPs for offline authentication, CyberArk Identity does not consider them the machine owner.

    e <user> where <user> is the user's userPrincipalName

    Users explicitly assigned during enrollment are considered the owner of the device; the user can find the device on the Devices tab of the User Portal.

    If you are enrolling a server that can only access the internet through a proxy server (for example, a domain controller), use -p <proxy url> where <proxy url> is the URL of the proxy server the machine uses to connect to the internet.

    If you are enrolling a server with no open inbound ports, use -p <proxy url>, where <proxy url> is the IP address and port of the server hosting the CyberArk Identity Connector; the CyberArk Identity Connector acts as a proxy to CyberArk Identity.

    If it's necessary, you can give additional users permission later: Grant authentication permission to additional users. Users given permission after enrollment are not considered the machine owner, regardless of whether they are explicitly given permission or given permission via role membership.

  6. Click Finish to enroll the machine.

    If enrollment does not initiate or complete, you can manually enroll the machine using the CLI. Refer to Windows Cloud Agent CLI reference for more information.

This procedure is only applicable to AD-joined machines. It deploys the Windows Cloud Agent on Windows workstations throughout your organization by granting authentication permissions to a role.

  1. Generate the MST file.

    1. Log in the Identity Administration portal.

    2. Click Downloads and select Agents from the software list.

      All the agents available for download are displayed.

    3. Click download for the Windows Cloud Agent.

    4. Create a backup copy of the installer file.

    5. Right-click the installer file and select Edit with Orca.

    6. Select Transform > New Transform.

    7. Select the Property table in the left hand pane.

    8. Right-click in the main pane and select Add Row to specify the relevant properties and values.

    9. Specify the following properties and corresponding values one at a time into the pop-up window:

      Property Value

      Notes

      TENANTURL <tenant url>

      Your tenant URL. You can find it in the Identity Administration portal, Settings > Customization > Tenant URLs. See Configure tenant settings for more information on tenant URLs.
      ENROLLCODE <enrollment code>

      The enrollment code you generated. See Generate an enrollment code..
      PARAM -l <role>

      <role> should be the role containing users you want enrolled. This role should be the same one you specified in your policy assignment settings -- the Identity Administration portal, Core Services > Policies > Policy Settings > Policy Assignment configuration area.

      Although users who received permission via role membership can authenticate to the machine and generate offline OTPs for offline authentication, CyberArk Identity does not consider them the machine owner.

      If it's necessary, you can give additional users permission later: Grant authentication permission to additional users. Users given permission after enrollment are not considered the machine owner, regardless of whether they are explicitly given permission or given permission via role membership.

      Refer to Windows Cloud Agent CLI reference for more information about available parameters.

    10. Repeat the previous steps to create the required properties.

      The following image shows a created tenant URL property/value and the window available for the next property.

    11. Select Transform > Generate Transform to save your modifications to the MST file.

    12. Select Transform > Close Transform.

      Be sure to save the MST file in the same folder as the MSI file. If the MST and MSI files are in different folders, the MST file will not execute when you execute the MSI file.

  2. Deploy the MSI file to your organization.

    Deployment methods include:

    See https://docs.microsoft.com/en-us/windows/win32/msi/transforms for more information about how to specify the transform using your chosen deployment method.

This procedure is only applicable to AD-joined machines. It deploys the Windows Cloud Agent on Windows workstations throughout your organization by mapping individual users to each workstation.

  1. Log in to the Identity Administration portal.

  2. Click Settings > Endpoints > Corporate-owned Devices > Import.
    The Corporate-owned Devices Import window opens.

  3. (Optional) Click the Corporate-owned devices import template link if you need to create the CSV file.

  4. (Optional) For Windows devices, open the CSV file and enter a username with the domain suffix in the Assigned User column to assign each Windows device to a user.

  5. Click Browse, navigate to your CSV file, then upload the file.

  6. Click Next.

  7. Review the data fields and click Next.

  8. Verify the email address for report delivery and click Confirm.
    The imported devices and serial numbers appear in the Corporate-owned Devices list in the Identity Administration portal (Settings > Endpoints > Corporate-owned Devices).

  1. Click Downloads and expandAgents in the software list.

  2. Click download for the Windows Cloud Agent.

  3. Deploy the Windows Cloud Agent with the tool of your choice.

    For example, you could use SCCM. After you deploy the Windows Cloud Agent, only the users assigned in the CSV file can authenticate to each machine.

Grant authentication permission to additional users