Chat now with support
Chat with Support

One Identity Safeguard for Privileged Passwords 7.5.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

Adding an application registration

To allow a third-party application to perform one of the tasks provided by the Application to Application service, you must register the third-party application with Safeguard for Privileged Passwords.

Prerequisites
  • User Administrator adds certificate users to Safeguard for Privileged Passwords.
  • Asset Administrator adds assets and accounts to Safeguard for Privileged Passwords.

To add an application registration

  1. Log in to the Safeguard for Privileged Passwords web client as a Security Policy Administrator.
  2. Navigate to Security Policy Management > Application to Application.

  3. Click Add. The New Registration dialog displays.

  4. Specify the following information: 
    1. Name: Enter a name for the application registration.
    2. Description: Enter information about the application registration.

    3. Certificate User: Click Browse to select a certificate user who is associate with the third-party application being registered.

      A certificate user must be specified. If not specified when you initially add an application registration, click Edit on the Application to Application page to specify the certificate user.

      NOTE: For SignIR, connect as a certificate user using A2A API key for the retrievable account you want to monitor that is assigned an A2A registration for Retrievable Accounts. The connected certificate user will receive event notifications for any events related to that account (for example, password change, update, and delete). For more information, see Making a request using the Application to Application service..

    4. Visible To Certificate Users: Select this check box to make the registration, including the API keys, visible by the certificate user that is configured for the A2A registration.

  5. Click OK. This will save the initial application registration information and open a new dialog with additional settings.

  6. The Access Request Broker tab displays a list of users for which the third-party application can create an access request on behalf of.

    • Click to add a user or user group to the list.

    • Click Edit Restrictions to specify IP address restrictions for all of the users and user groups in the list.

      A restriction is a list of IP addresses or range of IP addresses that are allowed to call the Application to Application service to perform this task. That is, if a restriction is added to a Credential Retrieval or Access Request Broker task, the service will only allow requests that initiate from the IP addresses specified in the restriction list.

      The IP address notation can be:

      • An IPv4 or IPv6 address (for example, 10.5.32.4).

      • An address range in CIDR notation (for example, 10.5.0.0/16).

    • Click to remove the selected user from the list.

  7. The Credential Retrieval tab displays a list for which the third-party can retrieve credentials from Safeguard for Privileged Passwords without going through the normal workflow process.

    • Click to add an account to the list.

    • Click Restrictions in the Restrictions column to specify IP address restrictions for the selected account.

      A restriction is a list of IP addresses or range of IP addresses that are allowed to call the Application to Application service to perform this task. That is, if a restriction is added to a Credential Retrieval or Access Request Broker task, the service will only allow requests that initiate from the IP addresses specified in the restriction list.

      The IP address notation can be:

      • An IPv4 or IPv6 address (for example, 10.5.32.4).

      • An address range in CIDR notation (for example, 10.5.0.0/16).

    • Click to remove the selected account from the list.
  8. Click OK to save and close the dialog.

Once an application registration is added to Safeguard for Privileged Passwords, the third-party application can authenticate with Safeguard for Privileged Passwords using the API key that was generated and the certificate that was associated with the registration. To make a request, you must retrieve the relevant API key for the application using an authorized account (that is, using bearer token authentication) and install the correct certificate on the host that will make the request. For more information, see Making a request using the Application to Application service..

Deleting an application registration

You can delete a previously configured application registration from Safeguard for Privileged Passwords.

To delete an application registration

  1. Navigate to Security Policy Management > Application to Application.
  2. Select the application registration to be deleted.
  3. Click the toolbar button.
  4. Confirm your request.

Regenerating an API key

If, as the Security Policy Administrator, you discover that the API key has been stolen or misplaced, you can regenerate the API key at any time. When you regenerate an API key, it invalidates the old API key and prevents any services from using that key to access the Application to Application service.

To regenerate an API key

  1. Log in to the Safeguard for Privileged Passwords web client as a Security Policy Administrator.
  2. Navigate to Security Policy Management > Application to Application.
  3. Select an application registration from the list and click (Edit).

  4. On the Access Request Broker tab, click (Regenerate).

You can now view or copy the new API key to the clipboard and use this new API key in your third-party application to access the Application to Application interfaces. See Making a request using the Application to Application service.

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 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://<ApplianceIP>/service/core/v4/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/v4/A2ARegistrations/<AppId>/RetrievableAccounts?filter=AssetName%20eq%20%22<Asset Name>%22%20and%20AccountName%20eq%20%22<AccountName>%22

  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/v4/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 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://<ApplianceIP>/service/core/v4/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/v4/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.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating