This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Protegrity REST APIs

Overview of the Policy Management and Encrypted Resilient Package REST APIs.

The Protegrity REST APIs include the following APIs:

  • Policy Management REST APIs The Policy Management REST APIs are used to create or manage policies.
  • Encrypted Resilient Package APIs The Encrypted Resilient Package REST APIs include the REST API that is used to encrypt and export a resilient package, which is used by the resilient protectors.
    For more information on how the REST API is used to export the encrypted resilient package in an immutable policy deployment, refer to the section DevOps Approach for Application Protector.

1 - Accessing the Protegrity REST APIs

Overview of how to access the Protegrity REST APIs.

The following section lists the requirements for accessing the Protegrity REST APIs.

  1. Available endpoints - Protegrity has enabled the following endpoints to access the REST APIs.

    Base URL
    https://{ESA IP address or Hostname}/pty/<Version>/<API>

    Where:

    • ESA IP address or Hostname: Specifies the IP address or Hostname of the ESA.
    • Version: Specifies the version of the API.
    • API: Endpoint of the REST API.

  2. Authentication - You can access the REST APIs using basic authentication, client certificates, or tokens. The authentication depends on the type of REST API that you are using. For more information about accessing the REST APIs using these authentication mechanisms, refer to the section Accessing REST API Resources.

  3. Authorization - You must assign the permissions to roles for accessing the REST APIs. For more information about the roles and permissions required, refer to the section Managing Roles.

2 - View the Protegrity REST API Specification Document

Access and view the REST API specification document. Use an OpenAPI specification editor, such as Swagger Editor, to generate samples.

The steps mentioned in this section contains the usage of Docker containers and services to download and launch the images for Swagger Editor within a Docker container.

For more information about Docker, refer to the Docker documentation.

The following example uses Swagger Editor to view the REST API specification document. In this example, JSON Web Token (JWT) is used to authenticate the REST API.

  1. Install and start the Swagger Editor.

  2. Download the Swagger Editor image within a Docker container using the following command.

    docker pull swaggerapi/swagger-editor

  3. Launch the Docker container using the following command.

    docker run -d -p 8888:8080 swaggerapi/swagger-editor

  4. Paste the following address on a browser window to access the Swagger Editor using the specified host port.

    http://localhost:8888/

  5. Download the REST API specification document using the following command.

    curl -H "Authorization: Bearer ${TOKEN}" "https://<NFA IP address or Hostname>/pty/<Version>/<API>/doc" -H "accept: application/x-yaml" --output api-doc.yaml

    In this command:

    • TOKEN is the environment variable that contains the JWT token used to authenticate the REST API.
    • <Version> is the version number of the API. For example, v1 or v2.
    • <API> is the API for which you want to download the OpenAPI specifications document. For example, specify the value as pim to download the OpenAPI specifications for the Policy Management REST API. Similarly, specify the value as auth to download the OpenAPI specifications for the Authentication and Token Management API.
      For more information about the Policy Management REST APIs, refer to the section Using the Policy Management REST APIs.
      For more information about the Authentication and Token Management REST APIs, refer to the section Using the Authentication and Token Management REST APIs

  6. Drag and drop the downloaded api-doc.yaml* file into a browser window of the Swagger Editor.

Generating the REST API Samples Using the Swagger Editor

Perform the following steps to generate samples using the Swagger Editor.

  1. Open the api-doc.yaml* file in the Swagger Editor.

  2. On the Swagger Editor UI, click on the required API request.

  3. Click Try it out.

  4. Enter the parameters for the API request.

  5. Click Execute.

    The generated Curl command and the URL for the request appears in the Responses section.

3 - Using the Common REST API Endpoints

Explains the usage of the Common APIs with some generic samples.

The following section specifies the common operations that are applicable to all the Protegrity REST APIs.

The Base URL for each API will change depending on the version of the API being used. The following table specifies the version that you must use when executing the common operations for each API.

REST APIVersion in the Base URL <Version>
Policy Managementv2
Encrypted Resilient Packagev1
Authentication and Token Managementv1

Common REST API Endpoints

The following table lists the common operations for the Protegrity REST APIs.

REST APIDescription
/versionRetrieves the service versions that are supported by the Protegrity REST APIs on the ESA.
/healthThis API request retrieves the health information for the Protegrity REST APIs and identifies whether the corresponding service is running.
/docThis API request retrieves the API specification document.
/logThis API request retrieves current log level set for the corresponding REST API logs.
/logThis API request changes the log level for the REST API service during run-time. The level set through this resource is persisted until the corresponding service is restarted. This log level overrides the log level defined in the configuration.

Retrieving the Supported Service Versions

This API retrieves the service versions that are supported by the corresponding REST API service on the ESA.

