Appendices

• 1: Integrating Cloud Protect with PPC (Protegrity Provisioned Cluster)
• 2: Configuring Regular Expression to Extract Policy Username
• 3: Getting JWT for Service Account in Azure Active Directory
• 4: Protection Methods
• 5: ARM Template Installation - Required Permissions
• 6: Associating ESA Data Store With Cloud Protect Agent

1 - Integrating Cloud Protect with PPC (Protegrity Provisioned Cluster)

This guide describes how to configure the Protegrity Policy Agent and Log Forwarder to connect to a Protegrity Provisioned Cluster (PPC), highlighting the differences from connecting to ESA.

Key Differences: PPC vs ESA

Prerequisites

• Access to PPC and required credentials.
• Tools: curl, kubectl installed.

Policy Agent Setup with PPC

Follow these instructions as a guide for understanding specific inputs for Policy Agent integrating with PPC:

1. Obtain the Datastore Key Fingerprint

   To retrieve the fingerprint for your Policy Agent:

   curl -k -H "Authorization: Bearer ${TOKEN}" -X POST https://${HOST}/pty/v2/pim/datastores/1/export/keys  -H "Content-Type: application/json" --data '{
     "algorithm": "RSA-OAEP-256",
     "description": "example-key-from-kms",
     "pem": "-----BEGIN PUBLIC KEY-----\nABC123... ...890XYZ\n-----END PUBLIC KEY-----"
   }'
   

   Sample Output:

   {"uid":"1","algorithm":"RSA-OAEP-256","fingerprint":"4c:46:d8:05:35:2e:eb:39:4d:39:8e:6f:28:c3:ab:d3:bc:9e:7a:cb:95:cb:b1:8e:b5:90:21:0f:d3:2c:0b:27","description":"example-key-from-kms"}
   

   Record the fingerprint and configure it as the value for PTY_DATASTORE_KEY in the Policy Agent function environment variable.

2. Retrieve the PPC CA Certificate

   To obtain the CA certificate from PPC:

   kubectl -n api-gateway get secret ingress-certificate-secret -o jsonpath='{.data.ca\.crt}' | base64 -d > CA.pem
   

   Use the CA.pem that was returned as described in Policy Agent Installation.

3. Configure the PPC Address

   Use the PPC fqdn in place of the ESA IP address wherever required in your configuration.

Log Forwarder Setup with PPC

• The Log Forwarder will proceed without certificates and will print a warning if PTY_ESA_CA_SERVER_CERT is not provided.
• No additional certificate or CA configuration is needed for PPC.

2 - Configuring Regular Expression to Extract Policy Username

Configuring Regular Expression to Extract Policy Username

Cloud Protect Function exposes USERNAME_REGEX configuration to allow extraction of policy username from user in the request.

• USERNAME_REGEX Function Environment configuration

  The USERNAME_REGEX environment variable can be set to contain regular expression with one capturing group. This group is used to extract the username. Examples below show different regular expression values and the resulting policy user.

^(.*)[@/].*$

3 - Getting JWT for Service Account in Azure Active Directory

Getting JWT for Service Account in Azure Active Directory

Protect Function App can use Microsoft identity platform endpoint for identity-as-a-service, available in Azure Active Directory, to implement OpenID Connect and OAuth 2.0 authorization. This section describes how to get JWT using OAuth 2.0 client credentials grant flow in Azure Active Directory and authorize the Client ID in Protegrity Policy.

Suggested reading: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow

High-level design:

1. Active Directory Admin creates App registration for the service account.
2. Active Directory Admin gives consent for the Service Account App ID.
3. Daemon uses the Service Account App ID and the Service Account App ID Secret or Certificate, Protect Function App ID as the scope, and gets back the Access Token (JWT).
4. Daemon sends the request to the Protect Function App, including the access token in the Authorization Bearer header.

Configure the Protect Function App:

1. From the Azure console, navigate to Function App service and select protect function app.

2. Navigate to Settings > Environment variables and click OPENID_ENABLED. Make sure it is set to true.

3. Click on OPENID_AUDIENCES, make sure it is set to the App ID recorded in EntraIDApplicationID.

4. Click or Add the authorization environment variable. Make sure it is set to jwt.

5. Click or Add on jwt_user_claim environment variable, make sure it is set to [“azp”, “appid”]. For more information on claims on AAD access token, refer:

   https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens

To register a Service Account:

1. In the Azure portal navigate to Azure Active Directory.

2. Under Manage, select App registrations > New registration.

3. Enter a Name and select Accounts in any organizational directory.

4. Redirect URI is set to http://localhost.

5. Select Register.

   After registration is complete record Application ID and Directory (tenant) ID displayed in the overview window:

   Service Account App ID: ___________________

   Directory (tenant) ID: ___________________

6. In the Azure portal, in App registrations, select your application.

7. Select Certificates & secrets > New client secret.

8. Add a description for your client secret.

9. Select a duration.

10. Click Add.

