Deployment reference

Overview

Deployment policies specify how agents are installed on user devices. This article describes each element of the Deployment Policies interface.

Considerations

This article assumes you understand the introduction to deployment provided by the article Deploy agents.

• To use these deployment tools, you need to sign in to the Incydr console as a user with the Security Administrator role. 
• Do not restore Incydr application files backed up from one device as a means to install the insider risk agent on a different device. Application files are unique to each device and cannot be transferred to a new device.
• In the Incydr federal environment, backup agent installations must be deployed with a deployment policy to ensure the use of FIPS encryption. Users cannot download the installation package from the Incydr console or an email message.

Need help?
For assistance, contact your Customer Success Manager (CSM) to engage the Incydr Professional Services team. If you don't know who your CSM is, contact our Technical Support Engineers.

Insider risk agent

Deployment policies

To view and manage deployment policies:

1. Sign in to the Incydr console.
2. Select Administration > Agent Management > Deployment.

If your environment does not yet have any deployment policies, you see the option to Create deployment policy. If your environment already has one or more policies, you see the deployment policies list.

Item		Description
a	Create deployment policy	Open the interface for defining a new insider risk agent deployment policy.
b	Name	The name of the policy.
c	Created	The date the policy was created and the username of the administrator who created the policy.
d	Registration organization	Insider risk agents deployed with this policy register with this organization.  The organization determines the authentication method and optional proxy address for the policy. If you deactivate an organization, the associated policy will not work.
e	Organization Status	The status of the registration organization.
f	View details	Allows you to view and change details of the policy.

Policy details

In the deployment policies list, click View details  to see details about the policy.

Item		Description
a	Policy name	The name of the policy.
b	Delete	Removes the policy from your environment. Insider risk agents deployed to use that policy, but not yet run and installed, will fail to install.
c	Edit	Change details of the policy.
d	Details	The details of the policy.
e	Scripts	The user detection scripts for the policy.
f	Registration  organization	Insider risk agents deployed with this policy register with this organization. If your custom script specifies a value for C42_ORG_REG_KEY, only users not covered by the script register to this organization.  The organization determines the authentication method and optional proxy address for the policy.
g	Created and Last modified dates	The dates the policy was created and last saved.
h	Configured operating systems	The operating systems the policy is configured for (Windows, Mac, or Linux).
i	Use organization's proxy URL	Specifies whether agents should use a proxy URL to connect to the Incydr cloud.
j	Deployment properties	Use these strings as arguments to a command that installs an insider risk agent: DEPLOYMENT_URL: The address of your Incydr console. The insider risk agent requests its deployment policy from this address. DEPLOYMENT_POLICY_TOKEN: A unique ID string that identifies each deployment policy.   DEPLOYMENT_SECRET: The deployment secret that authorizes the agent and limits the time in which an agent can register.  The file can also optionally contain a PROVIDED_USERNAME parameter that bypasses the user detection script altogether and simply registers with the provided username. Click the links to download or copy the properties. For more information about the DEPLOYMENT_URL and DEPLOYMENT_POLICY_TOKEN, see Deployment script and command reference for the insider risk agent.
k	Command-line arguments	These strings provide arguments for a command that installs an insider risk agent. Use them in your device management tool or installation scripts. See Deployment script and command reference for the insider risk agent for more details.

Scripts

In the policy details view, click the Scripts tab. To update the scripts, click Edit.

For information about user detection scripts, see Deployment script and command reference for the insider risk agent.

Requirements for multiple agents

Deploying both the insider risk and backup agents to a single device requires:

• Two code42.deployment.properties files (the deployment policy contains separate properties for each agent type).
• A single user detection script. Only use the user detection script for the backup agent; it also detects the user for the insider risk agent. If you use the detection script for the insider risk agent, the backup agent will not be able to register.

Create or edit deployment policy

In the Deployment policies view, select Create deployment policy, or in the policy details click Edit.

