Skip to content

Getting Set Up

In order for Workload Privilege Management to broker connections to a targeted web application or server, an administrator will first work with a SailPoint Customer Success Manager to deploy a gateway agent, configure a domain and location, and add API keys. After these steps, see how to manage users, roles, and access groups.

Deploying the Gateway Agent

Before you can begin connecting to targets, you must install a gateway agent. This lightweight agent runs as a service on your own host server.

A gateway agent is used exclusively to broker SSH and RDP connections. It serves as a single agent that can connect to many servers. For example, if you have 100 servers in AWS, you can use one gateway agent to connect to them all, provided that the device that the gateway is installed on has a route to all 100.

Note

The key distinction between a gateway agent and a user agent is that only user agents can broker web connections. RDP and SSH connections can be brokered with a user agent, provided that the route to the target exists from your machine.

Prerequisites

You will work with your SailPoint Customer Success Manager to set up the software-based gateway agent in your initial deployment. To prepare for that installation, ensure you are using an administrator account and have reviewed and completed the following prerequisites:

Supported Operating Systems Hardware and System Requirements Supported Browsers
Windows 2016, 2012, 2012 R2 2 CPU Google Chrome
Windows 10 Pro, 10, 7-32bit and 7-64bit 4GB RAM Mozilla Firefox
macOS X 20GB hard drive
CentOS 7
Red Hat 7
Amazon
Linux 2

Firewall and IP Requirements

Port Protocol Description
22 TCP Outbound from the agent to network switches, firewalls (SSH), and Linux targets.
443 HTTPS Outbound access to Workload Privilege Management at cloudpriv.sailpoint.com. The agent performs public key pinning of the root CA certificate therefore the traffic must not be SSL terminated at the firewall.
443 TCP Outbound access to Workload Privilege Management at reflect.cloudpriv.sailpoint.com. The agent performs public key pinning of the root CA certificate therefore the traffic must not be SSL terminated at the firewall.
3389 TCP Outbound from the agent to Windows targets.
8888 TCP The agent is a multi-process application that communicates with internal APIs over this port on the local loopback interface. This does not require any edge firewall changes and should not require any local firewall changes. It is required on targets that agents are running on, not on all targets that are being connected to.

Allowing Access by Files

If you want to use Workload Privilege Management with host-based endpoint protection, you'll need to update your protection rules to permit the following files in the C:\Program Files (x86)\SPPrivAgent\ directory:

  • spprivagent.exe

  • spprivagentui.exe

  • spprivagent-cli.exe

After you've prepared your system for installing the gateway agent, you can access Workload Privilege Management to add an API key and domain, both of which are needed to initialize your agent.

Downloading the Gateway Agent

You can download the Gateway Agent using the OS-specific links or by following the directions in Installing and Configuring the Gateway Agent.

Operating System Agent Download Link
Windows https://cloudpriv.sailpoint.com/agent/latest/SPPrivAgent-windows-installer.exe
MacOS https://cloudpriv.sailpoint.com/agent/latest/SPPrivAgent-osx-installer.dmg
Linux https://cloudpriv.sailpoint.com/agent/latest/SPPrivAgent-linux-x64-installer.run

Note

You may need to replace "cloudpriv.sailpoint.com" with your platform URL.

Installing and Configuring the Gateway Agent

Once you have completed the prerequisites and are set up in Workload Privilege Management, you can use an account with system administrative privileges to begin installing and configuring the gateway agent. You can download the agent using the links above or by using the in-app menu (see step 2 below). See specific directions to install the gateway agent on a Windows server or a Linux server.

  1. Select your name in the top-right corner to open a drop-down menu.

     

  2. Select Download User Agent.

  3. Start the agent install.

  4. Choose Shared Gateway Agent and select Next.  

  5. Once the gateway agent is installed, select the SailPoint icon in your top toolbar for macOS or right-click the icon in the Windows system tray to see the Credentials and Settings options.

  6. Select Credentials. Choose if you want to authorize the gateway agent with user credentials or by pasting your JWT into the API Key field. If your login is approved, you will see the SailPoint agent icon turn from red to blue.

     

  7. Select Settings to choose to auto update and/or use HTTP proxy with a required username and password.

     

Once your agent is registered, it must be enabled before it can be used.

