Azure on

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

Agent Function Outbound IP address

Agent Function App IP addresses may be useful for configuring ESA policy store and allowing traffic between Agent and ESA.

Note

Add IP addresses in the ESA network inbound port rules.
Add the list of IPs to Policy data store in ESA

To obtain the list of Outbound IP addresses:

From Azure console navigate to Function App, select the Agent Function App.
Select Settings > Networking.
Under Outbound traffic configuration, select Show More next to Outbound addresses

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

Configure Function

Agent Function must be configured with parameters recorded in steps above.

To configure Function:

Open Function App service from the Azure console. Select the Function App created for policy agent in previous steps.
Navigate to Settings > Environment variables .
On the App Settings pane, click on Show values to reveal all configuration values
To modify multiple parameters, click the pencil icon Advanced edit at the top. Alternatively you may click on the environment variable name to edit single values.

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

Create Policy Encryption Key

Create a policy encryption key.

To create policy encryption key:

From Azure console, navigate to Key Vaults and select Key Vault created in Key Vault.
Under Objects, select Keys.
Click Generate/Import.
Specify the following:

a. Key name for the Name field.

b. RSA for Key type.

c. 2048 for RSA key size.

d. Set Enabled toggle to Yes.
Select Create.
Click on the key name after creation is complete, then click on the key identifier row under CURRENT VERSION.

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

Certificates on ESA

By default, ESA is configured with self-signed certificates, which can only be validated using self-signed CA certificate supplied in policy agent Cloud Function Environment variables configuration.

In case ESA is configured with publicly signed certificates, this section can be skipped since the agent function will use public CA to validate ESA certificates.

To obtain self-signed CA certificate from ESA:

Log in to ESA Web UI.
Select Settings > Network > Manage Certificates.

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

Creating ESA Credentials

Policy Agent Function requires ESA credentials to be provided as one of the two options:

Note

The username and password of the ESA user requires role with DPS Admin and Export Certificates permissions. Security Administrator is one of the predefined roles which contains the above permissions, however for separation of duties it is recommended to create custom role.

ESA Credentials In Azure Key Vault

Policy Agent Function uses Key Vault as secure store for sensitive information like ESA username and password.

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

ESA Credentials From Custom Azure Function App

Policy Agent Function requests ESA username and password from a custom Azure Function App, further referred to as ESA Credentials function. This method may be used to get the username and password from external vaults.

There are four options for configuring Policy Agent authorization with ESA Credentials function: Option 1, Option 2, Option 3 and Option 4. Only one option is expected to be configured at a time.

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

ESA Credentials In Azure Key Vault

Policy Agent Function uses Key Vault as secure store for sensitive information like ESA username and password.

Create ESA credentials secrets:

Navigate to Key Vault.
Under Objects, select Secrets > Generate/import.
Select Manual, then type in valid json as shown in the example for Secret value.
```
{"username": "<policy_export_user>", "password": "<password>"}
```
Select Create.
Navigate to the secret details in Key Vault by selecting the newly created secret.

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

ESA Server

Policy Agent function requires ESA server running and accessible from Agent Function App on TCP port 8443. Make sure inbound connections on TCP:8443 are allowed for the network where ESA is hosted. You can find the list of Agent Function Outbound IP addresses after you deploy the function in Agent Function Outbound IP address

Note down ESA IP to be accessed form Agent Function:

ESA IP Address (EsaIpAddress): ___________________

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

Install Agent via ARM template

Resources created with ARM template include Function App, Premium V3 App Service Plan (optional) and Application Insights service. Run Azure Resource Manager deployment.

Note

Refer to ARM Template Installation - Required Permissions for the list of IAM permissions required to deploy ARM template.

To install Agent via ARM template:

From Azure Console, select Create a resource, search for template and then select Template deployment > Create.

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

Agent Function Key Vault Access Policies

Agent Function requires access to Key Vault created in Key Vault to encrypt policy and to access configuration secrets.