Item		Description
a	Deployment policy name	Enter a name to describe and identify this policy.
b	Registration organization	Select the organization to use this deployment policy.  Users register according to the authentication method and directory services configured for their organization. If an organization already has another deployment policy, it is excluded from the dropdown list. Choose a different organization, or edit the existing policy for that organization. If you have a custom script that specifies a value for C42_ORG_REG_KEY (see item g below), only users not covered by the script register to this organization.
c	User detection scripts	The user detection script settings below specify how users are associated with an installed agent.
d	Domains allowed	Specify the user email domains approved for agent deployment. If you are deploying to users on more than one domain, enter a comma-separated list (for example: example.com, company.org).
e	Excluded users and domains	To prevent specific domains or users from registering, enter one or more values separated by a comma. Default exclusions include common personal email domains and administrator accounts: *@yahoo.com, *@gmail.com, *@outlook.com, admin, admin1, admin2, Administrator, admin-*, jamfadmin, local, _mbsetupuser, reboot, root, shutdown, user1
f	Select operating systems	Select the operating systems to which this policy applies. For example, if you are deploying the insider risk agent to both Windows and Mac endpoints, select both Windows and Mac. Then select a script type for each operating system.
g	Script type	Select the user detection method (options vary by operating system): Current username plus domain: Detects users running explorer.exe and appends the domain of the email address. Domain joined: Detects users running explorer.exe and determines their email addresses from the directory. First and last name plus domain: Detects the locally logged-in users' display name, then separates it into first and last names. Google username: Detects the current logged-in user by querying the Windows Registry and the Google Credential Provider for Windows. Last logged in user: Detects the username of the most recent user to log in to the device's operating system, then appends the company domain to make an email address. macOS plist: Reads a .plist file on the local device populated with the email address supplied by your macOS mobile device management (MDM) tool. Read from file: Reads a text file for the user's email address. Custom: Supply your own user detection script. Custom script details A custom script enables you to define how the username and the user's organization are determined. A summary of script requirements is listed below, but for complete details about customizing scripts, see Deployment script and command reference for the insider risk agent. All custom scripts must end by writing the C42_USERNAME variable to standard output (see below). C42_ORG_REG_KEY can also be included to define the organization, but this is optional. If C42_ORG_REG_KEY is not present, the insider risk agent uses the default organization selected for this deployment policy. echo C42_USERNAME=<value> echo C42_ORG_REG_KEY=<value> Usernames must be email addresses. To specify an organization, use the registration key. For assistance with custom scripts, contact your Customer Success Manager (CSM) to engage the Incydr Professional Services team.
h	Do your clients need a proxy URL to connect to the Code42 cloud?	No: Insider risk agents communicate with the cloud directly. Yes: The Registration Org requires insider risk agents to communicate through a proxy server. To see the URL of an organization's proxy auto-config (PAC) file, go to Administration > Organizations > [select an organization] > Proxy.

Deployment secrets

In the deployment policies view, click Deployment secrets to see available secrets. 

Deployment Secrets are used in the policy details to authorize the agent and limit the time in which an agent can register. Every deployment policy must have a deployment secret. A deployment secret can be used by any deployment policy for any organization in the tenant. 

Deployment secrets expire after a set amount of time to ensure ongoing security. By default, deployment secrets expire after one year. If a secret expires, you can extend it to reactivate it. 

Deployment secrets expire after one year
Before the end of the one-year period, extend the secret to authorize its use for another year. If a deployment secret expires, deployments using that secret fail until the secret is extended.

To disable a deployment policy, revoke the secret
You can disable a deployment policy at any time by revoking the deployment secret. The policy definition remains intact, but insider risk agents actively making requests for this policy can no longer use the policy. To re-enable the policy, extend the secret.

Item		Description
a	Active	Select to show active secrets that can be used in deployment policies.
b	Expired	Select to view secrets that have passed their expiration date or have been revoked. When viewing expired secrets, click Reactivate to reinstate the secret.
c	Create deployment secret	Create a new secret that can be used in deployment policies. By default, newly-created secrets do not expire for one year.
d	Secret	The secret's unique string. Secrets appear in the policy's details. A deployment token must always be presented with a secret in the deployment policy.
e	Expiration date (UTC)	The date the secret is no longer valid to authorize an agent installation. The time is based on the device’s system clock and reported in Coordinated Universal Time (UTC).
f	Extend	Lengthen the amount of time that the secret is active by a year.
g	Revoke	Nullify the secret. Revoking the secret prevents registration for clients deployed with the secret that have not yet connected to the Incydr cloud. Clients already registered with the secret are not affected. To re-enable the policy, extend the secret.

Uninstall secrets

Requires insider risk agent version 1.10.0 or later. Windows and Mac devices only.

Uninstall secrets prevent unauthorized users from removing the insider risk agent by requiring a code to uninstall. Maintaining better control over who can uninstall the agent helps keep your data more secure by ensuring the insider risk agent continues running on user devices.

To view and manage uninstall secrets:

1. Sign in to the Incydr console as a user with the Custom Cloud Admin or Security Administrator role.
2. Select Administration > Agent Management > Deployment.
3. Select the Uninstall secrets tab.

Considerations