Installing on a Windows Server

Review the supported OS, system requirements, and post-installation steps for installing the agent on a Windows host server.

Supported Operating Systems Hardware and System Requirements
Windows Server 2019 2 vCPU
Windows Server 2016 4GB of RAM
Windows Server 2012 30GB hard drive
Windows Server 2012 R2

You will also need:

  • Windows PowerShell v3+ and outbound TCP/5986 from SPPrivAgent for WinRM over HTTPS, and inbound TCP/8888.

  • DHCP Media Sense enabled

    • Check: netsh interface ipv4 show global
    • Repair: netsh interface ipv4 set global dhcpmediasense=enabled

Downloading the Windows Server Gateway Agent

See Downloading the Gateway Agent to download the Windows agent. After you download and install, you can start the wizard and follow the directions. Complete your installation by updating your DNS settings.

Post-Installation: Updating Your DNS Settings

After you've successfully installed the agent on a Windows server, you'll want to remove the setting that registers the connection's addresses in DNS.   

  1. Open the Control Panel.  

  2. Select Network and Internet.

  3. Select Network and Sharing Center.

     

  4. Select the active connection (Ethernet0 in the example image).

  5. Select Properties.

     

  6. Select Internet Protocol Version 4 (TCP/IPv4).

  7. Select Properties.

     

  8. Select Advanced

  9. Select the DNS tab.

     

  10. Uncheck the Register this connection's addresses in DNS option and select OK through each menu until the Close option appears. 

You will need to manually remove the unwanted entry from DNS if you have legacy settings on the Windows server.

Best Practice

Barring special circumstance, SailPoint does not recommend installing the agent on Windows domain controllers.

Installing on a Linux Server

Ensure that you have the following prerequisites before installing the gateway agent on your Linux server.

Supported Operating Systems Hardware and System Requirements
CentOS 7 2 vCPU
Red Hat 7 4GB of RAM
Amazon Linux 2 30GB hard drive

Installation Directions

  1. Download the Linux gateway agent from Downloading the Gateway Agent.

  2. Run the installed binary as an administrator:

    sudo spprivagent-latest-linux-x64-installer.run

  3. Specify the directory where the agent will be installed. For example, /opt/agent.

  4. Specify if the agent will be installed for a local user or as a shared gateway. Enter 2 to select the shared gateway agent.

  5. Enter Y to begin the installation.

  6. Once the agent is installed, you can enable and start the agent.

    a. On Linux environments, enter:

    systemctl enable spprivagent
    systemctl start spprivagent
    
  7. Register the agent using the API key provided by the SailPoint professional services: /opt/spprivagent/spprivagent-cli -a

  8. Enter 1 to choose to use the API key to contact the agent.

  9. Enter your API key and press return or Enter.

  10. See Enabling the Gateway Agent in Agent Maintenance to verify that the agent is registered and visible.

Verifying Installation and Troubleshooting

See below for some useful commands for verification and troubleshooting.

Check the host-based firewall:

  1. netstat -na | grep 8888

  2. sudo firewall-cmd --get-active

  3. sudo firewall-cmd --list-all

Set local host firewall (if not running as root, start each command with sudu):

  1. firewall-cmd --permanent  --dd-port=8888/tcp

  2. firewall-cmd --reload

  3. firewall-cmd --list-all

  4. firewall-cmd --permanent --add-port=8888/tcp

  5. firewall-cmd --reload

Restarting the gateway agent:

  1. systemctl start spprivagent

  2. systemctl enable spprivagent

  3. systemctl start spprivagent

Enabling the Gateway Agent in Agent Maintenance

As an agent registers back with its tenant, it will always be disabled until it is enabled in agent maintenance. If it is not enabled and someone tries to use it, that attempt will fail.

  1. To enable an agent, select ADMIN from the top toolbar.

  2. Expand Agent Maintenance in the left menu and select Agent Maintenance. This will show both gateway and local user agents.

     

  3. Agents are disabled at creation by default and must be manually enabled. Select the three lines in the Actions column to see the actions you can take on that agent.

     

  4. Select Edit and select the Enable toggle to turn it on.

     

  5. You can select Update to save your changes locally and return to the list of agents or select Commit to push the configuration to the agent to persist the configuration on that agent.