From Azure console navigate to Key Vaults, select the Key Vault created in Key Vault.
Select Access policies.
Click Create.
Select the following permissions in Permissions tab: a. Get under Key Management Operations. b. Wrap Key under Cryptographic Operations. c. Get under Secret Permissions.
For Principal provide function identity a. For functions with user-assigned identity enter identity recorded in step Agent Function User-Assigned Managed Identity b. For functions with system-assigned identity enter function name recorded in step Install Agent via ARM template
Proceed Next to Application and Next again to Review + Create.
Review permissions and Create.

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

Function System-Assigned Managed Identity

System-assigned Azure managed identity is enabled if user-assigned managed identity is not used. User-assigned managed identities offer less frequent updates to Azure resources and allow for configuration of permissions ahead of function creation.

If you have not created a user-assigned managed identity at Agent Function User-Assigned Managed Identity, setup following role assignments for system-assigned managed identity:

Navigate to the function
Select Settings, Identity.
Confirm Status of system-assigned identity is already On on System Assigned tab

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

Test Agent Function Installation

After configuration is complete you can test the function.

To test Agent function installation:

Navigate to Overview.
Select the function agent from the Functions tab.
Click Code + Test > Test/Run and then Run to execute the function.
You should see a 202 Accepted response.
Expand Logs output at the bottom of the page. Click Maximize to enlarge log output.

Note
It may take 1-2 minutes for the logs to begin populating in the console. Logging in the console is best effort and it is possible for the logs to be cut off. Navigate to Application Insights for full logs.
Below is an example log output from successful agent run.

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

Troubleshooting

To review the most recent invocation traces, navigate to the function app instance. Select Monitoring > Logs from the menu on the left. Run the query traces in the query editor to retrieve the full history of executions with detailed traces.

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

Agent Function User-Assigned Managed Identity

User-assigned Azure managed identities are optional. If a user-assigned identity is not provided, a system-assigned managed identity will be enabled the function. User-assigned managed identities offer less frequent updates to Azure resources and allow for configuration of permissions ahead of function creation.

In the search box, enter Managed Identities. Under Services, select Managed Identities
Select Create
For Subscription provide recorded value of AzureSubscriptionID
For Resource Group provide recorded value of ApiResourceGroup

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

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.

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

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.

Permissions

Description

Built-In Azure Role

Microsoft.Insights/components/read

Microsoft.OperationalInsights/workspaces/read

Read access to monitoring data and settings

Monitoring Reader

Microsoft.Insights/components/write

Microsoft.OperationalInsights/workspaces/write

Write and manage access to monitoring data and settings

Monitoring Contributor

Microsoft.Web/serverFarms/write

Microsoft.Web/sites/write

Microsoft.Web/sites/host/listkeys/action

Microsoft.Web/serverFarms/join/action

Microsoft.Web/register/action

Write and manage access to web apps

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

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.

USERNAME_REGEX

User in the request

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

Audit Log Forwarding Architecture

Audit logs are by default sent to Azure Blob Storage and Application Insights. The Cloud Protect product can also be configured to send audit logs to ESA. Such configuration requires deploying audit Log Forwarder component which is available as part of Cloud Protect deployment bundle. The diagram below shows additional resources deployed with Log Forwarder component.

The audit log forwarding solution includes Azure Event Hubs data-streaming service and an Azure Function App deployment called Log Forwarder. Protect function delivers audit logs to Azure Event Hub instance, Event Hub instance batches audit logs and delivers them to Log Forwarder function. Log Forwarder function then delivers audit logs to ESA. Audit log aggregation occurs on both Protect and Log Forwarder functions. Aggregation rules are described in the Understanding the log aggregation section. If Log Forwarder cannot deliver audit logs to ESA due to temporary ESA connection loss, it will send undelivered audit logs to a dead-letter queue Event Hub. Audit logs in dead-letter queue Event Hub can be re-delivered to ESA using another instance of Log Forwarder, which can be configured to run either manually or on schedule.

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

