Safeguard for Privileged Passwords has a robust API with an easy to use tutorial. Safeguard PowerShell can be used to automate functions.
Safeguard for Privileged Passwords has a robust API with an easy to use tutorial. Safeguard PowerShell can be used to automate functions.
Safeguard for Privileged Passwords (SPP) is built with an API-first design and uses a modernized API based on a REST architecture which allows other applications and systems. Every function is exposed through the API to enable quick and easy integration regardless of what want to do or which language your applications are written. There are even a few things that can only only be done via the Safeguard SPP API. The Safeguard for Privileged Passwords API tutorial is available on GitHub at: https://github.com/oneidentity/safeguard-api-tutorial.
Safeguard for Privileged Passwords has the following API categories:
Core: Most product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, and so on.
https://<Appliance IP>/service/core/swagger/
Notification: Anonymous, unauthenticated operations. This service is available even when the appliance isn't fully online.
https://<Appliance IP>/service/notification/swagger/
Event: Specialized endpoint for connecting to SignalR for real-time events.
https://<Appliance IP>/event/notification/swagger/
a2a: Application integration specific operations. Fetching passwords, making access requests on behalf of users, and so on.
https://<Appliance IP>/a2a/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.
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:
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"
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:
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.
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.
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.
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.
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 |
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 '\''
PowerShell is a task-based command-line shell and scripting language used to automate tasks that manage operating systems and processes. The Safeguard for Privileged Passwords Powershell module and scripting resources can be found on GitHub here: OneIdentity/safeguard-ps.
The Safeguard for Privileged Passwords Powershell module is published to the PowerShell Gallery to make it easy to install using the built-in Import-Module cmdlet. Use the Update-Module cmdlet to get the latest functionality.
By default, Powershell modules are installed for all users. You need to be running Powershell as an Administrator to install for all users.
> Install-Module safeguard-ps
Or, you can install the modules just for you using the -Scope parameter which will never require administrator permission:
> Install-Module safeguard-ps -Scope CurrentUser
© 2024 One Identity LLC. ALL RIGHTS RESERVED. 이용 약관 개인정보 보호정책 Cookie Preference Center