Base URL
https://{ESA IP address}/pty/<Version>/<API>
Path
/version
Method
GET

CURL request syntax

curl -H "Authorization: Bearer TOKEN" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/version"

This sample request uses the JWT token authentication.

Sample CURL response

{"version":"1.8.1","buildVersion":"1.8.1-alpha+605.gfe6b1d.master"}

Retrieving the Service Health Information

This API request retrieves the health information of the REST API service and identifies whether the service is running.

Base URL
https://{ESA IP address}/pty/<Version>/<API>
Path
/health
Method
GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"

Authentication credentials

TOKEN - Enviroment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/health"

This sample request uses the JWT token authentication.

Sample CURL response

{
  "isHealthy" : true
}

Where,

  • isHealthy: true - Indicates that the service is up and running.
  • isHealthy: false - Indicates that the service is down.

Retrieving the API Specification Document

This API request retrieves the API specification document.

Base URL
https://{ESA IP address}/pty/<Version>/<API>
Path
/doc
Method
GET

CURL request syntax

curl -H "Authorization: Bearer <Token>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Sample CURL requests

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc"

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc" -o "rps.yaml"

These sample requests uses the JWT token authentication.

Sample CURL responses

The Encrypted Resilient Package API specification document is displayed as a response. If you have specified the “-o” parameter in the CURL request, then the API specification is copied to a file specified in the command. You can use the Swagger UI to view the API specification document.

Retrieving the Log Level

This API request retrieves current log level set for the REST API service logs.

Base URL
https://{ESA IP address}/pty/<Version>/<API>
Path
/log
Method
GET

CURL request syntax

curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Sample CURL request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/log"

This sample request uses the JWT token authentication.

Sample CURL response

{
  "level": "INFO"
}

Setting Log Level for the REST API Service Log

This API request changes the REST API service log level during run-time. The level set through this resource persists until the corresponding service is restarted. This log level overrides the log level defined in the configuration.

Base URL
https://{ESA IP address}/pty/<Version>/<API>
Path
/log
Method
POST

CURL request syntax

curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer <TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"

In this command, Token indicates the JWT token used for authenticating the API.

Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.

curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"

Authentication credentials

TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Request body elements

log level

Set the log level. The log level can be set to SEVERE, WARNING, INFO, CONFIG, FINE, FINER, or FINEST.

Sample CURL request

curl -X POST "https://{ESA IP Address}/pty/v1/rps/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"SEVERE\"}"

This sample request uses the JWT token authentication.

Sample response

The log level is set successfully.

4 - Using the Policy Management REST APIs

Explains the usage of the Policy Management APIs with some generic samples.

The user accessing these APIs must have the Security Officer permission for write access and the Security Viewer permission for read-only access.
For more information about the roles and permissions required, refer to the section Managing Roles.

The Policy Management API uses the v2 version.

If you want to perform common operations using the Policy Management REST API, then refer the section Using the Common REST API Endpoints.

The following table provides section references that explain usage of some of the Policy Management REST APIs. It includes an example workflow to work with the Policy Management functions. If you want to view all the Policy Management APIs, then use the /doc API to retrieve the API specification.

REST APISection Reference
Policy Management initializationInitializing the Policy Management
Creating an empty manual role that will accept all usersCreating a Manual Role
Create data elementsCreate Data Elements
Create policyCreate Policy
Add roles and data elements to the policyAdding roles and data elements to the policy
Create a default data storeCreating a default datastore
Deploy the data storeDeploying the Data Store
Get the deployment informationGetting the Deployment Information

Initializing the Policy Management

This section explains how you can initialize Policy Management to create the keys-related data and the policy repository.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/init
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/init" -H "accept: application/json"

This sample request uses the JWT token authentication.

Creating a Manual Role

This section explains how you can create a manual role that accepts all the users.

For more information about working with roles, refer to the section Working with Roles.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/roles
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/roles" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"ROLE\",\"mode\":\"MANUAL\",\"allowAll\": true}

This sample request uses the JWT token authentication.

Creating Data Elements

This section explains how you can create data elements.

For more information about working with data elements, refer to the section Working with Data Elements.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/roles
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/dataelements" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\": \"DE_ALPHANUM\",\"description\": \"DE_ALPHANUM\",\"alphaNumericToken\":{\"tokenizer\":\"SLT_1_3\",\"fromLeft\": 0,\"fromRight\": 0,\"lengthPreserving\": true, \"allowShort\": \"YES\"}}"

This sample request uses the JWT token authentication.

Creating Policy

This section explains how you can create a policy.

For more information about working with policies, refer to the section Creating Policies.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/policies
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/policies" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"POLICY\",\"description\": \"POLICY\", \"template\":{\"access\":{\"protect\":true,\"reProtect\":true,\"unProtect\":true},\"audit\":{\"success\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false},\"failed\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false}}}}"

