Configuring policies and devices for use in Adaptable SSH Key Discovery

If the folder you want to use is already configured for Adaptable SSH Key Discovery, you can skip this section.

1. From the SSH Protect menu, click Folders.

2. Browse to (or create) the folder where you want to store the discovered items.

3. In the SSH Policy > General settings click Yes for Allow Adaptable SSH Key Discovery.

4. Click Save.

5. From the SSH Protect menu, click Configuration > Policy Tree.

6. Browse to the policy (folder) you just edited (or created).

7. Click the Devices tab.

8. In the Host Information section, under Provisioning Mode, select Adaptable.

   TIP  If Adaptable isn't in the list, make sure you completed step 3 above.

9. Set any other fields you want at the policy level. (Show/hide table with field descriptions.)

   Device policy settings

   Field	Policy	Description
   General
   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 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 (*). Select a user or group identity, and then click Select. Press Shift+click to select multiple, contiguous users and groups. Press Ctrl+click to select multiple, discontiguous users and groups.
   Host Information
   Provisioning Mode		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 Click the Browse button. 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.)
   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 Click the Browse button. 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.
   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 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, 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.

10. Click Save.

Now your policy is in place, so you need to create a device.

1. From the SSH Protect menu, click Configuration > Policy Tree.

2. Expand the policies in the tree to locate the group (shown in this view as a policy) you created in the previous steps.

3. Click on the policy, then click the Devices tab.

4. In the Host Information section, set Provisioning Mode to Adaptable, then save the policy.

5. Right-click on the policy in the tree and click Add > Deices > Device.

   Since the policy has the provisioning mode set to Adaptable, you see that policy setting filter down to this device in it's own Host Information section, Provisioning Mode field.

6. Set any other fields you want at the device level. (Show/hide table with field descriptions.)

   Device 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 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 (*). Select a user or group identity, and then click Select. 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		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 Click the Browse button. 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.)
   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 Click the Browse button. 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.
   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 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, 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.

7. Save your changes.

At this point, it might be a good idea to check to see if SSH Protect can connect to your device using the credentials you specified.

To test your device's connection

1. From the SSH Protect menu, click Inventory > Devices.

2. [Optional] If needed, use the filter boxes to help you find the device you created.

3. Click the device name for the device you created in the previous procedure.

4. Click Test Connection.

If you get a success message, you're ready to continue.

If not, go back to Policy Tree and change the device configuration. We recommend you start by verifying the hostname/IP address and the credentials. You might try connecting to the device (using a remote desktop tool, or an SSH connection, etc.) to help you troubleshoot potential issues.