Device object settings (agent, agentless, and adaptable provisioning)

To enable Trust Protection Platform to reference a device when it manages and validates certificates and private keys, you must configure the device object. This object provides the information Trust Protection Platform needs to reference a device.

To get to these settings on an existing object, open Policy Tree, locate the device in the Policy tree and then click the Settings tab.

BEST PRACTICE  Consider managing device object settings via policy. For more information, see Managing devices using policies.

IMPORTANT  If you make any modifications to device object settings, you must click Save to implement those changes.

Device policy object settings

Field

Policy

Description

General

 

 

Device Name

No

Unique name for the Device object. (Only visible when creating the device object.)

Description

No

Description of the device object.

BEST PRACTICE  An effective description can be helpful to other administrators by describing the purpose or function of the device object.

Contact

User or group Identities assigned to this object. Default system notifications are sent to the contact identities.

The default contact is the master administrator.

To select the Device object contacts

  1. Click the Browse button.

    The Identity Selector dialog opens.

    If the Identity Selector dialog is not populated, enter a search query to retrieve the Identity list. The administration console does not automatically display external users and groups. You must first enter a search string so Trust Protection Platform can query the external Identity store, then return the list of requested users or groups.If you want to display all user or group entries, enter the wildcard character (*).

  2. Select a user or group identity, and then click Select.
  3. Press Shift+click to select multiple, contiguous users and groups. Press Ctrl+click to select multiple, discontiguous users and groups.

Host Information

 

 

Hostname/Address

No

IP address or hostname of the physical server associated with the device object.

Trust Protection Platform supports both IPv4 or IPv6 connections.

DID YOU KNOW?  Like most Trust Protection Platform applications, AWS makes use of the Hostname/Address setting from its parent device object, even though it's a cloud service and not a typical device. This is because AWS is an Internet-based service with a public interface that is the same for all customers. But if you're provisioning to a secondary account, the parent device's Hostname/Address setting in Trust Protection Platform is actually used to specify the AWS account ID (rather than the expected hostname or address).

This is a confusing but temporary method for managing this specific use case.

For more information about AWS configuration, see Amazon Web Services (AWS)—Overview.

Provisioning Mode

Specify whether provisioning to this device should be done using the Server Agent, or without the agent (called Agentless).

If you are provisioning using the Server Agent, you must also then configure agent work in Aperture. For more information, see Creating and assigning Work.

For Adaptable SSH Key Discovery, click Adaptable.

Concurrent Connection Limit

Maximum number of connections the server will accept from Trust Protection Platform.

Currently, Trust Protection Platform uses only one connection to provision certificates and keys on a server.

To configure this setting via Policy, go to the Devices > Device tab in the Policy object configuration.

The Device Concurrent Connection Limit defined in the Policy object may be inherited by all subordinate Device objects.

Device Credential

Credential that Trust Protection Platform uses to authenticate with platforms or access keystores on the device.

Credential objects store the credentials Trust Protection Platform uses to authenticate with devices, applications, and CAs. The stored credential may be a password, a username and password, a certificate, or a private key.

Trust Protection Platform uses the Device Credential only if credentials are not defined in the application object. If multiple applications are running on a single device and they share the same credentials, you can simplify credential management by defining the required credential only on the device object. The device credential is then used for all subordinate applications and you don’t have to define credentials for each application object.

If you use the device credential to authenticate with your subordinate applications, the user account must have read and write permissions to the device object’s Temp directory as well as the permissions required for each application.

For more information on application permissions requirements, refer to the Permission Requirements sections for each application driver.

To select the Device Credential

  1. Click the Browse button.
  2. In the Credential Selector dialog, select the Credential required to authenticate with this device, and then click Select.

For more information, see Working with system credentials in the Venafi Trust Protection Platform Administration Guide.

To configure this setting via Policy, go to the Devices > Device tab in the Policy object configuration, and use the Device Credentials setting.

The Device Credentials defined in the Policy object may be inherited by all subordinate Device objects.

Temp Directory

Directory where Trust Protection Platform can write temporary files.

  • To configure this setting via Policy, go to the Devices > Device tab in the Policy object configuration.

The Device Temp Directory defined in the policy object may be inherited by all subordinate Device objects.

For agentless discovery, the value of this field is used for .venafiTemp directories. (If a value is not in this field, agentless discovery will use the default directory of /var/tmp.)

OS Type

Specify the OS type of the devices you will connect to with this policy, or select Automatic.

TIP  This field is not visible if the Provisioning Mode is set to Adaptable.

Jump Server

(Optional) The jump server required to connect with the current device.

A jump server is an intermediary server through which external servers, such as Trust Protection Platform, can access a device behind a firewall. For more information, see Managing Jump Server Objects.

Trust Protection Platform supports jump server connections to the following supported applications using SSH:

Apache

GSK

iPlanet

JKS

NetScaler

PEM

PKCS#12

Tealeaf PCA

To require a jump server connection for the current Device object

  1. Click the Browse button.

  2. In the Device Selector dialog, select the device object required to connect to this device, and then click Select.

When you create a Device object under a Device object, Trust Protection Platform automatically assigns the parent Device object to the Device. However, this is not required, You can associate a Device object with any Device object in the Policy tree.