• Active secrets are valid for all devices in your organization.
• To facilitate secret rotation, you can create multiple secrets with varying expiration dates.
• Agents requiring an uninstall secret can only be uninstalled via the command line. The secret must be included as a parameter in the uninstall command.
• To uninstall the agent with a secret listed on the Deployment > Uninstall secrets tab, the device must be online and able to connect to the Incydr cloud. To uninstall the agent from an offline device, use a temporary Agent secret instead.
• To help an end user uninstall the agent from a single device (while troubleshooting, for example), use a device-specific Agent secret. Unlike the organization-wide secrets listed on this screen, agent secrets are only valid for 6 hours and are unique to each device.
• Uninstall secrets prevent local admin users from uninstalling the agent. The insider risk agent runs as a system process, so users without local admin permissions cannot uninstall the agent even if uninstall secrets are disabled.

Item		Description
a	Active	Shows active secrets available to uninstall the insider risk agent. Any active secret can be used to uninstall any agent from any device.
b	Expired	Shows secrets that: Are past their expiration date Have been manually revoked Click Reactivate to reinstate the secret.
c	Settings	Provides options to: Enable/disable uninstall secrets Enabled: A secret is required to uninstall agents from user devices. Disabled: No secret is required to uninstall agents from user devices.  Uninstall secret lifespan: Choose the default lifespan for new secrets. Email notifications: Configure who receives email notifications when secrets are about to expire.
d	Create uninstall secret	Create a new secret that can be used to uninstall the agent.
e	Secret	The secret's unique string. Click Show to view the entire string. Click the copy icon to copy the secret to your clipboard.
f	Expiration date (UTC)	After this date, the secret cannot be used to uninstall an agent. The time is reported in Coordinated Universal Time (UTC).
g	Extend	Extend the secret's expiration date. By default, secrets are extended for 6 months. If you set a custom Uninstall secret lifespan, the secret is extended by your chosen custom value.
h	Revoke	Deactivate the secret. Revoking the secret prevents it from being used to authorize uninstallation of the agent. To re-enable the secret, click Extend.

Backup and legacy agent

Legacy agent end-of-life
On April 10, 2024, the Code42 legacy agent reached end-of-life. Devices with the legacy agent are no longer backing up, and Incydr monitoring has stopped. See our FAQ for steps to upgrade to a supported agent. 

Deployment policies

To view and manage deployment policies:

1. Sign in to the Incydr console.
2. Select Administration > Agent Management > Deployment.

If your environment does not yet have any deployment policies, you see the option to Create New Deployment Policy. If your environment already has one or more policies, you see the Deployment Policies list.

Item		Description
a	Create deployment policy	Define a new agent deployment policy.
b	Name	The name of the policy. Click to see policy details.
c	Created	The date the policy was created and the username of the administrator who created the policy.
d	Registration organization	Agents deployed with this policy register with this organization.  The organization determines the authentication method and optional proxy address for the policy. If you deactivate an organization, the associated policy will not work.
e	Organization Status	The status of the registration organization.
f	View details	Allows you to view and change details of the policy.

Policy details

In the Deployment Policies list, click a policy name to see details about the policy, then select the Backup agent or Legacy agent tab. For details about the Insider risk agent tab, see Insider risk agent above.

Item		Description
a	Policy name	The name of the policy.
b	Delete	Deletes the policy. Any agents deployed with this policy that have not yet completed installation will fail to install.
c	Edit Policy	Change details of the policy.
d	Details	The details of the deployment policy.
e	Scripts	The user detection scripts for the policy.
f	Registration organization	Agents deployed with this policy register with this organization. If your custom script specifies a value for C42_ORG_REG_KEY, only users not covered by the script register to this organization.  The organization determines the authentication method and optional proxy address for the policy.
g	Authentication	The method the registration organization uses to validate the usernames and passwords entered by users in the backup agent. Local: Username and passwords are defined in the Incydr console SSO (<provider name>): Usernames and passwords are defined in SSO provider data.
h	Auto Register Users	No: Users must manually sign in to the backup agent to start monitoring and backup. You have two options: Advise users to self-register by clicking Sign up in the backup agent. Create user accounts and provide the credentials to users. Yes: The username is determined by the deployment policy's detection script. The agent authenticates with SSO. Monitoring and backup begins automatically, provided the destination is set to auto-start.
i	Created and Last modified dates	The dates the policy was created and last saved.
j	Configured operating systems	The operating systems the policy is configured for (Windows, Mac, or Linux).
k	Launch desktop app after install	Yes: After installation on a Windows or Mac device, the backup agent opens for the user to see and use. Not applicable on Linux. No: The backup agent does not show until the user manually opens the app.
l	Use organization's proxy URL	Yes: The Registration Org requires agents to communicate through a proxy server. To see the URL of an organization's proxy auto-config (PAC) file, go to Organizations > [select an organization] > Action menu > Device Backup Defaults > Network > Proxy. No: Backup agents communicate with the cloud directly
m	Installation properties	These strings provide arguments for a command that installs a backup agent. Use them in your device management tool or installation scripts. See Deployment script and command reference for the backup and legacy agents for more details.
n	Generate new token	Give the policy a new identifier string. Generate a new token if you suspect unauthorized use of the deployment policy. Any agents previously deployed with the policy, and not yet installed, will fail to install. You will need to install them with the new, active, deployment token.

