REST API on

Policy Users

Mon, 01 Jan 0001 00:00:00 +0000

Policy Users

Protegrity Policy roles defines the unique data access privileges for every member. The protector function protects the data with the username sent in either the JWT-formatted authorization header, the request body or service user in the environment variables.

The protector function behavior can be set in the cloud function environment variables as described in Install Protect Function via Terraform Scripts

Authorization/allow_assume_user	0	1
Empty	User from the request body. / (Throw an error).	User from the request body.
JWT	User from JWT payload	User from request body. If not found user from JWT payload.

Note

The service_user will always take priority over any other user in the payload or in the JWT header.

JWT Verification

Mon, 01 Jan 0001 00:00:00 +0000

JWT Verification

Cloud Protect function can authenticate JWTs with an OpenID endpoint or a stored certificate/secret.

The protector must be able to reach specified OpenID endpoint to obtain the public key when OpenID settings are enabled. The retrieved key is used to verify the signature. Several additional claims are verified against the configuration provided to the protect function when OpenID is enabled: issuer, audience, appid (optional).

Availability of an OpenID endpoint from the protector may not be feasible or a non-OpenID issuer may be in use. In those cases, a stored certificate/secret may be used to validate the jwt signature by enabling jwt_verify and including a base64 encoded certificate/secret in jwt_secret_base64 configuration. Additional claims are not verified.

Authorization Header

Mon, 01 Jan 0001 00:00:00 +0000

Authorization Header

Allowing unauthenticated HTTP function invocation on Google Cloud protector function.

The Protect function will validate the JWT in the Authorization header.

Authenticating for invocation on Google Cloud protector function. All requests to the protector function will need to send the Google JWT in the Authorization header.

When PTY_GCP_JWT_HEADER is not set or it is false the Protect function will validate the JWT in the Authorization header.

When PTY_GCP_JWT_HEADER = true the Protect function will validate the JWT in the X-PTY-Authorization header.

Export an OpenAPI Spec

Mon, 01 Jan 0001 00:00:00 +0000

Export an OpenAPI Spec

Once the Cloud API on GCP is installed, you can export the OpenAPI documentation file from:

{base url}/pty/v1/openapi

Authentication and Authorization configurations are enforced on the openapi endpoint URL.

Tip

To get the base url, login to Google Cloud console. Navigate to the Protect Cloud Function details and to the TRIGGER tab.

For testing the REST API, we recommend using a client tool, such as Postman.

v1 Specification

Mon, 01 Jan 0001 00:00:00 +0000

Request

AWS Lambda service limits maximum size of payload to 6 MB. Client applications of Protegrity Cloud API must ensure their payload size is within this limit. This applies to all types of requests described below.

Performs a policy operation such as protect, unprotect, or reprotect.

URI

/v1/protect or /v1/unprotect or /v1/reprotect
Method

POST
Parameters

data: Input data to the policy operation.

data_element: Data element to use for the policy operation.

Legacy Specification

Mon, 01 Jan 0001 00:00:00 +0000

Protegrity has multiple products with REST API capabilities, such as Protection Server (out of support), DSG, and the latest product - IAP REST. Each one has its use case. To help you move to cloud-native implementation, Cloud Product REST API supports legacy payload.

Request

Performs a policy operation such as protect, unprotect, or reprotect.

Method

POST
Parameters

dataelementname: (protect/unprotect) Data element to use for the policy operation.

externaliv: (protect/unprotect) Optional, external initialization vector.

HTTP Status Codes

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Status Codes

The following table explains the different HTTP Status Codes with their corresponding response.

Status Codes

Response

Description

200

{"results":["<string>","<string>"],
 "success": true, "encoding":[hex|utf8]}

Success protected data is in results and success attribute is true

400

{
 "error_msg": "<string>",
 "success": false
}

There was an issue in the request, success is false, check error_msg attribute. For more information check the logs

SSL Certificates

Mon, 01 Jan 0001 00:00:00 +0000

SSL Certificates

By default, the Google Cloud Functions support HTTPS.