11. Record the secret’s value for use in your client application code. This secret value is never displayed again after you leave this page.

    Service Account App Secret: ___________________

For more information on app registration, see Azure documentation Quickstart Registering App

Admin Consent the Service Account:

https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={Service Account App ID}
&state=12345
&redirect_uri=http://localhost

Replace the tenant and the Service Account App ID with the values recorded in the previous step. At this point, Azure AD enforces that only a tenant administrator can sign into complete the request. The administrator will be asked to approve all the direct application permissions that were requested for the app in the app registration portal.

Get the access token

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id={Service Account App ID}&scope={EntraIDApplicationID }%2F.default&client_secret={Service Account App Secret}&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'

Replace Service Account App ID, EntraIDApplicationID, Service Account App Secret, and tenant with values recorded in previous steps.

Example for successful response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

\

Record the access_token from the response. access_token: ___________________

Use the token

curl -X POST "https://<Protect hostname>/api/v1/protect" -k \
-H 'x-functions-key: <Protect Function app key>' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "data": ["hello world!"],
  "data_element": "alpha"
}'

Replace the {Protect hostname}, {Protect Function app key} and {access_token} with the.

Troubleshooting:

• Service Account App ID redirect URL matches the redirect URL in the request for admin consent.
• Active Directory administrator does admin consent.
• JWT aud claim is the same as OPENID_AUDIENCES.
• JWT iss claim is the same as OPENID_ISSUERS.
• Protect Function configuration authorization=JWT
• At least one of thejwt_user_claim exists in the JWT
• The user claim in the token has permissions to make protect request.
• The data element exists in the Protect Function App current policy.
• JWT is not expired

4 - Protection Methods

Protection Methods

For more information about the protection methods supported by Protegrity, refer to the Protection Methods Reference.

5 - ARM Template Installation - Required Permissions

ARM Template Installation - Required Permissions

Permissions below are required to install Protegrity service using ARM template.

All permissions in the table must be granted with the Resource group scope.

Microsoft.Insights/components/read

Microsoft.OperationalInsights/workspaces/read

Microsoft.Insights/components/write

Microsoft.OperationalInsights/workspaces/write

Microsoft.Web/serverFarms/write

Microsoft.Web/sites/write

Microsoft.Web/sites/host/listkeys/action

Microsoft.Web/serverFarms/join/action

Microsoft.Web/register/action

Microsoft.ManagedIdentity/userAssignedIdentities/assign/action

Microsoft.ManagedIdentity/userAssignedIdentities/read

Microsoft.Resources/deployments/validate/action

Microsoft.Resources/deployments/write

Microsoft.Resources/deployments/operationStatuses/read

Microsoft.Resources/deployments/read

Log Forwarder service ARM deployment requires additional permissions below:

Microsoft.EventHub/namespaces/write

Microsoft.EventHub/namespaces/eventhubs/write

Microsoft.EventHub/namespaces/networkrulesets/write

Microsoft.EventHub/namespaces/read

The additional permissions listed below are required when API management is part of the deployment.

Microsoft.ApiManagement/service/write

Microsoft.ApiManagement/service/apis/write

Microsoft.ApiManagement/service/diagnostics/write

Microsoft.ApiManagement/service/apis/operations/write

Microsoft.ApiManagement/service/apis/operations/policies/write

Microsoft.ApiManagement/service/backends/write

Microsoft.ApiManagement/service/loggers/write

Microsoft.ApiManagement/service/policies/write

Microsoft.ApiManagement/service/apis/diagnostics/write

Microsoft.ApiManagement/service/read

Microsoft.ApiManagement/service/operationResults/read

6 - Associating ESA Data Store With Cloud Protect Agent

Associating ESA Data Store With Cloud Protect Agent

ESA controls which policy is deployed to protector using concept of data store. A data store may contain a list of IP addresses identifying servers allowed to pull the policy associated with that specific data store. Data store may also be defined as default data store, which allows any server to pull the policy, provided it does not belong to any other data stores. Node registration occurs when the policy server (in this case the policy agent) makes a policy request to ESA, where the agent’s IP address is identified by ESA.

Policy agent function source IP address used for node registration on ESA depends on ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP and the PTY_ADDIPADDRESSHEADER configuration exposed by the agent function.

The function service uses multiple network interfaces, internal network interface with ephemeral IP range of 169.254.x.x and external network interface with IP range described in Function app outbound IP addresses section under function configuration. By default, when agent function is contacting ESA to register node for policy download, ESA uses agent function outbound IP address. This default behavior is caused by the default ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP=false and agent default configuration PTY_ADDIPADDRESSHEADER=yes.

In some cases, when there is a proxy server between the ESA and agent function, the desirable ESA configuration is ASSIGN_DATASTORE_USING_NODE_IP=true. and PTY_ADDIPADDRESSHEADER=no which will cause the ESA to use proxy server IP address.

The table below shows how the hubcontroller and agent settings will affect node IP registration on ESA.