Once the agent is registered back to the tenant, you can use it as a gateway to start brokering connections to specific targets.

Note

If, after installing the shared gateway agent, during the activation process you receive an error message that it "Cannot Reach Digital Store," this indicates that the account used to install the agent did not have administrative privileges. Uninstall the agent and switch to an admin-enabled account to reinstall.

Monitoring the Gateway Agent

SailPoint recommends customers monitor this service and its underlying infrastructure, including:

  1. Host server environmental health: CPU, RAM, HDD, Network I/O, and service up-time

  2. Agent status. Right-click on the SailPoint agent icon in the systems tray or menu bar and verify that it says Status: Running.

Managing Domain Accounts

Domain refers to a domain such as Active Directory or other identity services. Workload Privilege Management administrators can create, edit, and view the history of domains, which is required to use domain credentials in your environment.

Domains allow for federated credentials to be managed. There are scenarios where servers are attached to a domain. This allows for federated credentials to be used to access these servers. Federated credentials would be like username@sailpoint.com. This credential can have access to literally every server in an enterprise environment. The domain serves to tie these servers together and then to associate a single credential to many servers.

Adding a New Domain

  1. Navigate to ADMIN.
  2. Expand Privileged Access Management and select Domains.
  3. Select Add Domain.
  4. Enter the domain name as it is named in your network. 
  5. Use the drop-down menu to select the domain management target that will be used to manage passwords associated with that target.  
  6. If the target is not yet created, select the + icon next to Domain Management Target to add a new target.

Using Domain Members

A domain member is a device that Workload Privilege Management uses to manage all domain credentials. This device must be a Windows server that is configured to enable AD-Domain-Services

To enable AD-Domain-Services, open a command prompt and run the following as an administrator: 

Install-windowsfeature -name AD-Domain-Services-IncludeManagementTools

Setting Domain Member Local Permissions