Google Cloud Function HTTPS endpoint have TLS 1.0, TLS 1.1, TLS 1.2 and TLS1.3 enabled.

For more information on HTTPS setting on Google Cloud HTTP Functions, refer to Security levels

Mon, 01 Jan 0001 00:00:00 +0000

OpenID

Verification example using openid_* configuration parameters:

Navigate to the cloud function main.tf configuration file, and find the section Parameters applicable when openid_enabled = true
Edit/replace the entries as indicated below, then save and apply the configuration:

Parameter	Value	Notes
openid_enabled	true
openid_audiences	Audience as it would appear in the aud claim, for example “https://management.azure.com/"	Can be either one value or comma separated list.
openid_issuers	Issuer as it would appear in the iss claim, for example “https://sts.windows.net/bca3157d-b8d9-4ca8-a724-1c7e2b96e1ef"	Can be either one value or comma separated list.
openid_appid	Appid as it would appear in the appid claim, for example “9ada3e7d-4ec4-48da-9d69-5379b7984fe1”	Optional. If value is “”, appid claim is ignored. When openid_appid is provided, it must match the appid claim of the token.

Mon, 01 Jan 0001 00:00:00 +0000

Request

Performs a policy operation such as protect, unprotect, or reprotect.

URI

/v1/protect or /v1/unprotect or /v1/reprotect
Method

POST
Parameters

data: Input data to the policy operation.

data_element: Data element to use for the policy operation.

encoding: Optional, encoding of the data. One of: base64, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.

external_iv: Optional, external initialization vector.

old_data_element: (reprotect) Data element for unprotecting the input.

Mon, 01 Jan 0001 00:00:00 +0000

Request

Performs a policy operation such as protect, unprotect, or reprotect.

Method

POST
Parameters

dataelementname: (protect/unprotect) Data element to use for the policy operation.

externaliv: (protect/unprotect) Optional, external initialization vector.

newdataelementname: (reprotect) Data element to use for the output.

newexternaliv: (reprotect) Optional, external initialization vector for the output.

olddataelementname: (reprotect) Data element to use for the input.

oldexternaliv: (reprotect) Optional, external initialization vector for the input.

policyusername: User performing the operation.

Mon, 01 Jan 0001 00:00:00 +0000

Response

responsePayloadV1:
type: object
 properties:
 success:
 type: bool
 error_msg:
 type: string
 description: When success is false, error_msg is included
 results:
 type: array
 items:
 type: string

Example success:

{
 "encoding": "utf8", 
 "results":["str1","str2"], 
 "success": true
}

If the request was successful, the success flag will always be true.

Example failure:

{
 "error_msg": "token expired", 
 "success": false
}

If the request fails, the success flag will always be false.

Multi Data Elements Support Payload

responsePayloadV2:
type: object
 properties:
 success:
 type: boolean
 results:
 type: array
 items:
 type: object
 properties:
 success:
 type: bool
 error_msg:
 type: string
 description: When success is false, error_msg is included
 id:
 type: string
 description: When id is sent in the request payload, id is included in the response
 results:
 type: array
 items:
 type: string

Example success:

Mon, 01 Jan 0001 00:00:00 +0000

Response

Example:

{"protect":{"bulk":{"returntype":"success","data":[{"returntype":"success","message":"Data
 protection was successful.","content":"RGZBUFR4ODAzejFwNjQ5TWg0TEFpcFNqbA=="},{"returntype":"success",
"message":"Data protection was successful.","content":"aHNnVVB5QWFDYw=="}]}}}

Mon, 01 Jan 0001 00:00:00 +0000

Secret

Stored secret verification example using jwt_verify and jwt_secret_base64 configurations:

Navigate to the cloud function main.tf configuration file, and find the section Parameters applicable when authorization = jwt
Edit/replace the entries as indicated below, then save and apply the configuration:

Parameter	Value	Notes
authorization	JWT
jwt_verify	1
jwt_secret_base64	Secret in base64 encoding. For example, the value of the public key is as follows.