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

Making a request using the Application to Application service

Using the Application to Application service, third-party applications can interact with Safeguard for Privileged Passwords in the following ways:

  • Credential retrieval: A third-party application can retrieve a credential from the Safeguard for Privileged Passwords vault in order to perform automated functions on the target asset. In addition, you can replace hard coded passwords in procedures, scripts, and other programs with programmatic calls.
  • Access request broker: A third-party application can initiate an access request on behalf of an authorized user so that the authorized user can be notified of the available request and log in to Safeguard for Privileged Passwords to retrieve a password or start a session.

A third-party application authenticates with Safeguard for Privileged Passwords using an API key and a client certificate, rather than the bearer token normally used to authenticate Safeguard for Privileged Passwords API requests. To make a request, you must first retrieve the API key for the application from Safeguard for Privileged Passwords using an authorized user account (that is, using bearer token authentication), and install the correct certificate on the host that will be making the request. The certificate must be installed in the certificate store of the authorized certificate user that will make the request.

Prerequisites

To make a credential retrieval request from the third-party application

  1. Retrieve the relevant API key for the application from Safeguard for Privileged Passwords. You can retrieve the API key using the following methods:

    Using the desktop client:

    • Log in to the Safeguard for Privileged Passwords client as a Security Policy Administrator.
    • Navigate to Administration Tools | Settings | External Integration | Application to Application.
    • Click to display the API keys.
    • On the API Keys dialog, select the API key and click .

    Using the web client:

    • Log in to the Safeguard for Privileged Passwords client as a Security Policy Administrator.
    • Navigate to Security Policy Management | Application to Application.
    • Select the application and click (Edit).
    • On the Credential Retrieval tab, click .

    Using the Safeguard for Privileged Passwords API:

    • Use the following URL to retrieve the details of the registered application from the Safeguard for Privileged Passwords API. The ID property in the response can then be used to retrieve the relevant API key. The Certificate Thumbprint property in the response identifies the certificate that the application must use to authentication the request.

      https://<Appliance IP>/service/core/V3/A2ARegistrations?filter=AppName%20eq%20%22<ApplicationName>%22

    • Use the ID property in the response retrieved for the application registration to retrieve the API key for the selected account from the Safeguard for Privileged Passwords API:

      https://<Appliance IP>/service/core/V3/A2ARegistrations/<Id>/RetrievableAccounts?filter=AccountName%20eq%20%22<account name>%22%20and%20SystemName%20eq%20%22<system name>%22&fields=ApiKey

  2. Ensure that the certificate matching the application's registered CertificateUserThumbprint is installed on the host that will be making the request.
  3. Ensure that the selected certificate is trusted by Safeguard for Privileged Passwords. That is, install the trusted root certificate in Safeguard for Privileged Passwords.

  4. Create the application request, authenticating with the retrieved API key and the certificate thumbprint.

    • Set the Authorization header in the request to A2A <API key>.
    • The type can be Password or PrivateKey. Note that private keys can only be retrieved for service accounts.

    • Present the certificate with the request as appropriate for the invoking method. For example, when using the Invoke-WebRequest cmdlet, use the option:

      -CertificateThumbprint <thumbprint>

    To retrieve a credential, use the following request:

    GET https://<ApplianceIP>/service/A2A/V3/Credentials?type=Password
    Host: <ApplianceIP>
    Content-Type: application/json
    Accept: text/plain
    Authorization       A2A <API Key>

    This URL returns a string response.