Use Sudo

Select Yes to enable sudo.

If you need to be able to provision certificates to secure locations for which the user account you're using does not have access rights, sudo can be used to temporarily elevate the user rights in order to perform provisioning tasks on a Unix server.

When enabled, Trust Protection Platform provisions to a temporary directory where your user account has permissions to perform basic functions; then sudo is used to copy the files from the temporary directory to the target directory where they need to be placed.

For more information about sudo, see About using sudo.

NOTE  Sudo use only applies to SSL CLI-drivers that use a standard shell and CLI-based drivers (Apache, JKS, GSK, iPlanet, PKCS#12, and PEM).

Sudo Credential (Optional)

 

Select the credential to use with sudo, which in this case is simply a password.

This is the password that sudo asks for by default when a user attempts to run a command using sudo. The password is optional because the device administrator can put NOPASSWD in the sudoer's file, thereby allowing the user to execute the command without being challenged for a password.

For more information about sudo, see About using sudo.

Enforce Host Key

Describes how to handle SSH connectivity when the Provisioning Mode is Agentless. Matches the presented key and corresponding thumbprint with information in Trust Protection Platform.

Set the Enforce Host Key to No (default), if you want host connectivity regardless of thumbprint changes. Trust Protection Platform compares the current device thumbprint with the last seen fingerprint. If the fingerprints differ, log event is 40060020,SSH Public Key Fingerprint Changed.

Set Enforce Host Key is Yes, if you want to block host connectivity after the thumbprint changes. If the presented thumbprint is different than the stored thumbprint, Trust Protection Platform. refuses the connection. The log event is 40060004,SSH Connect To Host Failed.

For example: 127.0.0.1, 2/22/2017 10:10:04 AM, \VED\Policy\centos-oracle: \VED\Policy\centos-oracle, Error: Error, Translated event: SSH Connection Failed, The SSH library failed to connect to 192.168.3.220 on port 22, with the Connection Result 8: The host key was not accepted.

Presented Thumbprint

n/a

For devices that use the Agentless mode to provision. When the Enforce Host Key is Yes, this field shows the SSH server key thumbprint, also known as a fingerprint, that Trust Protection Platform detected after a successful connection to the device.

Presented Key Type

n/a The key type that encrypted the thumbprint. Corresponds to the Presented Thumbprint value.

TIP  The remaining settings in this list ONLY apply (and are thus only visible) if you set the Provisioning Mode to Adaptable.

Adaptable Script Parameters

PowerShell Script

The PowerShell script you want used for this policy. The script must be stored in the \Venafi\Scripts\AdaptableSSHManagement folder on the Venafi server.

For more information about PowerShell scripts for Adaptable SSH Key Discovery, see PowerShell script reference for Adaptable SSH Key Discovery.

WebSDK OAuth Token Configuration

 

Adaptable SSH Key Discovery can use Venafi APIs for communicating between devices. An API integration needs to be created for this purpose. To learn more about working with and configuring API integrations, see About API integrations.

OAuth Application Id

The value of the Client ID of the application from the API Integrations inventory.

OAuth Token Credential

The username credential object that contains the username and password of the identity that has access to the specified application. (This can be any SSH Protect identity that can obtain a grant for this application.)

When looking at the application in the API Integrations inventory, click on an application name, and look at the User or Team access section to see which users can obtain grants

OAuth Scope

This scope must exactly match the scope, privileges, and restrictions for this application as they are displayed in the API Integrations inventory. The easiest way to copy this is to open the application details from the API Integrations inventory, and in the Overview section, copy the value of the scope attribute in the JSON example.

At minimum, the application must have the following:

Scope Privileges and restrictions
ssh discover

If your application uses this minimum setting, you would enter this value:

ssh:discover

Once it is supported (not during the technology preview stage), if you want to do SSH remediation on the devices, you will need the following minimum scope:

Scope Privileges and restrictions
ssh manage,discover

If your application uses this setting, you would enter this value:

ssh:manage,discover

Advanced Settings

Enable Debug Logging

If you are trying to troubleshoot a problem with your Adaptable SSH Key Discovery setup, you may consider enabling this setting to get debugging information in the logs.

Script Execution Timeout

The maximum number of seconds a script can run before the process is terminated.

Custom Fields

 

If you have configured custom fields (not related to custom field definitions in the PowerShell script, which are not supported in this preview), you can set the field value on for the policy here. You will have a separate field for each custom field you have created. For more information, see Adding or deleting a custom field.

These custom fields are NOT passed to the PowerShell script, and are not related to the adaptable technology features of Venafi Platform.

What's next?

After you create a CA object, you can select it from the Policy tree, and then view important information and manage various settings.

  • Click the General tab to view and modify log and permissions settings.

    • Click the Log sub-tab to view any logged events that are triggered by the template object.

      IMPORTANT  You must have the Read permission to view the Log tab.

      For more information about options found on the Log tab, see Viewing log events.

    • On the Permissions sub-tab, you can configure the users or groups to whom you want to grant permissions to the new template object.

      Consider managing object permissions via parent objects so that you can take advantage of inheritance. For more information, see Permission inheritance and flow down.