This sample request uses the JWT token authentication.

Adding Roles and Data Elements to a Policy

This section explains how you can add roles and data elements to a policy.

For more information about adding roles and data elements to a policy, refer to the sections Adding Data Elements to Policy and Adding Roles to Policy respectively.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/policies/1/rules
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/policies/1/rules" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"role\":\"1\",\"dataElement\":\"1\",\"noAccessOperation\":\"EXCEPTION\",\"permission\":{\"access\":{\"protect\":true,\"reProtect\":true,\"unProtect\":true},\"audit\":{\"success\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false},\"failed\":{\"protect\":false,\"reProtect\":false,\"unProtect\":false}}}}"

This sample request uses the JWT token authentication.

Creating a Default Data Store

This section explains how you can create a default data store.

For more information about working with data stores, refer to the section Creating a Data Store.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/datastores
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/datastores" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"DS\",\"description\": \"DS\", \"default\":true}"

This sample request uses the JWT token authentication.

Deploying the Data Store

This section explains how you can deploy policies or trusted applications linked to a specific data store or multiple data stores.

For more information about deploying the Data Store, refer to the section Deploying Data Stores to Protectors.

Deploying a Specific Data Store

This section explains how you can deploy policies and trusted applications linked to a specific data store. The specifications provided for the specific data store are applied and becomes the end-result.

Note: If you deploy an array with empty policies or trusted applications, or both, then the connected protectors contain empty definitions for these respective items.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/datastores/{dataStoreUid}/deploy
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address or Hostname}:443/pty/v2/pim/datastores/{dataStoreUid}/deploy" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"policies\":[\"1\"],\"applications\":[\"1\"]}"

This sample request uses the JWT token authentication.

Deploying Data Stores

This section explains how you can deploy data stores, which can contain the linking of either the policies or trusted applications, or both for the deployment.

Note: If you deploy a data store containing an array with empty policies or trusted applications, or both, then the connected protectors contain empty definitions for these respective items.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/deploy
Method
POST

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X POST "https://{ESA IP address}:443/pty/v2/pim/deploy" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"dataStores\":[{\"uid\":\"1\",\"policies\":[\"1\"],\"applications\":[\"1\"]},{\"uid\":\"2\",\"policies\":[\"2\"],\"applications\":[\"2\"]}]}"

This sample request uses the JWT token authentication.

Getting the Deployment Information

This section explains how you can check the complete deployment information. This service returns the list of the data stores with the connected policies and trusted applications.

Note: The result might contain data store information that is pending deployment after combining the Policy Management operations performed through the ESA Web UI and PIM API.

Base URL
https://{ESA IP address or Hostname}/pty/v2
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Path
/pim/deploy
Method
GET

Sample Request

curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address or Hostname}:443/pty/v2/pim/deploy" -H "accept: application/json"

This sample request uses the JWT token authentication.

5 - Using the Encrypted Resilient Package REST APIs

Explains the usage of the Encrypted Resilient Package APIs.

The Encrypted Resilient Package API is only used by the Immutable Resilient protectors.

Before you begin:

  • Ensure that the concept of resilient protectors and necessity of a resilient package is understood.
    For more information on how the REST API is used to export the encrypted resilient package in an immutable policy deployment, refer to the section DevOps Approach for Application Protector.

  • Ensure that the RPS service is running on the ESA.

  • The user accessing this API must have the Export Resilient Package permission.
    For more information about the roles and permissions required, refer to the section Managing Roles.

The Encrypted Resilient Package API uses the v1 version.

If you want to perform common operations using the Encrypted Resilient Package API, then refer the section Using the Common REST API Endpoints.

The following table provides a section reference to the Encrypted Resilient Package API.

REST APISection Reference
Exporting the resilient packageExporting Resilient Package

Exporting Resilient Package Using GET Method

This API request exports the resilient package that can be used with resilient protectors. You can use the Basic authentication, Certificate authentication, and JWT authentication for encrypting and exporting the resilient package.

Warning: Do not modify the package that has been exported using the RPS Service API. If you modify the exported package, then the package will get corrupted.

The resilient package that has been exported using the Encrypted Resilient Package API is not FIPS-compliant.

Base URL
https://<ESA IP address or Hostname>/pty/v1/rps
Path
/export
Method
GET
CURL request syntax
Export API
curl -H "Authorization: Bearer <TOKEN>" -X GET https://<ESA IP address or Hostname>/pty/v1/rps/export/<fingerprint>?version=1\&coreVersion=1 -H "Content-Type: application/json" -o rps.json
In this command, TOKEN indicates the JWT token used for authenticating the API.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.
Query Parameters
fingerprint
Specify the fingerprint of the Data Store Export Key. The fingerprint is used to identify which Data Store to export and which export key to use for protecting the resilient package. The user with the Security Officer permissions must share the fingerprint of the Export Key with the user who is executing this API.

version

Set the schema version of the exported resilient package that is supported by the specific protector.

coreVersion

Set the Core policy schema version that is supported by the specific protector.
Sample CURL request
Export API
curl -H "Authorization: Bearer $<TOKEN>" -X GET https://<ESA IP address or Hostname>/pty/v1/rps/export/a7fdbc0cccc954e00920a4520787f0a08488db8e0f77f95aa534c5f80477c03a?version=1\&coreVersion=1 -H "Content-Type: application/json" -o rps.json

This sample request uses the JWT token authentication.

Sample response
The rps.json file is exported using the public key associated with the specified fingerprint.

Protect the encrypted resilient package with standard file permissions to ensure that only the dedicated protectors can access the package.

Exporting Resilient Package Using POST Method (Deprecated)

Note: The POST method of the Export API has been deprecated. A DevOps user can use this API with any public-private key pair of their choosing. Instead of the POST method, it is recommended to use the GET method for exporting a protected resilient package.
If you want to disable this API, contact Protegrity Support.

This API request exports the resilient package that can be used with resilient protectors. You can use the Basic authentication, Certificate authentication, and JWT authentication for encrypting and exporting the resilient package.

Warning: Do not modify the package that has been exported using the RPS Service API. If you modify the exported package, then the package will get corrupted.

The resilient package that has been exported using the Encrypted Resilient Package API is not FIPS-compliant.

Base URL
https://<ESA IP address or Hostname>/pty/v1/rps
Path
/export
Method
POST
CURL request syntax
Export API - KEK
curl -H "Authorization: Bearer <TOKEN>" -X POST https://<ESA IP address or Hostname>/pty/v1/rps/export\?version=1\&coreVersion=1 -H "Content-Type: application/json" --data '{
    "kek":{
"publicKey":{
"label": "<Key_name>",
"algorithm": "<RSA_Algorithm>",
"value": "<Value of publickey>"
}
}' -o rps.json
In this command, TOKEN indicates the JWT token used for authenticating the API.
For more information about creating a JWT token, refer to the section Generating JWT for REST APIs.

Note: You can download the resilient package only from the IP address that is part of the allowed servers list connected to a Data Store. This is only applicable for the 10.0.x and 10.1.0 protectors.

Query parameters
version
Set the schema version of the exported resilient package that is supported by the specific protector.

coreVersion

Set the Core policy schema version that is supported by the specific protector.
Request body elements
Encryption Method
The kek encryption can be used to protect the exported file.
Encryption MethodSub-elementsDescription
kek\publicKeylabelName of the publicKey.
algorithmThe RPS API supports the following algorithms:
  • RSA_OAEP_SHA1
  • RSA_OAEP_SHA256
  • RSA_OAEP_SHA512
  • RSA_PKCS1_v1_5
valueSpecify the value of the publicKey.
Sample CURL request
Export API - KEK
curl -H "Authorization: Bearer $<TOKEN>" -X POST https://<ESA IP address or Hostname>/pty/v1/rps/export\?version=1\&coreVersion=1 -H "Content-Type: application/json" --data '{
    "kek":{
"publicKey":{
"label": "key_name",
"algorithm": "RSA_OAEP_SHA256",
"value": "-----BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1eq9vH5Dq8pwPqOSqB0YdY6ehBRNWCgYhh9z1X093id+42eTRDHMOpLXRLhOMdgOeeyEsue1s5ZEOKY9j2TcaVTRwLhSMfacjugfiknnUESziUi9mt+XFnSgk7n4t5EF7fjvriOQvHCp24xCbtwKQlOT3x4zUs/REyJ8FXSrFEvrzbb/mEFfYhp2J6c90CKYqbDX6SFW8WjphDb/kgqg/KfT8AlsllAnci4CZ+7u0Iw7GsRvEvrVUCbBsXfB7InTst3hTc4A7iiY36kSEn78mXtfLjWiMpzEBxOteohmXKgSAynI7nI8c0ZhHSoZLUSJ2IQUi25ho8uxd/v3fedTTD91zRTxMJKw8XDrwjXllH7FGgsWBUenkO2lRlfIYBDctjv1MB+QJlNo+gOTGg8sJ1czBm20VQHHcyHpCKNu2gKzqWqSU6iGcwGXPCKY8/yEpNyPVFS/i7GAp10jO+QdOBskPviiLFN5kMh05ZGBpyNvfAQantwGv15Ip0RJ3LTQbKE62DAGNcdP6rizwm9SSt0WcG58OenBX5eB0gWBRrZI5s3EkhThYXyxbvFWObMWb/3jMsE+O22NvqAxWSasPR1zS1WBf25ush3v6BGBO4Frl5kBRrTCSSfAZBDha5VqXOqR1XIdQKf8wKn5DSScpMRuyf3ymRGQf915CC7zwp0CAwEAAQ==-----END PUBLIC KEY-----"}
}
}' -o rps.json