The following sections provide installation steps for the Log Forwarder component in Azure. The Log Forwarder deployment allows for the audit logs generated by Protect Service to be delivered to ESA for auditing and governance purposes. Log Forwarder component is optional and is not required for the Protect Service to work properly. See Audit Log Forwarder Architecture for more information. Some of the installation steps are not required for the operation of the software but recommended for establishing a secure environment. Contact Protegrity for further guidance on configuration alternatives in the cloud.

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

Certificates on ESA

By default, ESA is configured with self-signed certificates, which can only be validated using self-signed CA certificate supplied in Log Forwarder configuration.

Note

Certificate Validation can be bypassed for testing purposes, see section: Install Log Forwarder via ARM template

In case ESA is configured with publicly signed certificates, this section can be skipped since the Log Forwarder will use public CA to validate ESA certificates.

To obtain self-signed CA certificate from ESA:

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

Create Key Vault Secrets

Log Forwarder uses Key Vault as a secure store for certificate key file.

Create secret in Key Vault for certificate key file:

Navigate to Key Vault.
Under Objects, select Secrets > Generate/import.
Select Manual, type in secret name and specify single-line certificate key file value for Secret value.
Select Create.
Record secret name:

ESA Client Cert Key Secret Name (EsaClientCertKeySecretName): ___________________

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

ESA Authentication

Audit Log Forwarder must authenticate with ESA using certificate-based authentication with client certificate and certificate key. Download the following certificates from the /etc/ksa/certificates/plug directory of the ESA:

client.key
client.pem

Both certificate and certificate key must be converted to single-line values using code similar to the following examples.

Client certificate (client.pem):

$folder = 'C:\Temp'
cd $folder
(Get-Content "$folder\client.pem") -join '\n' | Set-Content "$folder\one-liner-client.pem"
cat "$folder\one-liner-client.pem"

folder="/tmp"
cd "$folder"
awk 'NF {printf "%s\\n",$0}' "client.pem" > "one-liner-client.pem"
cat "one-liner-client.pem"

Client certificate key (client.key):

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

Install Log Forwarder via ARM template

Resources created with ARM template include Function App, App Service Plan and Application Insights service. Optionally, a new Event Hub namespace and Event Hub instance can be created.

Note

Refer to ARM Template Installation - Required Permissions for the list of IAM permissions required to deploy ARM template.

To install Log Forwarder via ARM template:

From Azure Console, select Create a resource, search for template and then select Template deployment > Create.

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

Update Function Key Vault Access Policies

The Key vault must be updated to allow the Function App to decrypt the policy files. The Forwarder is using policy to confirm the authenticity of audit logs it receives from Event Hub and to digitally sign the aggregated logs that it sends to ESA. Update the Key vault access policies with function identity. To update the key vault access policies:

From Azure console navigate to Key Vaults, select the Key Vault created in Key Vault.
Select Access policies.
Click Create.
Select the following permissions in Permissions tab: a. Get under Key Management Operations. b. Unwrap Key under Cryptographic Operations. c. Get under Secret Permissions.
Proceed Next to Principal.
For Principal provide function identity a. For functions with user-assigned identity enter identity recorded in step Function User-Assigned Managed Identity b. For functions with system-assigned identity enter function name recorded in step Install Log Forwarder via ARM template
Proceed Next to Application and Next again to Review + Create.
Review permissions and Create.

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

Function System-Assigned Managed Identity

If you have not created a user-assigned managed identity at Function User-Assigned Managed Identity, setup following role assignments for system-assigned managed identity:

Navigate to the function
Select Settings, Identity.
Confirm Status of system-assigned identity is already On on System Assigned tab

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

Test Full Log Forwarder Installation

Install and configure Protegrity Agent, Protect Service and Log Forwarder components.
Set EVENT_LEVEL environment variable on Protect Service function to Informational.
Set PTY_LOG_LEVEL environment variable on both Protect Service function and Log Forwarder function to config.

Test Installation

Make a protect operation using a data element or user which will result in audit log generation
Navigate to the Logs for the Protect Service function
Execute ’traces’ query

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

Test Log Forwarder Installation

Follow the steps to validate Log Forwarder installation. Successful Log Forwarder installation will aggregate logs, connect to ESA and send audit log events.

Testing in this section validates the connectivity between Log Forwarder and ESA. The sample policy included with the initial installation and test event below are not based on your ESA policy. Any logs forwarded to ESA which are not signed with a policy generated by your ESA will not be added to the audit store.

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

Troubleshooting

Configure additional logging for functions:

Set EVENT_LEVEL environment variable on Protect function to Informational.
Set PTY_LOG_LEVEL environment variable on both Protect function and Log Forwarder function to config.

Error

Detail


Unhandled exception. System.Exception: Failed to initialize 
function type,expecting environment variable 
'AzureWebJobs.AuditLogForwarder.Disabled' 
to be set to either 'true' or 'false'

An environment variable ‘AzureWebJobs.AuditLogForwarder.Disabled’ is expected. This environment variable is added automatically when functions are deployed with ARM templates.
Verify this environment variable exists and is set to ’true’ for Protect Service functions and is set to ‘false’ for Log Forwarder functions.


[2024/08/08 10:00:00] [error] [tls] error: unexpected EOF

Log Forwarder failed to verify ESA certificate

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

Update Policy Agent With Log Forwarder Function Target

Log Forwarder requires a Protegrity policy which is in sync with the Protector Service. This section will describe the steps to update the Policy Agent to include updating the Log Forwarder.

Note

If the Policy Agent has not been installed, follow the steps in Install Agent via ARM template. Set PROTEGRITY_PROTECT_FUNCTION to include both Protect Service function and Log Forwarder function.

Navigate to the Policy Agent function created in Install Agent via ARM template

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

Update Protect Service With Event Hub details

In this section, Event Hub details will be provided to the Protect Service installation.

Note

If the Protect function has not been installed yet, you may provide the ‘Event Hub Name’, ‘Event Hub Namespace’ during Protect Service installation and skip the remainder of this section.

Navigate to the Protect function environment variables.
Set EVENTHUB_NAME to the output value recorded in Install Log Forwarder via ARM template.

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

Function User-Assigned Managed Identity

In the search box, enter Managed Identities. Under Services, select Managed Identities
Select Create
For Subscription provide recorded value of AzureSubscriptionID
For Resource Group provide recorded value of ApiResourceGroup

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

Log Forwarder ARM Template Parameters

New Event Hub Namespace Sku Name and New Event Hub Namespace Sku Tier directly affect the quotas applied to new Event Hub instances. Review Azure Event Hub Quotas related to selected tier in Azure documentation: Azure Event Hub Quotas
New Event Hub Namespace Sku Capacity: Event Hubs throughput units for Basic or Standard tiers, where value should be 0 to 20 throughput units. The Event Hubs premium units for Premium tier, where value should be 0 to 10 premium units. Capacity directly controls the purchased throughput of Event Hub instance. Review details in Azure documentation: Event Hub Instance Throughput
New Event Hub Partition Count: The number of partitions represents the level of parallel log streams in the Event Hub. It is proportional to throughput capacity of the Event Hub instance. If the number of partitions is too low and the volume of audit logs is too high, a throughput ceiling may be reached on Event Hub and some audit records sent from protect function may be lost. Review details in Azure documentation: Event Hub Scalability
New Event Hub Audit Log Retention In Days: Number of days audit logs are to be available in Event Hub. Applies to both primary Event Hub instance and dead-letter queue Event Hub instance. While audit logs are processed by Log Forwarder in near-realtime, it may be beneficial to keep audit logs available in Event Hub for extended period in case Log Forwarder or ESA require maintenance.
Event Hub Name DLQ: Dead-letter Queue Event Hub name. This Event Hub will be used by Log Forwarder in case ESA is temporarily unavailable. Messages from DLQ Event Hub can be re-processed by another instance of Log Forwarder either manually or on schedule once ESA connectivity is restored.

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

Monitoring Log Forwarder Performance

Azure Event Hub Metrics: Any positive value in ‘Throttled Requests’ metric indicates that audit logs rate from protect function is too high. The recommended actions may include:
- Increase aggregation and batching intervals of Protect function by increasing values of PTY_CORE_FLUSHINTERVAL and MAX_WAIT_TIME
- Increase number of partitions for Event Hub
- Purchase additional capacity units for Event Hub
- Use a higher Event Hub namespace tier
Azure Event Hub Metrics for DLQ Event Hub: Any positive value in ‘Incoming Messages’ metric indicates that not all audit logs are being delivered to ESA. Review whether connection to ESA is set up in Audit Log Forwarder Installation

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

Log Forwarder Performance

Log forwarder architecture is optimized to minimize the amount of connections and reduce the overall network bandwidth required to send audit logs to ESA. This is achieved with batching and aggregation taking place on two levels.

The first level is in protect function instances, where audit logs from consecutive requests to an instance are batched and aggregated. The second level of batching takes place in Azure Event Hub instance where log records from different protect function instances are additionally batched and sent to log forwarder function where they are aggregated.

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

Protect Service Function Environment Variables

PTY_CORE_FLUSHINTERVAL: Defines for how long audit logs are aggregated before they are sent to Azure Event Hub. Default value is ten seconds. Audit logs are always aggregated into one minute buckets, therefore a value greater than sixty seconds will affect mostly the batching interval.
MAX_WAIT_TIME: Defines for how long aggregated audit logs are batched before they are sent to Azure Event Hub. Default value is ten seconds.

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

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

Feature	ESA 10.2	PPC (this guide)
Datastore Key Fingerprint	Optional/Recommended	Required
CA Certificate on Agent	Optional/Recommended	Optional/Recommended
CA Certificate on Log Forwarder	Optional/Recommended	Not supported
Client Certificate Authentication from Log Forwarder	Optional/Recommended	Not supported
IP Address	ESA IP address	PPC address

Prerequisites

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

Policy Agent Setup with PPC

Important

When connecting to PPC, the Policy Agent requires use of a datastore key fingerprint. For connecting to ESA 10.2 with Cloud Protect Policy Agent, the fingerprint is optional but recommended. See Policy Agent Installation for general setup steps.

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

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

Key Vault

Key Vault is required to store secrets and encrypt policy deployment package. Identify existing Key Vault or create new.

To create Key Vault:

From the Azure Console select Create a resource.
Navigate to Key Vault > Create.
Select a Resource group.
Enter a Key vault name.
Select a Region. For the best performance, use the same region for all resources.
Set the Pricing tier to Standard.
Under Access configuration, select Vault access policy as the Permission model.

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

Resource Group

Identify or create a new Azure Resource Group where the Protegrity solution will be installed. It is recommended that a new Resource group is created. This can provide greater security controls and help avoid conflicts with other applications that might impact regional account limits. An individual with the Cloud Administrator role will be required for some of the subsequent installation steps.

Azure Subscription ID (AzureSubscriptionID): ____________________

Azure Resource Group ID (ApiResourceGroupID): ___________________

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

Resource Group

Azure Subscription ID (AzureSubscriptionID): ____________________

Azure Resource Group ID (AzureResourceGroupID): ___________________

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

Function App Storage

Create Storage Account

Create a storage account to host Protegrity deployment packages provided in installation artifact bundle. Note that turning on the firewall or restricting access to selected virtual networks or IP address ranges will require additional configuration and is beyond the scope of this document.

To create Function App storage:

From the Azure Console select Create a resource.
Navigate to Storage account > Create.
Select the Resource group where the Protegrity solution will be deployed.

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

Create Agent Policy Blob Container

The Agent function uploads an encrypted policy zip package to a blob container which is used as a staging storage. Create the policy staging container

To prepare the policy blob container:

Under Storage account created in previous step, select Data storage > Containers and click + Container .
Type in a container name and click Create .

Agent Policy Blob Container Name (AgentPolicyBlobContainer): ___________________

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

Create Protect Function Policy Blob

Create a blob container for encrypted Protegrity security policy using Azure Blob Service. Agent will store encrypted policy in this container. Both Protect and Log Forwarder functions will load policy from this container.

Go Storage Account created in the previous step.
Under Data storage section, select Containers and click + Container .
Type in container name and click Create .
Right-click the container name, and select Container properties to obtain URL.

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

Create Storage Account

To create Function App storage:

From the Azure Console select Create a resource.
Navigate to Storage account > Create.
Select the Resource group where the Protegrity solution will be deployed.

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

Upload Files

Create a deployment container using the Azure Blob Service.

Go Storage Account created in the previous step.
Under Data storage section, select Containers and click + Container .
Type in container name and click Create .
Upload the following installation artifacts to the container:

protegrity-protect-azure-<version>.zip
protegrity-agent-azure-<version>.zip

Important

The installation bundle you receive from Protegrity should be unzipped to reveal the files above. Only the files above need to be uploaded to the storage container. Do not unzip the three individual zip packages.

Record Protect function blob URL:

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

Azure Services

The following table describes the Azure services that may be part of your Protegrity installation.

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

Service

Description

Microsoft Entra ID Application

Allows authentication with Azure Function app

Azure Managed Identity

Allows functions assume user-defined managed identity

Function App

Provides serverless compute for Protegrity protection operations and ESA integration to fetch policy updates or deliver audit logs.

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

Preparation

Ensure that all the steps in Pre-Configuration are performed.
Login to the Azure account console where Protegrity will be installed.
Ensure the Azure Resource Manager templates provided by Protegrity are available on your local computer.

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

Register an Entra ID App

A Microsoft Entra ID App provides the mechanism for Client to authenticate with the Function App instance. Creating an Entra ID app requires appropriate permissions to the Azure Subscription and is typically performed by the Azure Account Administrator.

To register an Entra ID App:

In the Azure portal navigate to Microsoft Entra ID.
Click + Add and select App registration.
Enter a Name and select Accounts in any organizational directory.

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

Function System-Assigned Managed Identity

If you have not created a user-assigned managed identity at Protect Function User-Assigned Managed Identity, setup following role assignments for system-assigned managed identity:

Navigate to the function
Select Settings, Identity.
Confirm Status of system-assigned identity is already On on System Assigned tab

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

Troubleshooting

To review live requests, navigate to Application Insights service and select item with the same name as the protect function. Under Investigate, select Live Metrics. Wait for the dashboard to load, then go to Sample Telemetry pane on the right and look for the requests in question.

To review the full history of requests from Application Insights under Monitoring select Logs:

Select the Tables tab.
Hover over one of the table names under Application Insights header, for example exceptions.
Click on See preview data.
Click Use in editor.

You can also run the query directly in the query editor. For instance to select the 10 latest exceptions run the following query.

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

Update Key Vault Access Policies

The Key vault must be updated to allow the Function App to decrypt the policy files. Azure assigns a unique identifier to each Function App instance that can be used to grant permissions to that instance. Update the Key vault access policies with the Protect function. To update the key vault access policies:

Obtain Function App identifier

Navigate to the Function App service in the Azure portal.

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

Upload the Sample Policy

The Protegrity installation bundle contains a sample policy which can be used to test the protect service installation without an ESA. Upload the sample policy artifact to the policy Blob storage container:

Go to Azure console and select Storage Account Name (StorageAccountName) recorded in step Create Storage Account.
Under Data storage select Blob Containers and select container created in Protect Function Policy Blob Container
Click Upload and select protegrity-sample-policy-<version>.zip file from your local computer.

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

Protect Function User-Assigned Managed Identity

In the search box, enter Managed Identities. Under Services, select Managed Identities
Select Create
For Subscription provide recorded value of AzureSubscriptionID
For Resource Group provide recorded value of ApiResourceGroup

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

Disable Agent Policy Deployment and Test Policy Agent Function

Policy agent generates a backup of pulled policy when triggered. The policy will then be deployed to Protect and Log Forwarder functions. Deployment of policies to functions should be disabled during the upgrade process.

Follow the steps below to disable policy deployment:

From Azure Console, navigate to Policy Agent Function App
Navigate to Settings > Environment variables.
set DISABLE_DEPLOY to 1 if it is not already set.

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

Disable Protegrity Agent Function Timer Trigger

App Function Timer Trigger is used to periodically run Protegrity Agent Function to synchronize policy from ESA. The trigger must be disabled temporarily for the time of the upgrade process.

Follow the steps below to disable the Agent Function Timer Trigger.

From Azure Console, go to Function App service and select Protegrity Agent Function.
Navigate to Overview.
The functions list should contain agent function with Trigger type Timer and status Enabled.

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

Upload Deployment Artifacts

You can download the latest version of the deployment package from https://my.protegrity.com. Navigate to Data Protection > Cloud Protect to download the latest version.

After downloading the deployment package from the Protegrity Portal, go to Azure console. Navigate to the storage account that was previously created to upload deployment artifacts (see: Agent Policy Blob Container).

Upload the following artifacts to the Azure storage container:

protegrity-protect-<version>.zip
protegrity-agent-<version>.zip

After upload is complete, note the blob url for each file. Blob URL may be found in the blob properties.

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

Re-enable Policy Agent Deployment Setting

Skip this step if changes were not made to the DISABLE_DEPLOY setting in previous upgrade steps

Navigate to Agent function Settings > Environment variables
Set DISABLE_DEPLOY to 0.
apply changes and restart the Agent Function App

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

Enable Protegrity Agent Function Timer Trigger

If the Agent Function Timer Trigger was disabled at the beginning of the upgrade process, you must re-enabled it. Follow the steps below to enable Policy Agent Timer Trigger.

Navigate back to Protegrity Agent Function.
Select Overview.
Click on the three dots in the same row as the agent function in the list of functions. Then select Enable.

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

Test/Run Policy Agent Function to Generate Latest Policy

Follow the steps below to run the upgraded policy agent to refresh latest backup policy. Record the latest backup policy URL for later upgrade steps.

Note

Policy will not be deployed to Protectors when agent DISABLE_DEPLOY is set to 1 as described in Disable Agent Policy Deployment and Test Policy Agent Function.

From Azure Console, navigate to the Policy Agent Function App

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

Upgrading Policy Agent Function

Note

If the release version of the artifact zip file has not changed since the previous installation, you can skip the Agent Function upgrade.

Important

If Policy Agent version is less than version 4, a new installation must be created. Carefully observe the below points:

Create a new Container in the Storage Account for policy storage for the installation, as the version 4 policy package differs from version 3.
To prevent overwriting production environment policies with incompatible policy package, follow Disable Protegrity Agent Function Timer Trigger after deploying the new function with arm template. Do not add the production Protect or Forwarder functions to the PROTEGRITY_PROTECT_FUNCTION environment variable of new Policy Agent until the trigger is disabled
Skip to Disable Agent Policy Deployment and Test Policy Agent Function once installation is complete.

Upgrade Policy Agent Runtime Package

From Azure console, navigate to Function App service and select agent function app. Navigate to Settings > Environment variables.

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

Enable Protegrity Agent Function Timer Trigger

If the Agent Function Timer Trigger was disabled at the beginning of the upgrade process, you must re-enabled it. Follow the steps below to enable Policy Agent Timer Trigger.

Navigate back to Protegrity Agent Function.
Select Overview.
Click on the three dots in the same row as the agent function in the list of functions. Then select Enable.

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

Re-enable Policy Agent Deployment Setting

Skip this step if changes were not made to the DISABLE_DEPLOY setting in previous upgrade steps

Navigate to Agent function Settings > Environment variables
Set DISABLE_DEPLOY to 0.
apply changes and restart the Agent Function App

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

Finalize Log Forwarder Upgrade

Upgraded Log Forwarder Function will be swapped into production deployment slot to serve production traffic and re-enabled,

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

Re-Enable Log Forwarder Function Trigger

Go to your main Log Forwarder Function.
Navigate to environment variable settings Settings > Environment variables
Click on AzureWebJobs.AuditLogForwarder.Disabled configuration entry.
Replace value with false. Click Apply then Apply and Confirm to finalize.

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

Swap Upgraded Function Slot to Production

Go to your main Log Forwarder Function.
Select deployment slots.
Select Swap.
Select staging Log Forwarder Function slot as source and current Function as target.
Click Start Swap and wait until the functions are swapped.
If you need to rollback, swap the application slots again.

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

Upgrading Log Forwarder Function

Note

If the release version of the artifact zip file has not changed since the previous installation, you can skip the Log Forwarder upgrade.

Important

Upgrading the Log Forwarder component to version 4 from versions <3.2, or versions of 3.2 which use shared access key for loading the source, requires a new installation

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

Disable Log Forwarder Event Hub Trigger

Disabling the Event Hub trigger will prevent audit log delivery during the upgrade process. This reduces the chance for any duplicate or lost audit logs. Later steps will indicate when this trigger may be re-enabled.

Follow the steps below to disable the Event Hub trigger:

From Azure Console, go to Function App service and select Protegrity Log Forwarder Function.
Navigate to Overview.
The functions list should contain AuditLogForwarder function with Trigger type Event Hub and Status Enabled.

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

Create Staging Deployment Slot (Log Forwarder)

Creating new deployment slot allows updating the function such that it may easily be rolled back. Log Forwarder Function will be disabled during the upgrade process. Logs generated during this time will be processed once Log Forwarder is re-enabled

From Azure console, navigate to Function App service and select the Log Forwarder Function App to upgrade. Navigate to Deployments > Deployment Slots.
Click Add slot. Specify slot name.

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

Upgrading Protect Function

Note

If the release version of the artifact zip file has not changed since the previous installation, you can skip the Protect Function upgrade.

Important

Upgrading the Protector component to version 4 from versions <3.2, or versions of 3.2 which use shared access key for loading the source, requires a new installation

Diagram below illustrates upgrade steps.

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

Create Staging Deployment Slot (Protector)

Creating new deployment slot allows updating the function without interruptions to the existing traffic.

From Azure console, navigate to Function App service and select the Protect Function App to upgrade. Navigate to Deployments > Deployment Slots.
Click Add slot. Specify slot name.
Click Add. Wait for the slot to be created.
After the slot is added, select Close to close the dialog box.
There should be a new slot available in the list of deployment slots. You will use this deployment slot as staging for the upgraded function. After upgrade is done and tested, you will swap staging slot with production slot.

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

Load Production Policy and Test New Protect Function In Staging

Navigate to the new staging Protect function Settings > Environment variables
Set AZURE_POLICY_BLOB_URL environment variable to the upgraded_agent_policy_blob_url value recorded in previous steps.
Start/Stop the protect function.
Test New Protect Function in staging. You can use curl command below, replacing Staging Protect Function URL and Staging Protect Function Default Host Key with values recorded in previous section.

curl -X POST "<Staging Protect Function URL>/api/Protect" -k \
-H 'sf-custom-X-Protegrity-HCoP-Rules: {"jsonpaths":[{"op_type":"unprotect","data_element":"alpha"}]}' \
-H 'sf-context-current-user: test' \
-H 'sf-external-function-current-query-id: test-id' \
-H 'x-functions-key: <Staging Protect Function Default Host Key>' \
-H 'Content-Type: application/json' \
-d '{
 "data": [
 ["0", "UtfVk UHgcD!"]
 ]
}'

curl -X POST "<Protect Function URL>/api/v1/protect" -k \
-H 'x-functions-key: <Protect Function app key>' \
-H 'Content-Type: application/json' \
-d '{
 "data": ["test"],
 "user": "test",
 "data_element": "test"
}'

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

Finalize Protector upgrade

Upgraded Protect Function can now be swapped in to production deployment slot to serve production traffic.

Go to your main Protect Function.
Select deployment slots.
Select Swap.
Select staging Protect Function slot as source and production Function as target.
Click swap and wait until the functions are swapped.
If you need to rollback swap the application slots again.