To make an access request broker request from the third-party application

  1. Retrieve the relevant API key for the application from Safeguard for Privileged Passwords. You can retrieve the API key using the following methods:

    Using the desktop client:

    • Log in to the Safeguard for Privileged Passwords client as a Security Policy Administrator.
    • Navigate to Administration Tools | Settings | External Integration | Application to Application.
    • Click to display the API keys.
    • On the API Keys dialog, select the API key and click .

    Using the web client:

    • Log in to the Safeguard for Privileged Passwords client as a Security Policy Administrator.
    • Navigate to Security Policy Management | Application to Application.
    • Select the application and click (Edit).
    • On the Access Request Broker tab, click .

    Using the Safeguard for Privileged Passwords API:

    • Use the following URL is retrieve the details of the registered application from the Safeguard for Privileged Passwords API. The Id property in the response can then be used to retrieve the relevant API key. The Certificate Thumbprint property in the response identifies the certificate that the application must use to authentication the request.

      https://<Appliance IP>/service/core/V3/A2ARegistrations?filter=AppName%20eq%20%22<ApplicationName>%22

    • Use the ID retrieved for the application registration to retrieve the API key from the Safeguard API:

      https://<Appliance IP>/service/core/V3/A2ARegistrations/<Id>/AccessRequestBroker/ApiKey

  2. Ensure that the certificate matching the application's registered CertificateUserThumbprint is installed on the host that will be making the request.
  3. Ensure that the selected certificate is trusted by Safeguard for Privileged Passwords. That is, install the trusted root certificate in Safeguard for Privileged Passwords.

  4. Create the application request, authenticating with the retrieved API key and the certificate thumbprint.

    • Set the Authorization header in the request to A2A <API key>.

    • Present the certificate with the request as appropriate for the invoking method. For example, when using the Invoke-WebRequest cmdlet, use the option:

      -CertificateThumbprint <thumbprint>

    • To create an access request, use the following request:

      POST
      Host: <Appliance IP>
      Accept             application/json
      Content-type       application/json
      Authorization           A2A <API key>
      {
           "ForUser": "<user name>",
           "ForUserId": <user id>,
           "ForProvider": “<providername>”,
      "SystemId": <system id>,
           "SystemName": "<system name>",
           "AccountId": <account id>,
           "AccountName": "<account name>",
           "AccessRequestType": "<request type>",
      “RequestedDurationDays”: <days>
           "RequestedDurationHours": <hours>,
      “RequestedDurationMinutes”: <minutes>,
      “RequestedFor”: “<date>,
           "ReasonCodeId": <reason code id>,
           "ReasonCode": "<reason name>",
           "ReasonComment": "<reason comment>",
      “IsEmergency”: <bool>,
      “TicketNumber”: “<ticket>”
       
      }

      This URL returns the new request if successful.

      Exceptions

      Most of the fields in this access request match those in a normal access request, with the exceptions noted here:

      The following fields are used to identify the target Safeguard for Privileged Passwords user that will be used to create the request. The result must uniquely identify a valid Safeguard for Privileged Passwords user for which the application has been granted permission to create an access request. If the search results in multiple matches or no matches, an error is returned.

      • ForUserId: The database ID of a Safeguard for Privileged Passwords user. This takes priority if it contains a value.
      • ForUser: The name of a Safeguard for Privileged Passwords user. This value is ignored if ForUserId contains a value.
      • ForProvider: An optional provider name, that can be used to limit the search for ForUser.

      The following fields are used to uniquely identify the target system. If the search results in multiple matches or no matches, an error is returned.

      • SystemId: The database ID of a Safeguard for Privileged Passwords asset. This field is used to search for a matching asset in the following order:
        • System Name: Exact match on the system name
        • Network Address: Exact match on the network address
        • String search: A string search on all string properties for the asset

      The following fields are used to uniquely identify the target account. If the search results in multiple matches or no matches, an error is returned.

      • AccountId: The database ID of a Safeguard for Privileged Passwords account. This takes priority if it contains a value.
      • AccountName: This is ignored if AccountId contains a value. This field is used to search for a matching account in the following order:
        • Account Name: Exact match on the account name
        • String search: A string search on all string properties for the account

      The following fields can be used to identify the reason code. If the search results in multiple matches or no matches, the reason code is set to null.

      • ReasonCodeId: The database ID of a predefined reason code. This takes priority if it contains a value.
      • ReasonCode: The name of a predefined reason code. This is ignored if ReasonCodeId contains a value.
    Access request creation

    Once the target user and account have been determined, the Application to Application service attempts to create the access request. Normal policy rules determine whether the attempt is successful.

Approval Anywhere

IMPORTANT: The Cloud Assistant feature is designed to replace the Approval Anywhere feature which will be deprecated in a future Safeguard for Privileged Passwords release. Current Approval Anywhere users are encouraged to begin switching to Cloud Assistant as soon as possible.

The Safeguard for Privileged Passwords Approval Anywhere feature integrates its access request workflow with Starling Two-Factor Authentication (2FA), allowing approvers to receive a notification through an app on their mobile device when an access request is submitted. The approver can then approve (or deny) access requests through their mobile device without needing access to the desktop or web application.