This sample request uses the JWT token authentication.

Sample response
The rps.json file is exported.

Protect the encrypted resilient package with standard file permissions to ensure that only the dedicated protectors can access the package.

6 - Using the Authentication and Token Management REST APIs

Explains the usage of the Authentication and Token Management APIs with some generic samples.

The Authentication and Token Management API uses the v2 version.

If you want to perform common operations using the Authentication and Token REST API, then refer the section Using the Common REST API Endpoints.

The following table provides section references that explain usage of some of the Authentication and Token REST APIs. It includes sample examples to work with the Authentication and Token functions. If you want to view all the Authentication and Token APIs, then use the /doc API to retrieve the API specification.

CategoryREST API
Token ManagementGenerate token
Refresh token
Roles and Permissions ManagementList all permissions
List all roles
Update roles
Create new role
Delete roles
User ManagementCreate user endpoint
Fetch users
Update user endpoint
Fetch user by ID
Delete user endpoint
Update user password endpoint
Group ManagementFetch groups
Create group endpoint
Update group endpoint
Delete group endpoint
SAML SSO ConfigurationList SAML providers
Create SAML provider endpoint
Get SAML provider
Update SAML provider endpoint
Delete SAML provider endpoint

Token Management

The following section lists the commonly used APIs to manage tokens.

Generate token

This API explains how you can generate an access token for authenticating the APIs.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/login/token
Method
POST

Request Body

  • loginname: User name for authentication.
  • password: Password for authentication.

Result This API returns JWT access token in the response header and the refresh token in the response body. You can use the refresh token in the Refresh token API to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/login/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'loginname=<User name>&password=<Password>!'

The login name and password are default for the MVP.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": 0,
  "data": {
    "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCcZQ",
    "expiresIn": 1800,
    "refreshExpiresIn": 1800
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:30:53 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1NiIsInR4YRUw 
 strict-transport-security: max-age=31536000; includeSubDomains

Refresh token

This API explains how to refresh an access token using the refresh token.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/login/refresh
Method
POST

Request Body

  • refreshToken: Refresh token for getting a new access token.

Result This API returns a new JWT access token in the response header and a new refresh token in the response body. You can use this refresh token to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/login/token/refresh' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCINGFeZEf8hw"
}
'

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": 0,
  "data": {
    "refreshToken": "MSkVFZiRl3Jkwi0uJQ",
    "expiresIn": 1800,
    "refreshExpiresIn": 1799
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:36:28 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1Nim95VHqh00vHfr8ip9RhyO-4FcxQ 
 strict-transport-security: max-age=31536000; includeSubDomains

Roles and Permissions Management

The following section lists the commonly used APIs for managing user roles and permissions.

List all permissions

This API lists all the permissions that are applicable to the user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/permissions
Method
GET

Request Body No parameters.

Result This API returns a list of all the permissions available for the logged in user.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/permissions' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "id": "faf70fd8-1c6d-4209-b64a-e9db37bbf58b",
    "name": "keycloak_viewer",
    "description": "Keycloak Viewer",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "b0ae18f9-fb85-4b1e-86fe-51b9f0fd8e53",
    "name": "cli_admin",
    "description": "Command Line Admin",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "cfb4d416-85f2-4b5b-a7d9-95bedfb5c57f",
    "name": "can_access_ap",
    "description": "Permission to access application",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "f03fcfcd-0aa9-4fcb-862f-01227f093516",
    "name": "can_create_token",
    "description": "Can Create JWT Token",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "ab434af4-8a49-430b-8306-9089744cd37c",
    "name": "keycloak_manager",
    "description": "Keycloak Manager",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "46142cfb-be47-4936-b399-7afcb4eea2cc",
    "name": "web_viewer",
    "description": "Appliance web viewer",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "1ced685a-7a02-4820-84bd-1dafa6273e13",
    "name": "uma_protection",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "f0a84500-e19a-4be2-a712-b01cc94b448d",
    "name": "can_proxy_ap",
    "description": "Proxy for a an application",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "efe391ed-032e-494e-ac62-20368cb4e41e",
    "name": "can_export_certificates",
    "description": "Can download protector certificates",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "43e7648d-49a8-4813-bf86-3d5bf31bfe7c",
    "name": "Shell_Accounts",
    "description": "Accounts that have cli access",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "0bb2cd71-01c4-4634-b77f-2d65dcdb5e8e",
    "name": "can_login_web",
    "description": "Web Login Permission",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "ce93275f-5cd2-4905-8237-89f4dbf2cc48",
    "name": "web_admin",
    "description": "Appliance web manager",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "e70d3988-4dfe-4411-b6df-c2181eb16b03",
    "name": "security_officer",
    "description": "Security Officer",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "aee1f91e-08fa-4c14-94ad-1d3b1cf08d4b",
    "name": "nfa_insight",
    "description": "Access to Insights and Insight Dashboard",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  },
  {
    "id": "28f7ad8b-1d7c-49e0-95c8-6bde2a4bfba5",
    "name": "can_fetch_package",
    "description": "Can download resilient packages",
    "composite": false,
    "clientRole": true,
    "containerId": "a09679da-b559-4856-8d29-6d39aa6485a1"
  }
]

