Chat now with support
Chat with Support

One Identity Safeguard for Privileged Passwords 2.4 - Administration Guide

Introduction System requirements Installing the One Identity Safeguard for Privileged Passwords desktop client Setting up Safeguard for Privileged Passwords for the first time Getting acquainted with the console Privileged access requests Toolbox Accounts Account Groups Assets Asset Groups Directories Entitlements Partitions Settings
Access Request settings Appliance settings Asset Management settings Backup and Retention settings Certificate settings Cluster settings External Integration settings Messaging settings Profile settings Access settings Sessions settings
Users User Groups Disaster recovery Administrator permissions Preparing systems for management Troubleshooting Frequently asked questions
How do I access the API How do I audit transaction activity How do I configure external federation authentication How do I manage accounts on unsupported platforms How do I modify the appliance configuration settings How do I prevent Safeguard for Privileged Passwords messages when making RDP connections How do I see which assets and/or accounts are governed by a profile How do I set the appliance system time How do I setup discovery jobs How do Safeguard for Privileged Passwords database servers use SSL What are the access request states What do I do when an appliance goes into quarantine What is required for One Identity Safeguard for Privileged Passwords Privileged Sessions What is required to integrate with Starling Identity Analytics & Risk Intelligence What needs to be set up to use Application to Application What role-based email notifications are generated by default When does the rules engine run for dynamic grouping and tagging Why did the password change during an open request Why join Safeguard for Privileged Passwords to One Identity Starling
Safeguard Desktop Player Appendix: Safeguard ports

How do I make 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 desktop client or API.

    Using the desktop client:

    • Log into 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 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/V2/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/V2/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/V2/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 desktop client or API.

    Using the desktop client:

    • Log into 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 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/V2/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/V2/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>",
           "Comment": "<comment>",
      “IsEmergency”: <bool>,
      “TicketNumber”: “<ticket>”
       
      }

      This URL returns the new request if successful.

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

      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 identity 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.

    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.

What role-based email notifications are generated by default

One Identity Safeguard for Privileged Passwords can be configured to send email notifications warning you of operations that may require investigation or action. Your administrative permissions determine which email notifications you will receive by default.

Table 279: Email notifications based on administrative permissions
Administrative permission Event/Warning

Appliance Administrator

Operations Administrator

Appliance Healthy

Appliance Restarted

Appliance Sick

Appliance Task Failed

Archive Task Failed

Cluster Failover Started

Cluster Replica Enrollment Completed

Cluster Replica Removal Started

Cluster Reset Started

Disk Usage Warning

Factory Reset Appliance

License Expired

NTP Error Detected

Operational Mode Appliance

Raid Error Detected

Reboot Appliance

Shutdown Appliance

Directory Administrator or delegated partition owner

Account Discovery Failed

Dependent Asset Update Failed

Password Change Failed

Password Check Failed

Password Check Mismatch

Password Reset Needed

Restore Account Failed

Ssh Host Key Mismatch

Ssh Key Change Failed

Ssh Key Install Failed

Suspend Account Failed

Test Connection Failed

Security Policy Administrator

Policy Expiration Warning

Policy Expired

Entitlement Expiration Warning

Entitlement Expired

NOTE: Safeguard for Privileged Passwords administrators can use the following API to turn off these built-in email notifications:

POST /service/core/v2/Me/Subscribers/{id}/Disable

In addition, Safeguard for Privileged Passwords administrators can subscribe to additional events based on their administrative permissions using the following API:

POST /service/core/v2/Events

When does the rules engine run for dynamic grouping and tagging

The running of the rules engine used for dynamic grouping and tagging is triggered by the creation or change of pertinent objects. For example:

  • Whenever you add or change an asset account, all applicable rules are reevaluated against that asset account.
  • Whenever you change an asset account rule, the rule is reevaluated against all asset accounts within the scope of that rule. That is, against all asset accounts for grouping and the asset accounts within the designated partitions for tagging.

NOTE: In large environments, there is a possibility that the user interface may return before all of the rules have been reevaluated and you may not see the results you were expecting. If this happens, wait a few minutes and Refresh the screen to view the results.

Why did the password change during an open request

There are three ways a password can change while a user has it checked out.

  1. An Asset Administrator manually changes the password. For more information, see Checking, changing, or setting an account password.
  2. A profile was scheduled to automatically change the password. For more information, see Change Password.
  3. A policy allows both simultaneous access and requires that the password change when a user checks it in.

If the password changes while a user has it checked out, and the current request is still valid, the user can select either Copy or Show Password again to obtain the new password.

Related Documents