You will need to set local permission settings to support managed domain user and shared credentials.  

  1. On a Windows machine, open Active Directory Users and Computers


  2. Create a new organizational unit to contain all service accounts that will have passwords managed by Workload Privilege Management.

  3. Right-click on the newly created organizational unit and select Properties.

  4. Select the Security tab, highlight SELF, and select Advanced.

  5. In the Advanced Security Settings window, select Add.

  6. Click Select a principal.

  7. Type in "SELF" and select Check Names. 

     

  8. Select OK

  9. In the Permission Entry Window make sure that Type is set to Allow and Applies to is set to Descendant User Objects.

  10. In the Permissions panel, check the following boxes:  

    • Read all properties 
    • Write all properties 
    • Read Permissions 
    • Write Permissions 
    • Change Password 
    • Reset Password
  11. Move all domain accounts to be managed by Workload Privilege Management into the new Organizational Unit. To do so:

    1. Return to the Active Directory Users and Computers screen.
    2. To change domains, right-click on Active Directory Users and Computers in the left pane, select Connect to Domain, enter the domain name, and select OK.
    3. In the left pane, browse to the organizational unit you want to move.
    4. Right-click on the organizational unit and select Move.
    5. Select the new parent for the organizational unit and select OK.
  12. Allow sufficient time for AD Replication in your environment. This is dependent upon your setup, but a safe estimate is between 10 to 15 minutes.

  13. Make sure all domain accounts that are to be managed by Workload Privilege Management are members of the local group Remote Management Users (or WinRMRemoteWMIUsers__" group on 2008R2) on all desired servers. 

Adding Roles and Features on Domain Members

  1. Open Server Manager and select Local Server  

  2. Select Manage and choose Add Roles and Features.

  3. Click Next in the wizard until you see Features.

  4. In the Features menu, select Remote Server Administration ToolsRole Administration ToolsAD DS and AD LDS ToolsActive Directory module for Windows PowerShell.

     

  5. Select Next and Install.

Setting Up Managed Domain Credentials

Administrators can work with their SailPoint CSM to enable managed domain credentials by: 

Domain account users can onboard existing domain admin accounts to be managed so that Workload Privilege Management will obfuscate the password from the domain credential owners and automatically update the password. Domain accounts can be shared (service accounts) or personal user accounts. 

To ensure domain accounts are managed: 

  1. Select CONNECTION from the top toolbar.
  2. Select a connection and choose + Credential.
  3. Fill out the credential information, keeping the default management toggle off so that the credential is unmanaged. 
  4. Select Submit.
  5. Verify the connection using the new user credential. 
  6. Edit the user credential and turn on the managed toggle. 

Updating a Domain Credential in an RDP Connection

You may want to update your domain credential in an RDP connection if:

  • Domain user credentials are being used to make connections.
  • Domain user access is restricted to a secure environment. 
  • The secure environment is not part of the corporate identity federation and has its own unique identity store. 
  • Domain users can only connect to the secure environment using SailPoint-managed connections. 

Windows laptop or workstation users: 

  1. Connect to any Windows target in the secure environment using the domain user credential. 
  2. On the Remote Desktop, select Start
  3. Type "osk" and open the On Screen Keyboard
  4. Press CTRL and ALT on the physical keyboard, then select Del on the osk window. 
  5. Update the domain user credential and close the connection.
  6. Update the domain user credential in Workload Privilege Management.
  7. Test any connection with the domain user credential to verify.

MacOS users: 

  1. Connect to any Windows target in the secure environment using the domain user credential. 
  2. On the keyboard, press Control+Option+Function+Delete at the same time.
  3. Update the domain user credential and close the connection. 
  4. Update the domain user credential in Workload Privilege Management.
  5. Test any connection with the domain user credential to verify.  

Managing Locations

A location can be a physical address or logical categorization of targets (i.e., network devices, servers, machines). Users may add locations individually or through the bulk-load feature of Workload Privilege Management.

Important

Setting the location is a prerequisite to adding targets.   

Adding an Individual Location

  1. Select ADMIN from the top toolbar. 

  2. Expand Privileged Access Management in the left menu and select Locations

  3. To add a new location, select Add Location.
  4. A pop-up window will appear. Select Manual

  5. Enter all required data for the location and select Save.

Adding Locations in Bulk

  1. Select ADMIN from the top toolbar.
  2. Expand Privileged Access Management in the left menu and select Locations.
  3. Select Add Location
  4. A pop-up menu will appear. Choose Template to download the CSV template. 
  5. Preserve the header row in the CSV file.  
  6. Enter your location information in the fields and save as a CSV-formatted workbook.

    Note

    Address 2 and Address 3 are optional fields. 

  7. Select Add Location and choose From CSV.  

  8. Navigate to your saved CSV file and select Open

Editing a Location

Select the Edit icon to make edits and select Save when you're done. 

Deleting a Location

Select the Delete icon to open a confirmation prompt. Type "DELETE" in the field and select Delete

Warning

Deletion of a location is permanent and cannot be reversed. All targets associated with a location and the associated data to the targets will be deleted. This includes connections and local credentials to the target. 

Managing APIs

Workload Privilege Management exposes APIs for customers to leverage in scripts and external systems, such as DevOps tools and to interact with targets, connections, and credentials.

Restricting API Access by IP Addresses

You can control which IP addresses are allowed access to individual API keys when creating an API key. When you choose to enable IP restrictions, you can specify an access control list that dictates the exact IP addresses you want to allow. You can create new access control lists and edit or delete existing ones.

  1. Select ADMIN from the top menu.

  2. Expand Account Administration and select Access Control List.

  3. Select Add New to create a new access control list. Enter the IP addresses you want to limit access to. CIDR notation is allowed.

Adding API Keys

  1. To add an API key, select ADMIN from the top toolbar.
  2. Expand Account Administration in the left menu and select API Keys.
  3. Select Add API Key in the top right.
  4. In field 3, User Roles, choose the API key role you want to use. Workload Privilege Management ships with a default set of roles, including API_USER and API_KEY_ADMIN.

    Tip

    A best practice for API administrators is to use the default roles when using the API function, then consult with your SailPoint Customer Success Manager to fine tune the API roles to fit your specific use cases. This may result in simply modifying or renaming the existing roles or creating custom roles.

  5. By default, all IP addresses are allowed, but you can choose to enable IP restrictions. If you enable IP restrictions you can choose an access control list dictating what IP addresses are permitted.

  6. Select Save. You will see the API key added to the list.

To see the JSON web token created, select the eye icon in the JWT column. You can use this token to connect to an agent.