List all roles

This API lists all the roles applicable to the user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/roles
Method
GET

Request Body No parameters.

Result This API returns a list of all the roles available for the logged in user.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "name": "directory_admin",
    "description": "Directory Administrator",
    "composite": true,
    "permissions": [
      "keycloak_manager"
    ]
  },
  {
    "name": "policy_proxy_user",
    "description": "Policy Proxy User",
    "composite": true,
    "permissions": [
      "can_proxy_ap"
    ]
  },
  {
    "name": "security_viewer",
    "description": "Security Administrator Viewer",
    "composite": true,
    "permissions": [
      "keycloak_viewer",
      "can_login_web"
    ]
  },
  {
    "name": "policy_user",
    "description": "Policy User",
    "composite": true,
    "permissions": [
      "can_access_ap"
    ]
  },
  {
    "name": "security_admin",
    "description": "Security Administrator",
    "composite": true,
    "permissions": [
      "cli_admin",
      "can_create_token",
      "web_admin",
      "keycloak_manager",
      "security_officer",
      "eclipse_insight",
      "can_fetch_package",
      "can_export_certificates"
    ]
  }
]

Update role

This API enables you to update an existing role and its permissions.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/roles
Method
PUT

Request Body

  • name: Role name.
  • description: Description of the role.
  • permissions: List of permissions that need to be updated for the existing role.

Result This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "updated"
}

Create role

This API enables you to create a role.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/roles
Method
POST

Request Body

  • name: Role name.
  • description: Description of the role.
  • permissions: List of permissions that need to created for the existing role.

Result This API creates a roles with the requested permissions.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "created"
}

Delete role

This API enables you to delete a role.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/roles
Method
DELETE

Request Body

  • name: Role name.

Result This API deletes the specific role.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "admin"
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "deleted"
}

User Management

The following section lists the commonly used APIs for managing users.

Create user endpoint

This API enables you to create a user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users
Method
POST

Request Body

  • username: Name of the user. This is a mandatory field
  • email: Email of the user.
  • firstName: First name of the user.
  • lastName: Last name of the user.
  • enabled: Enable the user.
  • password: Password for the user.
  • roles: Roles to be assigned to the user.
  • groups: Groups in which the user is included.

Result This API creates a user with a unique user ID.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "alpha",
  "email": "alpha@example.com",
  "firstName": "Alpha",
  "lastName": "User",
  "enabled": true,
  "password": "StrongPassword123!",
  "roles": [
    "directory_admin"
  ]
  
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha"
}

Fetch users

This API enables you to retrieve the user details.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users
Method
GET

Request Body No parameters.

Query Parameters

  • max: Maximum number of entries that can retrieved.
  • first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result This API retrieves a list of users.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users?max=100&first=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "username": "admin",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "enabled": true,
    "id": "71c573a0-7412-475d-be67-4bf6fdf71404",
    "createdTimestamp": null,
    "attributes": null,
    "emailVerified": true
  },
  {
    "username": "alpha",
    "email": "alpha@example.com",
    "firstName": "Alpha",
    "lastName": "User",
    "enabled": true,
    "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
    "createdTimestamp": 1760643896108,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "dfuser",
    "email": null,
    "firstName": "se",
    "lastName": "se",
    "enabled": false,
    "id": "12770ab4-d3a0-4243-8018-5bb1fb0d06d7",
    "createdTimestamp": 1760425034931,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "fds",
    "email": null,
    "firstName": "dsf",
    "lastName": "fs",
    "enabled": false,
    "id": "a1251ca4-664d-469a-b1c1-539fe8c73a9d",
    "createdTimestamp": 1760425052196,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "shiva",
    "email": "shiva.v@protegrity.com",
    "firstName": "shiva",
    "lastName": "v",
    "enabled": true,
    "id": "0743b449-c050-4e49-ba95-974cd2069a84",
    "createdTimestamp": 1760433609089,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser1",
    "email": null,
    "firstName": "t",
    "lastName": "tes",
    "enabled": true,
    "id": "948c1484-45d7-4df9-aea4-9534ca2d1923",
    "createdTimestamp": 1760424968139,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser2",
    "email": null,
    "firstName": "sdf",
    "lastName": "df",
    "enabled": true,
    "id": "d4961126-d324-4166-97e6-2fac1f40566a",
    "createdTimestamp": 1760425012482,
    "attributes": null,
    "emailVerified": false
  }
]

