Chat now with support
Chat with Support

Safeguard for Privileged Passwords On Demand Hosted - 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 Getting started with the desktop client Using the desktop client Activity Center Search box Privileged access requests Toolbox Accounts Account Groups Assets
General/Properties tab (asset) Accounts tab (asset) Account Dependencies tab (asset) Owners tab (asset) Access Request Policies tab (asset) Asset Groups tab (asset) Discovered SSH Keys (asset) Discovered Services tab (asset) History tab (asset) Managing assets
Asset Groups Discovery Entitlements Linked Accounts Partitions Profiles Settings
Access Request settings Appliance settings Asset Management settings Tags Backup and Retention settings Certificates settings Cluster settings Enable or Disable Services settings External Integration settings Password Management settings Real-Time Reports Safeguard Access settings SSH Key Management settings Security Policy Settings
Users User Groups Disaster recovery and clusters Administrator permissions Preparing systems for management Troubleshooting Frequently asked questions Appendix A: Safeguard ports Appendix B: SPP 2.7 or later migration guidance Appendix C: SPP and SPS join guidance Appendix D: Regular Expressions About us

Using the API

Safeguard for Privileged Passwords (SPP) is built with an API-first design and uses a modernized API based on a REST architecture which allows other applications and systems to interact with it. Every function is exposed through the API to enable quick and easy integration regardless of what action you perform or in which language your applications are written. There are even a few things that can only be performed via the Safeguard SPP API.

CAUTION: Starting with Safeguard for Privileged Passwords 6.8, any user that built a custom solution that monitors for events using ASP.NET SignalR will need to make changes to their solutions due to the upgrade to ASP.NET Core SignalR. For more information on this change and how to upgrade between the two versions, see the Microsoft documentation.

Users that built custom solutions that do not rely on event monitoring via SignalR should not be impacted.

NOTE: Safeguard for Privileged Passwords 6.8 versions of open source projects hosted on GitHub (SafeguardDotNet, SafeguardJava, safeguard-bash) have been updated to support ASP.NET Core SignalR so they will work with the new SignalR changes in Safeguard for Privileged Passwords 6.8.

API tutorial

The Safeguard for Privileged Passwords API tutorial is available on GitHub at: https://github.com/oneidentity/safeguard-api-tutorial.

Access the SPP API

Safeguard for Privileged Passwords has the following API categories:

  • Core: Most product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, and so on.

    https://<Appliance IP>/service/core/swagger/

  • Appliance: RAppliance-specific operations, such as setting IP address, maintenance, backups, support bundles, appliance management.

    https://<Appliance IP>/service/appliance/swagger/

  • Notification: Anonymous, unauthenticated operations. This service is available even when the appliance isn't fully online.

    https://<Appliance IP>/service/notification/swagger/

  • Event: Specialized endpoint for connecting to SignalR for real-time events.

    https<Appliance IP>event/signalr

  • a2a: Application integration specific operations. Fetching passwords and SSH keys, making access requests on behalf of users, and so on.

    https://<Appliance IP>/service/a2a/swagger

You must use a bearer token to access most resources in the API. When using the Swagger web UI (as referenced in the URLs above), click the Authorize button at the top of each page and log in using the web UI. The Swagger web UI adds the bearer token to each API request automatically. However, if you are manually making the API request or writing your own application/script, perform the following two steps to obtain a bearer token.

  1. You must first authenticate using the OAuth 2.0 Resource Owner Password (or SSH Key) Credentials or Client Credentials grant types.
    An example of Resource Owner Password Credentials is:

    POST https://<ApplianceIP>/RSTS/oauth2/token

    Host: <ApplianceIP>

    Content-Type: application/json

    Accept: application/json

     

    {

    "grant_type": "password",

    "username": "<Username>",

    "password": "<Password>",

    "scope": "rsts:sts:primaryproviderid:local"

    }

    Where:

    • grant_type is required and must be set to password.
    • username is required and set to the user account you want to log in as.
    • password is required and set to the password associated with the username.
    • scope is required and set to one of the available identity provider's scope ID. The value shown in the example request, rsts:sts:primaryproviderid:local, is the default value available on all Safeguard for Privileged Passwords Appliances. User accounts that you create in Safeguard for Privileged Passwords directly (that is, not an Active Directory or LDAP account) will most likely have this scope value.

      NOTE: The list of identity providers is dynamic and their associated scope ID can only be obtained by making a request to:

      https://<ApplianceIP>/service/core/v3/AuthenticationProviders

      and parsing the returned JSON for the RstsProviderScope property.

    If you wish to authenticate using a client certificate, you must use the OAuth 2.0 Client Credentials grant type in which your certificate is included as part of the SSL connection handshake and the Authorization HTTP header is ignored. Set the scope to rsts:sts:primaryproviderid:certificate or any other identity provider that supports client certificate authentication.

    POST https://<ApplianceIP>/RSTS/oauth2/token

    Host: <ApplianceIP>

    Content-Type: application/json

    Accept: application/json

     

    {

    "grant_type": "client_credentials",

    "scope": "rsts:sts:primaryproviderid:certificate"

    }
  2. After successfully authenticating, your response will contain an access_token that must be exchanged for a user token to access the API.

    POST https://<ApplianceIP>/service/core/v3/Token/LoginResponse

    Host: <ApplianceIP>

    Content-Type: application/json

    Accept: application/json

     

    {

    "StsAccessToken": "<access_token from previous response>"

    }

You should now have an authorization token to be used for all future API requests. The token is to be included in the HTTP Authorization header as a Bearer token like this:

Authorization: Bearer <UserToken value>

For example:

GET https://<ApplianceIP>/service/core/v3/Users/-2

Host: <ApplianceIP>

Accept: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

NOTE: The token will expire in accordance to the Token Lifetime setting that is configured in Safeguard for Privileged Passwords at the time the token was issued.

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.

in

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

property values in a predefined set

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 Safeguard for Privileged Passwords Powershell module and scripting resources can be found on GitHub here: OneIdentity/safeguard-ps.

Installation

The Safeguard for Privileged Passwords 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 Worksation 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, Safeguard for Privileged Passwords 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.

Security

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 192.168.1.105. 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 192.168.1.105. 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 https://192.168.1.105 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.

Migrating the VM

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

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating