Chat now with support
Chat with Support

One Identity Safeguard for Privileged Passwords 7.4.1 - Administration Guide

Introduction System requirements and versions Using API and PowerShell tools Using the virtual appliance and web management console Cloud deployment considerations Setting up Safeguard for Privileged Passwords for the first time Using the web client Home page Privileged access requests Appliance Management
Appliance Backup and Retention Certificates Cluster Global Services External Integration Real-Time Reports Safeguard Access Appliance Management Settings
Asset Management
Account Automation Accounts Assets Partitions Discovery Profiles Tags Registered Connectors Custom platforms Importing objects
Security Policy Management
Access Request Activity Account Groups Application to Application Cloud Assistant Asset Groups Entitlements Linked Accounts User Groups Security Policy Settings
User Management Reports Disaster recovery and clusters Administrator permissions Preparing systems for management Troubleshooting Frequently asked questions Appendix A: Safeguard ports Appendix B: SPP and SPS join guidance Appendix C: Regular Expressions

Customize the response using API query parameters

You can use the following API query parameters to customize the response returned from the API.

The following output parameters allow you to define the property names to be included and the property names to be used for sorting.

Table 10: API query filtering: Output
Output Example Description/Notes
fields GET /Users?fields=FirstName,LastName List of property names to be included in the output.
orderby Get /AssetAccounts?orderby=-AssetName,Name

List of property names to be used to sort the output.

Implies descending order.

The following paging parameters allow you to include an item count, the starting page, and the number of items per page.

Table 11: API query filtering: Paging
Paging Example Description/Notes
count GET /Assets?count=true Indicates, True or False, whether to return a single integer value representing the total number of items that match the given criteria.
page & limit GET /DirectoryAccounts?page=3&limit=100

page defines which page (starting with 0) of data to return.

limit defines the size of the page data.

The following operators can be used to filter the results.

Table 12: API query filtering: filter parameter
Operator Example Description/Notes
eq GET /AssetAccounts?filter=Name eq 'George' equal to
ne GET /Users?filter=LastName ne 'Bailey' not equal to
gt GET /Assets?filter=Id gt 10 greater than
ge GET /Assets?filter=Id ge 10 greater than or equal to
lt GET /Assets?filter=Id lt 10 less than
le GET /Assets?filter=Id le 10 less than or equal to
and GET /UserGroups?filter=(Id eq 1) and (Name eq 'Angels') both operands return true
or GET /UserGroups?filter=(Id eq 1) or (Name eq 'Bedford') at least one operand returns true
not GET /UserGroups?filter=(Id eq 1) and not (Name eq 'Potters') narrows the search by excluding the "not" value from the results
contains GET /Users?filter=Description contains 'greedy' contains the word or phrase
q GET /Users?q=bob

q can be used to search across text properties; means "contains" for all relevant properties.


GET /Users?filter=UserName in [ 'bob', 'sally', 'frank']

property values in a predefined set

GET /AssetAccounts?filter=Name sw 'Sam'

(v4 API only) starts with (for case insensitive searches use isw)

GET /AssetAccounts?filter=Name ew 'Smith'

(v4 API only) ends with (for case insensitive searches use iew)

When using the filter parameter, you can use parenthesis () to group logical expressions. For example, GET/Users?filter=(FirstName eq 'Sam' and LastName eq 'Smith') and not Disabled

When using the filter parameter, use the backward slash character (\) to escape quotes in strings. For example: Get/Users?filter=UserName contains '\''

Using Safeguard PowerShell

PowerShell is a task-based command-line shell and scripting language used to automate tasks that manage operating systems and processes. The SPP Powershell module and scripting resources can be found on GitHub here: OneIdentity/safeguard-ps.


The SPP Powershell module is published to the PowerShell Gallery to make it easy to install using the built-in Import-Module cmdlet. Use the Update-Module cmdlet to get the latest functionality.

By default, Powershell modules are installed for all users. You need to be running Powershell as an Administrator to install for all users.

> Install-Module safeguard-ps

Or, you can install the modules just for you using the -Scope parameter which will never require administrator permission:

> Install-Module safeguard-ps -Scope CurrentUser

Using the virtual appliance and web management console

Before you start: platforms and resources

When setting up a virtual environment, carefully consider the configuration aspects such as CPU, memory availability, I/O subsystem, and network infrastructure to ensure the virtual layer has the necessary resources available. See One Identity's Product Support Policies for more information on environment virtualization.

You must license the VM with a Microsoft Windows license. Specific questions about licensing should be directed to your Sales Representative.

