Licenses
As a SPP user, if you get an "appliance is unlicensed" notification, contact your Appliance Administrator.
Hardware appliance
The One Identity Safeguard for Privileged Passwords 4000 Appliance, 3000 Appliance and 2000 Appliance ship with the Privileged Passwords module which requires a valid license to enable functionality.
You must install a valid license. Once the module is installed, SPP shows a license state of Licensed and is operational. If the module license is not installed, you have limited functionality. That is, even though you will be able to configure access requests, if a Privileged Passwords module license is not installed, you will not be able to request a password release.
Virtual appliance Microsoft Windows licensing
You must license the virtual appliance with a Microsoft Windows license. We recommend using either the MAK or KMS method. Specific questions about licensing should be directed to your Sales Representative. The virtual appliance will not function unless the operating system is properly licensed.
Licensing setup and update
To enter licensing information when you first log in
The first time you log in as the Appliance Administrator, you are prompted to add a license. The Success dialog displays when the license is added.
On the virtual appliance, the license is added as part of Initial Setup. For more information, see Setting up the virtual appliance.
IMPORTANT: After successfully adding a license, the Software Transaction Agreement will be displayed and must be read and accepted in order to use SPP.
To configure reminders for license expiration
To avoid disruptions in the use of SPP, the Appliance Administrator must configure the SMTP server, and define email templates for the License Expired and the License Expiring Soon event types. This ensures you will be notified of an approaching expiration date. For more information, see Enabling email notifications.
Users are instructed to contact their Appliance Administrator if they get an "appliance is unlicensed" notification.
As an Appliance Administrator, if you receive a "license expiring" notification, apply a new license.
To update the licensing file
Safeguard licenses can be updated both on hardware and virtual machines, whereas OS licenses can be updated only on virtual machines.
To perform licensing activities
Navigate to Appliance Management > Appliance > Licensing.
-
To upload a new license file, click 
Upload new license file and browse to select the current license file. The Software Transaction Agreement will also be displayed during this process and must be read and accepted in order to complete the licensing process.
-
To remove the license file, select the license and click 
Remove selected license.
-
To get more information on the license and to export license data, click the What do these numbers mean? button, or click on the numbers in the tile.
If you want to export data about users, desktops or systems in CSV or JSON format, navigate to the table from which you want to export data by clicking the corresponding tab, for example Users Used.
Click the 
export icon located on the table. For more information on exporting, see Exporting data.
Below is the list of the available tabs.
For device-based licenses:
-
General
-
Desktops Used
-
Other Desktops
-
Systems Used
-
Other Systems
-
History
For user-based licenses:
-
General
-
Users Used
-
Password Vault Only
-
Other Users
-
History
-
The General tab, contains general information about the license:
Long Term Support (LTS) and Feature Releases
Releases use the following version designations:
- Long Term Support (LTS) Releases: The first digit identifies the release and the second is a zero (for example, 6.0 LTS).
- Maintenance LTS Releases: A third digit is added followed by LTS (for example, 6.0.6 LTS).
- Feature Releases: The Feature Releases version numbers are two digits (for example, 6.6).
Customers choose between two paths for receiving releases: Long Term Support (LTS) Release or Feature Release. See the following table for details.
Table 9: Comparison of Long Term Support (LTS) Release and Feature Release
| |
Long Term Support (LTS) Release |
Feature Release |
| General Release |
Scope: Includes new features, resolved issues and security updates
Versioning: The first digit identifies the LTS and the second digit is a 0 (for example, 6.0 LTS, 7.0 LTS, and so on). |
Scope: Includes the latest features, resolved issues, and other updates, such as security patches for the OS
Versioning: The first digit identifies the LTS and the second digit is a number identifying the Feature Release (for example, 6.6, 6.7, and so on). |
| Maintenance Release |
Scope: Includes critical resolved issues
Versioning: A third digit designates the maintenance LTS Release (for example, 6.0.6 LTS). |
Scope: Includes highly critical resolved issues
Versioning: A third digit designates the maintenance Feature Release (for example, 6.6.1). |
Release and support details can be found at Product Life Cycle.
|
|
CAUTION: Downgrading from the latest Feature Release, even to an LTS release, voids support for SPP. |
One Identity strongly recommends always installing the latest revision of the release path you use (Long Term Support path or Feature Release path).
Moving between LTS and Feature Release versions
You can move from an LTS version (for example, 6.0.7 LTS) to the same feature version (6.7) and then patch to a later feature version. After that, you can patch from the minimum version for the patch, typically N-3. If you move from an LTS version to a feature version, you will receive a warning like the following which informs you that you will only be able to apply a Feature Release until the next LTS Release:
Warning: You are patching to a Feature Release from an LTS Release. If you apply this update, you will not be able to upgrade to a non-Feature Release until the next LTS major release version is available. See the Administration Guide for details.
You cannot move from a Feature Release to LTS Release. For example, you cannot move from 6.7 to 6.0.7 LTS. You have to keep upgrading with each new Feature Release until the next LTS Release version is published. For this example, you would wait until 7.0 LTS is available.
Patching
You can only patch from a major version. For example, if you have version 6.6 and want to patch to 7.7, you must patch to 7.0 LTS and then apply 7.7.
An LTS major version of One Identity Safeguard for Privileged Passwords (SPP) will only work with the same LTS major version of Safeguard for Privileged Sessions (SPS). For the best experience, it is recommended you use the latest supported version.
Using API and PowerShell tools
Using API and PowerShell tools
SPP has a robust API with an easy to use tutorial. Safeguard PowerShell can be used to automate functions.
Using 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 to interact with it. Every function is exposed through the API to enable quick and easy integration regardless of what action you perform or in which language your applications are written. There are even a few things that can only be performed via the Safeguard SPP API.
|
|
CAUTION: Starting with SPP 6.8, any user that built a custom solution that monitors for events using ASP.NET SignalR will need to make changes to their solutions due to the upgrade to ASP.NET Core SignalR. For more information on this change and how to upgrade between the two versions, see the Microsoft documentation.
Users that built custom solutions that do not rely on event monitoring via SignalR should not be impacted. |
NOTE: SPP 6.8 versions of open source projects hosted on GitHub (SafeguardDotNet, SafeguardJava, safeguard-bash) have been updated to support ASP.NET Core SignalR so they will work with the new SignalR changes in SPP 6.8.
API tutorial
The SPP API tutorial is available on GitHub at: https://github.com/oneidentity/safeguard-api-tutorial.
Access the SPP API
SPP 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/signalr
-
a2a: Application integration specific operations. Fetching passwords and SSH keys, making access requests on behalf of users, and so on.
https://<Appliance IP>/service/a2a/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 Resource Owner Password Credentials 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 SPP Appliances. User accounts that you create in SPP 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/v4/AuthenticationProviders
and parsing the returned JSON for the RstsProviderScope property.
NOTE: Certain OAuth 2.0 grant types can be disabled if they are not needed. For more information, see Local Login Control.
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/v4/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/v4/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 SPP at the time the token was issued.