Update user endpoint

This API enables you to update the details of an user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users
Method
PUT

Request Body

  • id: ID of the user. This is a mandatory field
  • email: Email of the user.
  • firstName: First name of the user.
  • lastName: Last name of the user.
  • enabled: Enable the user.
  • password: Password for the user.
  • roles: Roles to be assigned to the user.
  • groups: Groups in which the user is included.

Result This API updates the user details.

Sample Request

curl -X 'PUT' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "email": "alpha@example.com",
  "firstName": "lpha",
  "lastName": "User",
  "enabled": true,
  "roles": [
    "directory_admin"
  ]
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Fetch User by Id

This API enables you to fetch the details of a specific user by specifying the user ID.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users/{user_id}
Method
GET

Request Body No parameters.

Path Parameters

  • user_id: Unique ID of the user. This is a mandatory field.

Result This API retrieves the details of the specific user.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha",
  "firstName": "lpha",
  "lastName": "User",
  "email": "alpha@example.com",
  "emailVerified": false,
  "enabled": true,
  "createdTimestamp": 1760643896108,
  "groups": [],
  "roles": [
    "directory_admin"
  ]
}

Delete user endpoint

This API enables you to delete a user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users
Method
DELETE

Request Body No parameters.

Path Parameters

  • user_id: Unique ID of the user. This is a mandatory field.

Result This API deletes the specified user.

Sample Request

curl -X 'DELETE' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>'
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Update user password endpoint

This API enables you to update the password of an existing user.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/users/password
Method
PUT

Request Body

  • userId: Unique ID of the user. This is a mandatory field.
  • newPassword: New password for the user..
  • temporary: Specifies whether the password is temporary and must be changed on next login.

Result This API creates a roles with the requested permissions.

Sample Request

curl -X 'PUT' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/users/password' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "newPassword": "NewStrongPassword123!",
  "temporary": false
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "password_updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "temporary": false
}

Group Management

The following section lists the commonly used APIs for managing groups.

Fetch groups

This API enables you retrieve a list of all the groups.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/groups
Method
GET

Request Body No parameters.

Query Parameters

  • max: Maximum number of entries that can be retrieved.
  • first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result This API a list of the available groups.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/groups?max=100&first=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[ { “id”: “aee4c370-4e97-4b55-a072-0840fe83a2aa”, “name”: “developers”, “description”: “”, “members”: [ “testuser1”, “testuser2” ], “roles”: [] } ]

Create group endpoint

This API enables you create a group.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/groups
Method
POST

Request Body

  • name: Name of the group. This is a mandatory field.
  • description: Description of the group.
  • members: List of user names that need to be added as members.
  • roles: List of role names that need to be assigned to the group.

Result This API creates a group with the specified members and roles.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/groups' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "developers",
  "description": "",
  "members": [
    "testuser1",
    "testuser2"
  ],
  "roles": [
    "service_admin",
    "user_manager"
  ]
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “group_id”: “aee4c370-4e97-4b55-a072-0840fe83a2aa”, “name”: “developers”, “status”: “created”, “members_added”: 2, “roles_assigned”: 2 }

Update group endpoint

This API enables you update an existing group.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/groups
Method
PUT

Request Body

  • group_id: Unique ID of the group. This is a mandatory field.
  • members: Members added to the group.
  • roles: Roles assigned to the group.

Result This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/groups' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "group_id": "group-uuid",
  "members": [
    "testuser2"
  ],
  "roles": [
    "service_admin"
  ]
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “status”: “updated”, “group_id”: “group-uuid”, “members_updated”: 1, “roles_updated”: 1 }

Delete group end point

This API enables you to delete an existing group.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/groups/{group_id}
Method
DELETE

Request Body No parameters.

Path Parameters

  • group_id: ID of the group that needs to be deleted. This is a mandatory field.

Result This API deletes the specified group.

Sample Request

curl -X 'DELETE' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/groups/aee4c370-4e97-4b55-a072-0840fe83a2aa' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "group_id": "aee4c370-4e97-4b55-a072-0840fe83a2aa"
}

SAML SSO Configuration

The following section lists the commonly used APIs for managing SAML providers.

List SAML providers

This API enables you to list the existing SAML providers.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/saml/providers
Method
GET

Request Body No parameters

Result This API retrieves a list of the existing SAML providers.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/saml/providers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
{
  "alias": "azuread",
  "displayName": "Protegrity SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": false,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "encryptionAlgorithm": "RSA-OAEP",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://nfa.aws.protegrity.com/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
},
{
  "alias": "azured",
  "displayName": "Protegrity 2 SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "guiOrder": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "signingCertificate": "MIIC8DCCAdigAwIBAgIQf++2tyNO+YtIpa4MDh1hiQcoVX",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://nfa.aws.protegrity.com/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
}
]

Create SAML provider endpoint

This API enables you to create a SAML provider configuration.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/auth/saml/providers
Method
POST

Request Body

  • alias: Unique alias for the SAML provider. This is a mandatory field.
  • displayName: Display name for the SAML provider that will appear on the login page. This is a mandatory field.
  • configType: Configuration type, either metadata URL or metadata file content. This is a mandatory field.
  • metadataUrl: URL to fetch the SAML metadata from the identity provider. For example, https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml.
  • metadataFileContent: SAML metadata XML content as a string. For example, <?xml version=\"1.0\"?>...</EntityDescriptor>.
  • signingCertificate: X.509 certificate for signing SAML requests. Use the PEM format without the headers.
  • nameIdPolicyFormat: NameID policy format for SAML authentication. For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
  • forceAuthn: Force re-authentication of the user even if the user is already authenticated.
  • validateSignature: Validate the SAML response and assertion signatures.
  • wantAssertionsSigned: Require the SAML assertions to be signed.
  • wantAssertionsEncrypted: Require the SAML assertions to be encrypted.
  • signatureAlgorithm: Signature algorithm for SAML requests. For example, RSA_SHA256.
  • attributeMapping: Mapping of SAML attributes to user attributes.
  • enabled: Enable or disable the SAML provider.

For details of the each parameter, refer the documentation for the corresponding SAML provider.

Result This API enables you to add a SAML provider.

Sample Request

curl -X 'POST' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/saml/providers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "alias": "test-azure-ad-saml",
  "displayName": "Test Azure AD SAML",
  "configType": "metadataUrl",
  "metadataUrl": "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "metadataFileContent": "<?xml version=\"1.0\"?>...</EntityDescriptor>",
  "signingCertificate": "MIIDXTCCAkWgAwIBAgIJAL...",
  "nameIdPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
  "forceAuthn": false,
  "validateSignature": true,
  "wantAssertionsSigned": true,
  "wantAssertionsEncrypted": false,
  "signatureAlgorithm": "RSA_SHA256",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  },
  "enabled": true
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “status”: “created”, “alias”: “test-azure-ad-saml”, “configType”: “metadataUrl”, “message”: “SAML provider created successfully from metadata” }

Get SAML provider

This API enables you retrieve the details of a specific SAML provider.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/saml/providers/{alias}
Method
GET

Request Body No parameters.

Path Parameters

  • alias: Alias of the SAML provider. This is a mandatory field.

Result This API retrieves the details about the specific SAML provider.

Sample Request

curl -X 'GET' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/saml/providers/azure-ad-saml' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "alias": "azure-ad-saml",
  "displayName": "Azure AD SAML",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "additionalProp1": {}
  }
}

Update SAML provider endpoint

This API enables you update the configurations of an existing SAML provider.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/saml/providers/{alias}
Method
PUT

Request Body No parameters.

Path Parameters

  • alias: Alias of the SAML provider that you want to update. This is a mandatory field.

Result This API updates the existing SAML provider.

Sample Request

curl -X 'PUT' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/saml/providers/azure-ad-sampl' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "Azure AD SAML Updated",
  "configType": "metadataUrl",
  "metadataUrl": "https://login.microsoftonline.com/new-tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "metadataFileContent": "string",
  "signingCertificate": "string",
  "nameIdPolicyFormat": "string",
  "forceAuthn": true,
  "validateSignature": true,
  "wantAssertionsSigned": true,
  "wantAssertionsEncrypted": true,
  "signatureAlgorithm": "string",
  "attributeMapping": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "enabled": true
}'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “status”: “updated”, “alias”: “azure-ad-saml” }

Delete SAML provider endpoint

This API enables you to delete the configuration of an existing SAML provider.

Base URL
https://{NFA IP address or Hostname}/pty/v1
Path
/saml/providers/{alias}
Method
DELETE

Request Body No parameters.

Path Parameters

  • alias: Alias of the SAML provider that you want to delete. This is a mandatory field.

Result This API deletes the SAML provider.

Sample Request

curl -X 'DELETE' \
  'https://nfa.aws.protegrity.com/pty/v1/auth/saml/providers/azure-ad-saml' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

This sample request uses the access token for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "alias": "azure-ad-saml"
}