Create or edit deployment policy

In the Deployment Policy view, select Create New Policy or Edit Policy.

Item		Description
a	Deployment policy name	Enter a name to describe and identify this policy.
b	Registration organization	Determines the user's organization. If you have a custom script that specifies a value for C42_ORG_REG_KEY (see item h below), only users not covered by the script register to this organization. Users register according to the authentication method and directory services configured for their organization. If an organization already has another deployment policy, it is dimmed in the dropdown and cannot be selected. Choose a different organization, or edit the existing policy for that organization.
c	Do you want to automatically register users?	No: Users must manually sign in to the backup agent to start monitoring and backup. You have two options: Advise users to self-register by clicking Sign up in the backup agent interface. Create user accounts and provide the credentials to users. Yes: The username is determined by the deployment policy's detection script. The agent authenticates with SSO. Monitoring and backup begins automatically, provided the destination is set to auto-start.
d	User detection scripts	The user detection script settings below specify how users are associated with an installed agent.
e	Domains allowed	Specify the user email domains approved for agent deployment. If you are deploying to users on more than one domain, enter a comma-separated list (for example: example.com, company.org).
f	Excluded users and domains	To prevent specific domains or users from registering, enter one or more values separated by a comma. Default exclusions include common personal email domains and administrator accounts: *@yahoo.com, *@gmail.com, *@outlook.com, admin, admin1, admin2, Administrator, admin-*, jamfadmin, local, _mbsetupuser, reboot, root, shutdown, user1
g	Operating systems	Select the operating systems to which this policy applies. For example, if you are deploying the insider risk agent to both Windows and Mac endpoints, select both Windows and Mac. Then select a script type for each operating system.
h	Script type	Select the user detection method (options vary by operating system): Current username plus domain: Detects users running explorer.exe and appends the domain of the email address. Domain joined: Detects users running explorer.exe and determines their email addresses from the directory. First and last name plus domain: Detects the locally logged-in users' display name, then separates it to first and last names. Google username: Detects the current logged-in user by querying the Windows Registry and the Google Credential Provider for Windows. Last logged in user: Detects the username of the most recent user to log in to the device's operating system, then appends the company domain to make an email address. macOS plist: Reads a .plist file on the local device populated with the email address supplied by your macOS mobile device management (MDM) tool. Read from file: Reads a text file for the user's email address. Custom: Supply your own user detection script. Custom script details A custom script enables you to specify how the username, user home directory, and the user's organization are determined. A summary of script requirements is listed below, but for complete details about customizing scripts, see Deployment script and command reference for the backup and legacy agents. All custom scripts must end by writing the C42_USERNAME and C42_USER_HOME variables to standard output (see below). C42_ORG_REG_KEY can also be included to define the organization, but this is optional. If C42_ORG_REG_KEY is not present, the Code42 agent uses the default organization selected for this deployment policy. echo C42_USERNAME=<value> echo C42_USER_HOME=<value> echo C42_ORG_REG_KEY=<value> Usernames must be email addresses. To specify an organization, use the registration key. For assistance with custom scripts, contact your Customer Success Manager (CSM) to engage the Incydr Professional Services team. Require users to manually enter their usernames The main purpose of selecting operating systems in this section is to generate the appropriate scripts to automatically detect the username during agent installation. To require users to manually enter their usernames, do not select any operating systems. By leaving all operating systems blank, a deployment policy is still created, but there is no user detection script. As a result, users must enter their usernames to complete the installation process on their device. The server address is still automatically populated for users by the deployment policy.
i	Do your clients need a proxy URL to connect to the Code42 cloud?	No: Agents communicate with the cloud directly. Yes: The Registration Org requires agents to communicate through a proxy server. To see the URL of an organization's proxy auto-config (PAC) file, go to Organizations > [select an organization] > Action menu > Device Backup Defaults > Network > Proxy.
j	Launch desktop app after initial install?	Yes: After installation on a Windows or Mac device, the backup agent opens for the user to see and use. Not applicable on Linux. No: The backup agent does not show until the user manually opens it.

Authentication mismatch

Mismatches occur when you:

1. Define an organization to use SSO authentication.
2. Assign that organization a deployment policy with auto-registration.
3. Edit the organization to use local authentication.

The policy becomes invalid because the organization can no longer support auto-registration.

The solution is to reconfigure the organization or edit the policy.

Related topics

• Deploy agents
• Deployment script and command reference for the insider risk agent
• Deployment script and command reference for the backup and legacy agents