The Approval Anywhere feature is enabled when you join Safeguard for Privileged Passwords to Starling. For more information, see Starling. Once enabled, it is the responsibility of the Security Policy Administrator to define the users who are authorized to use Approval Anywhere to approve access requests.

NOTE: In version 2.1 and earlier, you had to specify a Starling API key in order to use Approval Anywhere and Starling Two-Factor Authentication (2FA) as a secondary authentication provider. This is no longer necessary when you join Safeguard for Privileged Passwords to Starling. If you previously configured these features, once you join to Starling, Safeguard for Privileged Passwords automatically migrates your previous configurations to use the credential string generated by the join process.

Go to Approval Anywhere:

  • web client: Navigate to Security Policy Management | Approval Anywhere.
  • desktop client: Navigate to Administrative Tools | Settings | External Integration | Approval Anywhere.

The Approval Anywhere pane displays the following about the users authorized to use the Approval Anywhere feature.

Table 210: Approval Anywhere: Properties
Setting Description

Name

Name of the Safeguard for Privileged Passwords user.

NOTE: This user must also be added as an approver in an access request policy.

Mobile Phone

Valid mobile phone number in E.164 format for the authorized user.

Alternate Mobile Phone

Alternate mobile phone number in E.164 format.

Email Address

Valid email address for the authorized user.

Use these toolbar buttons to manage the users authorized to use Approval Anywhere.

Table 211: Approval Anywhere: Toolbar
Setting Description

Add

Add Safeguard for Privileged Passwords users who are authorized to use this feature to approve (or deny) access requests.

NOTE: Approval Anywhere approvers must have a valid mobile phone number in E.164 format and a valid email address defined. If a user does not display a valid mobile phone number or email address, edit the user record before proceeding.

E.164 format: +<country code><area code><phone number>

NOTE: These same users must also be added as approvers in an access request policy.

Remove

Remove the selected user as an authorized user.

Refresh

Update the list of users authorized to use Approval Anywhere.

Adding authorized user for Approval Anywhere

Once Safeguard for Privileged Passwords is joined to Starling, use the Approval Anywhere pane to add the Safeguard for Privileged Passwords users that can use the Approval Anywhere feature to approve access requests.

NOTE: If you upgraded from a previous version of Safeguard for Privileged Passwords where you have already configured Approval Anywhere, your existing configure will continue to work. However, you will not be able to manage your Approval Anywhere users until you join Safeguard for Privileged Passwords to Starling. Once you join to Starling, Safeguard for Privileged Passwords automatically migrates your previous configurations to use the credential string generated by the join process.

TIP: Ensure OneTouch approvals is enabled on the two-factor authentication app on your mobile device.

To add users who are authorized to use Approval Anywhere

  1. Log in to the Safeguard for Privileged Passwords client as a Security Policy Administrator.
  2. To go to Approval Anywhere:
    • web client: Security Policy Management | Approval Anywhere.
    • desktop client: Navigate to Administrative Tools | Settings | External Integration | Approval Anywhere.
  3. Click Add.

  4. In the Users dialog, select users from the list and click OK.

    NOTE: Approval Anywhere approvers must have a valid mobile phone number in E.164 format and a valid email address defined. If a user does not display a valid mobile phone number or email address, edit the user record before proceeding.

    E.164 format: +<country code><area code><phone number>

  5. Add these Approval Anywhere users as approvers in the appropriate access request policy. For more information, see Creating an access request policy (desktop client).

Once a user is added as an Approval Anywhere user and as an approver in an access request policy, when an access request requires approval, Safeguard for Privileged Passwords sends a notification to the approver's Starling 2FA mobile app. The approver can either approve or deny the access request directly from the Starling 2FA mobile app.

NOTE: Revoking an access request that has already been approved is not available via the mobile app. You must use the Safeguard for Privileged Passwords desktop or web client to perform that action.

Email

It is the responsibility of the Appliance Administrator to configure Safeguard for Privileged Passwords to automatically send email notifications when certain events occur.

Use the Email pane to configure the SMTP server to be used for email notifications and to edit the email templates that define the content of email notifications.

Before you start