Platforms and versions follow.

  • You must license the VM with a Microsoft Windows license. We recommend using either the MAK or KMS method. Specific questions about licensing should be directed to your Sales Representative.

  • Supported hypervisors:
    • Microsoft Hyper-V (VHDX) version 8 or higher
    • VMware vSphere with vSphere Hypervisor (ESXi) versions 6.5 or higher
    • VMware Workstation version 13 or higher

  • Minimum resources: 4 CPUs, 10GB RAM, and a 500GB disk. The virtual appliances default deploy does not provide adequate resources. Ensure these minimum resources are met.
Available wizards

The Appliance Administrator responsible for racking and initial configuration of the appliance can create the virtual appliance, launch the Safeguard web management console, and select one of the following wizards.

  • Initial Setup: Used to set up the virtual appliance for the first time including naming, OS licensing, and networking. For more information, see Setting up the virtual appliance..
  • Setup: After the first setup, SPP updates and networking changes can be made via the web management console by clicking Setup.
  • Support Kiosk: The Support Kiosk is used to diagnose and resolve issues with Safeguard for Privileged Passwords. Any user able to access the kiosk can perform low-risk support operations including appliance restart or shutdown and support bundle creation. In order to reset the admin password, the user must obtain a challenge response token from One Identity support. For more information, see Support Kiosk.


CAUTION: To maximize security in the absence of a hardened appliance, restrict the access to the Safeguard virtual disks, the web management console, and the MGMT interface to as few users as possible. The Management web kiosk gives access to functions without authentication, such as pulling a support bundle and rebooting the appliance.

Security recommendations follow.

  • X0 hosts the public API and is network adapter 1 in the virtual machine settings. Connect this to your internal network.
  • MGMT hosts the web management console and is network adapter 2 in the virtual machine settings. This interface always has the IP address of Connect this to a private, restricted network accessible to administrators only, or disconnect it from the network to restrict unauthenticated actions such as rebooting or shutting down the appliance. The web management console is also available via the VMware console.

Once setup is completed, you can verify which of your NICs is MGMT and X0 by referring to the MAC address information found in Support Kiosk > Appliance Information > Networking for X0 and MGMT. For more information, see Support Kiosk.

Backups: virtual appliance and hardware appliance

To protect the security posture of the Safeguard hardware appliance, Safeguard hardware appliances cannot be clustered with Safeguard virtual appliances. Backups taken from a hardware appliance cannot be restored on virtual appliances and backups taken from a virtual appliance cannot be restored on a hardware appliance.

For more information, see Virtual appliance backup and recovery.

Upload and download

There is a web management console running on When you connect to the virtual appliance via the virtual display, the web management console is displayed automatically; however, upload and download functionality are disabled when connected this way.

You may choose to configure the networking of your virtual machine infrastructure to enable you to proxy to from your desktop. Connecting in this way will enable you to upload and download from the web management console.

CAUTION: Cloning and snapshotting are not supported and should not be used. Instead of cloning, deploy a new VM and perform Initial Setup. Instead of snapshotting, take a backup of the virtual appliance. Only the SPP backup and recovery functionality is supported (Virtual appliance backup and recovery).

Migrating the VM

VMware VMotion can be used for live migration of a virtual machine from one physical server to another.

Setting up the virtual appliance

The Appliance Administrator uses the initial setup wizard to give the virtual appliance a unique identity, license the underlying operating system, and configure the network. The initial setup wizard only needs to be run one time after the virtual appliance is first deployed, but you may run it again in the future. It will not modify the appliance identity if run in the future.

Once set up, the Appliance Administrator can change the appliance name, license, and networking information, but not the appliance identity (ApplianceID). The appliance must have a unique identity.

The steps for the Appliance Administrator to initially set up the virtual appliance follow.

Step 1: Make adequate resources available

The virtual appliances default deploy does not provide adequate resources. The minimum resources required are: 4 CPUs, 10GB RAM, and a 500GB disk. Without adequate disk space, the patch will fail and you will need to expand disk space then re-upload the patch.

Step 2: Deploy the VM

Deploy the virtual machine (VM) to your virtual infrastructure. The virtual appliance is in the InitialSetupRequired state.

Hyper-V zip file import and set up

If you are using Hyper-V, you will need the Safeguard Hyper-V zip file distributed by One Identity to setup the virtual appliance. Follow these steps to unzip the file and import:

  1. Unzip the Safeguard-hyperv-prod... zip file.
  2. From Hyper-V, click Options.
  3. Select Action, Import Virtual Machine.
  4. On the Locate Folder tab, navigate to specify the folder containing the virtual machine to import then click Select Folder.
  5. On the Locate Folder tab, click Next.
  6. On the Select Virtual Machine tab, select Safeguard-hyperv-prod....
  7. Click Next.
  8. On the Choose Import Type tab, select Copy the virtual machine (create a new unique ID).
  9. Click Next.
  10. On the Choose Destination tab, add the locations for the Virtual machine configuration folder, Checkpoint store, and Smart Paging folder.
  11. Click Next.
  12. On the Choose Storage Folders tab, identify Where do you want to store the imported virtual hard disks for this virtual machine?.
  13. Click Next.
  14. Review the Summary tab, then click Finish.
  15. In the Settings, Add Hardware, connect to Safeguard's MGMT and X0 network adapter.
  16. Right-click on the Safeguard-hyperv-prod... and click Connect... to complete the configuration and connect.
Step 3: Initial access

Initiate access using one of these methods:

  • Via a virtual display: Connect to the virtual display of the virtual machine. You will not be offered the opportunity to apply a patch with this access method. Upload and download are not available from the virtual display. Continue to step 3. If you are using Hyper-V, make sure that Enhanced Session Mode is disabled for the display. See your Hyper-V documentation for details.
  • Via a browser: Configure the networking of your virtual infrastructure to proxy on the virtual appliance to an address accessible from your workstation then open a browser to that address. For instructions on how to do this, consult the documentation of your virtual infrastructure (for example, VMWare). You will be offered the opportunity to apply a patch with this access method. Upload and download are available from the browser. Continue to step 3.

    IMPORTANT: After importing the OVA and before powering it on, check the VM to make sure it doesn't have a USB controller. If there is a USB controller, remove it.

Step 4: Complete initial setup

Click Begin Initial Setup. Once this step is complete, the appliance resumes in the Online state.

Step 5: Log in and configure Safeguard for Privileged Passwords
  1. If you are applying a patch, check your resources and expand the disk space, if necessary. The minimum resources are: 4 CPUs, 10GB RAM, and a 500GB disk.
  2. To log in, enter the following default credentials for the Bootstrap Administrator then click Log in.
    • User Name: admin
    • Password: Admin123

  3. If you are using a browser connected via, the Initial Setup pane identifies the current Safeguard version and offers the opportunity to apply a patch. Click Upload Patch to upload the patch to the current Safeguard version or click Skip. (This is not available when using the Safeguard Virtual Kiosk virtual display.)
  4. In the web management console on the Initial Setup pane, enter the following.
    1. Appliance Name: Enter the name of the virtual appliance.
    2. Host DNS Suffix: Enter the host DNS suffix name.
    3. Windows Licensing: Select one of the following options:
      • Use KMS Server: If you leave this field blank, Safeguard will use DNS to locate the KMS Server automatically. For the KMS Server to be found, you will need to have defined the domain name in the DNS Suffixes.

        If KMS is not registered with DNS, enter the network IP address of your KMS server.

      • Use Product Key: If selected, your appliance will need to be connected to the internet for the necessary verification to add your organization's Microsoft activation key.

    4. NTP: Complete the Network Time Protocol (NTP) configuration.
      • Select Enable NTP to enable the protocol.
      • Identify the Primary NTP Server IP address and, optionally, the Secondary NTP Server IP address.
    5. Network (X0): For the X0 (public) interface, enter the IPv4 and/or IPv6 information, and DNS Servers information. Directory or network scans are supported for IPv4 but not IPv6.
  5. Click Save. The virtual appliance displays progress information as it configures Safeguard, the network adapter(s), and the operating system licensing.
  6. When you see the message Maintenance is complete, click Continue.
Step 6: Access the web client

You can go to the virtual appliance's IP address for the X0 (public) interface from your browser.

Step 7: Change the Bootstrap Administrator's password

For security reasons, change the password on the Bootstrap Administrator User. For more information, see Setting a local user's password.For details, see the Safeguard for Privileged Passwords Administration Guide, Setting a local user's password.

Step 8. After clustering, change the trusted servers, CORS, and redirects setting

As a best practice, after you have created your Safeguard for Privileged Passwords cluster (or if just using a single VM), change the Trusted Servers, CORS and Redirects setting to the empty string or a list of values to integration applications you wish to allow. For more details, see the Safeguard for Privileged Passwords Administration Guide, Trusted Servers, CORS and Redirects.

View or change the virtual appliance setup

You can view or change the virtual appliance setup.

  • From the web management console, click Home to see the virtual appliance name, licensing, and networking information.
  • After the first setup, SPP updates and networking changes can be made via the web management console by clicking Setup.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating