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:

   1. Retrieve public key from the Cloud Provider Key Management service for the policy encryption key created in pre-configuration:

      • AWS
      • Azure
      • GCP
      1. Navigate to the Key Management Service in AWS console and open Customer Managed Keys
      2. Select the desired key
      3. Select the Public Key tab
      4. Select Download

      1. Navigate to the Key Vault in Azure console and open Objects>Keys
      2. Select the desired key
      3. Select the key indicated as CURRENT VERSION
      4. Select Download public key

      1. Navigate to Key Management in GCP console
      2. Select the desired key and open the Versions tab
      3. Select Get public key from the Actions column menu
      4. Select Download

   2. Escape the new line characters in the downloaded public key for use in the next step - for example:

      awk 'NF {printf "%s\\n",$0}' "<public_key_file>" > "new-line-escaped-public-key.pem"
      cat new-line-escaped-public-key.pem
      

   3. Export key fingerprint using the PPC API as indicated in the curl example below:

      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-key-management",
        "pem": "<value of new-line-escaped-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"}
      

      Note

      Alternatively, set using the PPC CLI utility. See the export key example in Create Datastores Key

   4. Record the value for fingerprint and configure the Policy Agent:

      • AWS
      • Azure
      • GCP

      Set the environment variable PTY_DATASTORE_KEY in the Policy Agent Lambda function to the fingerprint value.

      Set the environment variable PTY_DATASTORE_KEY in the Policy Agent Function App to the fingerprint value.

      Set the variable in Policy Agent main.tf pty_datastore_key to the fingerprint value and apply the changes.

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 ProtegrityCA.pem that was returned as described in Policy Agent Installation.

3. Configure the PPC Address

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

   Note

   Use FQDN as described in the PPC Rest API documentation

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.