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 208: API query filtering: Output
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 209: API query filtering: Paging
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 210: API query filtering: filter parameter
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 'Jane' 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 '\''
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:
One Identity Safeguard for Privileged Passwords supports the SAML 2.0 Web Browser SSO Profile, allowing you to configure federated authentication with many different Identity Provider STS servers and services, such as Microsoft's AD FS. Through the exchange of the federation metadata, you can create a trust relationship between the two systems. Then, you will create a Safeguard for Privileged Passwords user account to be associated with the federated account.
Safeguard supports both Service Provider (SP) initiated and Identity Provider (IdP) initiated logins. For SP initiated, the user will first browse to Safeguard and choose External Federation as the authentication provider. After entering just their email address, they will be redirected to the external STS to enter their credentials and perform any two-factor authentication that may be required by that STS. After successful authentication, they will be redirected back to Safeguard for Privileged Passwords and logged in. This works in both a web browser and the Safeguard desktop client application. For IdP initiated logins, a user will first go to their IdP STS and authenticate. Typically, the customer will have configured Safeguard as an application within their STS, allowing the user to just click on a link or icon and be redirected to Safeguard, automatically being logged in without having to enter any further credentials. Note, IdP initiated logins only work in the web browser, not the Safeguard desktop client application.
NOTE: Additional two-factor authentication can be assigned to the associated Safeguard for Privileged Passwords user account to force the user to authenticate again after being redirected back from the external STS.
To use external federation, you must first download the federation metadata XML for your STS and save it to a file. For example, for Microsoft's AD FS, you can download the federation metadata XML from:
https://<adfs server>/FederationMetadata/2007-06/FederationMetadata.xml.
It is the responsibility of the Appliance Administrator to configure the external federation service providers in Safeguard for Privileged Passwords.
To add an external federation service provider
- In Settings, select External Integration |Identity and Authentication.
- Click
Add then select External Federation.
- In the External Federation dialog, supply the following information:
-
Name: Enter a unique display name for the external federation service provider. The name is used for administrative purposes only and will not be seen by end users.
Limit: 100 characters
-
Realm: Enter a unique realm value, typically a DNS suffix, like contoso.com, that matches the email addresses of users intended to use this STS for authentication. A case-insensitive comparison will be used on this value when performing Home Realm Discovery.
Wildcards are not allowed.
Limit: 255 characters
- Federation Metadata File: Choose or enter the file path to the STS federation metadata file that you previously downloaded.
- Download Safeguard for Privileged Passwords Federation Metadata: If you have not done so before, click the link to download a copy of Safeguard for Privileged Passwords's federation metadata XML. You will need this file when creating the corresponding trust relationship on your STS server.
NOTE: The federation metadata XML files typically contain a digital signature and cannot be modified in any way, including white space. If you receive an error regarding a problem with the metadata, ensure that it has not been edited.