Before configuring the SMTP server, perform the following, as needed.

  • Configure the DNS Server and set up the user's email address correctly.
  • If you are using a transport layer for email authentication, it is recommended you create the certificate signing request (CSR) with SPP using the Add Certificate | Create Certificate Signing Request (CSR) option. For more information, see Creating an audit log Certificate Signing Request.

    CSRs may be installed in the following formats.

    • Install Certificate generated from CSR including:
      • DER Encoded Files (.cer, .crt, or .der)
      • PEM Encoded Files (.pem)
    • Install Certificate with Private Key including:
      • PKCS#12 (.p12 or .pfx)
      • Personal Information Exchange Files (.pfx)

To configure the SMTP Server

  1. Go to SMTP Server:
    • web client: Navigate to External Integration | Email.
    • desktop client: Navigate to Administrative Tools | Settings | External Integration | Email.
  2. To configure the email notifications, enter these global settings for all emails:
    • SMTP Server Address: Enter the IP address or DNS name of the mail server. When unspecified, the email client is disabled.
      When entering an IPv6 address, you must encapsulate it in square brackets, such as [b86f:b86f:b86f:1:b86f:b86f:b86f:b86f].
      If you are using a mail exchanger record (MX record), you must specify the domain name for the mail server.
    • SMTP Port: A default port is set for SMTP which should be changed, if needed. By default, the SMTP port is 465 or, if you are using SSL/TLS, the default is port 25. The range is 1 to 65535.

    • Select one of the following to add Transport Layer Security.

      • Require STARTTLS: Select this option to connect to an SMTP server that supports the STARTTLS command to elevate the connection from text-based to TLS.
      • Require SMTPS: Select this option to immediately use TLS in its connection to the target SMTP server.
      • None: There is no transport layer security applied to emails.

      If you selected Require STARTTLS or Require SMTPS, you can select one, both, or none of the following: 

      • Verify SSL Certificate: Verify SSL Certificate: If not selected, the remote SMTP server's SSL certificate is not verified.
      • Use Client Certificate: Select this check box to present a Client Certificate during a TLS connection to the remote SMTP server.
    • User Authentication: Select an option if you want to authenticate access to the SMPT server.
      • Account: If selected, click Directory Account or Asset Account then select the account to use for authentication.
      • Password: If selected, enter the Account Name and Account Password to use for authentication.
      • None: If selected, the user will not be authenticated.
    • Send Test Email To (web client) or Sender Email (desktop client): Enter an email address to use as the "From" address for all emails originating from the appliance. This is required if you specify the SMTP Server Address. The limit is 512 characters.

To validate your setup in the web client

Test the email setup. When you test, no emails except for the tests are handled.

  1. In Send Test Email To, enter the email address of where to send the test message.
  2. Enter the Timeout for the test email from delivery start to the email successfully being sent or the return of an error notification. Each IP address is tested and if one fails, the an error is returned for the entire process. The maximum is 255 seconds per IP check. The error logs are maintained for two days. During testing, a valid From address with an invalid To address is not delivered.
  3. Click Send Test Email. The email is sent using the configuration settings. If there is an error or timeout, a message displays in the user interface.
  4. You must check to ensure the email is delivered. If there was no message in the user interface but the email is not delivered, check the support bundle log files in the SMTPSVC1 folder. Two days of logs are maintained. For more information, see Support bundle.

To validate your setup in the desktop client

Test the email setup. When you test, no emails except for the tests are handled.

  1. The Sender Email displays. You can change this.
  2. Select the Test Email Settings link.
  3. In the Test Email dialog, enter the Send To email address of where to send the test message.
  4. Enter the Timeout for the test email from delivery start to the email successfully being sent or the return of an error notification. Each IP address is tested and if one fails, the an error is returned for the entire process. The maximum is 255 seconds per IP check. The error logs are maintained for two days. During testing, a valid From address with an invalid To address is not delivered.
  5. Click Send. The email is sent using the configuration settings. If there is an error or timeout, a message displays in the user interface.
  6. You must check to ensure the email is delivered. If there was no message in the user interface but the email is not delivered, check the support bundle log files in the SMTPSVC1 folder. Two days of logs are maintained. For more information, see Support bundle.

To use email templates

desktop client: The Email Templates grid at the bottom of this pane lists the email templates used to define the content to be included in email notifications.

For more information, see Email Templates.

For more information, see Email Templates.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating