Converse agora com nosso suporte
Chat com o suporte

One Identity Safeguard for Privileged Passwords 6.0 LTS - Administration Guide

Introduction System requirements Using the virtual appliance and web management console Cloud deployment considerations Setting up Safeguard for Privileged Passwords for the first time Search box Using the web client Installing the desktop client Using the desktop client Privileged access requests Toolbox Accounts Account Groups Assets Asset Groups Discovery 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 Safeguard Access settings
Users User Groups Disaster recovery and clusters Administrator permissions Preparing systems for management Troubleshooting Frequently asked questions Appendix A: Safeguard ports Appendix B: SPP 2.7 or later migration guidance Appendix C: SPP and SPS join guidance Appendix D: Regular Expressions Appendix E: Historical changes by release Glossary

How do I access the API

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.

Access the SPP API

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/

  • Appliance: RAppliance-specific operations, such as setting IP address, maintenance, backups, support bundles, appliance management. https://<Appliance IP>/service/appliance/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.

  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 206: 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 207: 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 208: 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

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 '\''

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:

How do I configure external federation authentication

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.
    IMPORTANT: For on-prem VM (Hyper-V or VMware only: After installing v6.0 or after a backup restore from v6.0, the log on to an existing External Federation provider will fail. See KB Article xxxx to for the steps to edit the app registration’s Application ID URI.
  • 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.

Documentos relacionados

The document was helpful.

Selecione a classificação

I easily found the information I needed.

Selecione a classificação