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

Frequently asked questions

The following topics will help you find answers to some of your questions about managing Safeguard for Privileged Passwords:

Related Topics

Appliance settings

Troubleshooting

How do I access the API

You can use the API to automate Safeguard for Privileged Passwords tasks and access functionality not currently available in the Windows desktop client. Safeguard for Privileged Passwords has the following API categories:

  • Appliance: Resources used to manage the appliance itself (like setting the time, network configuration, syslog, etc.)

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

  • Core: Resources used to govern policy and manage accounts, etc.

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

  • Notification: Resources used to query the Safeguard for Privileged Passwords Appliance status

    https://<Appliance IP>/service/notification/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 Credentials or Client Credentials grant types. An example of the former 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/v2/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/v2/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/v2/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 (Settings | Safeguard Access | Login Control) at the time the token was issued.

How do I 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 270: 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 271: 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 272: 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

NOTE: When using the filter parameter, you can use parenthesis () to group logical expressions.

For example, GET/Users?filter=(FirstName eq 'Jane' and LastName eq 'Smith') and not Disabled

NOTE: When using the filter parameter, use the backward slash character (\) to escape quotes in strings.

For example: Get/Users?filter=UserName contains '\''

How do I audit transaction activity

The appliance records all activities performed within One Identity Safeguard for Privileged Passwords. Any administrator has access to the audit log information; however, your administrator permission set determines what audit data you can access. For more information, see Administrator permissions.

Safeguard for Privileged Passwords provides several ways to audit transaction activity.

Table 273: Safeguard for Privileged Passwords' auditing tools
Option Description

Password Archive

Where you access a previous password for an account for a specific date.

For more information, see Viewing password archive.

Check and Change Log

Where you view an account's password validation and reset history.

Access the Check and Change Log from Accounts. For more information, see Accounts.

History

Where you view the details of each operation that has affected the selected item.

Each of the Administrative Tools has a History tab. For more information, see History tab.

Activity Center

Where you can search for and review any activity for a specific time frame.

For more information, see Activity Center.

Workflow

Where you can audit the transactions performed as part of the workflow process from request to approval to review for a specific access request.

For more information, see Auditing request workflow.

Reports

Where you can view and export entitlement reports that show you which assets and accounts a selected user is authorized to access.

For more information, see Reports.

Related Documents