Protect Service Installation

Preparation

1. Ensure that all the steps in Pre-Configuration are performed.

2. Login to the Azure account console where Protegrity will be installed.

3. Ensure the Azure Resource Manager templates provided by Protegrity are available on your local computer.

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:

1. In the Azure portal navigate to Microsoft Entra ID.

2. Click + Add and select App registration.

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

4. Leave the Redirect URI empty and select Register.

5. After registration is complete record the application name and application id displayed in the overview window.

   Entra ID Application Name (EntraIDApplicationName): ___________________

   Entra ID Application ID (EntraIDApplicationID): ___________________

Protect 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.

1. In the search box, enter Managed Identities. Under Services, select Managed Identities

2. Select Create

3. For Subscription provide recorded value of AzureSubscriptionID

4. For Resource Group provide recorded value of ApiResourceGroup

5. For Region provide recorded value of ApiRegion

6. For Name provide a name of the new identity

7. Assign following roles to this identity:

   • Storage Blob Data Owner
   • Monitoring Metrics Publisher
   • Azure Event Hubs Data Sender: required only if function is sending logs to ESA

8. Record Protect function user-assigned identity

   Protect Function User-Assigned Identity (ProtectFuncUserAssignedIdentity): ____________________

Install Protect Function via Azure Resource Manager

Resources created with the ARM template include API Management service, Function App, App Service Plan and Application Insights service.

To install protect function via Azure Resource Manager:

1. From Azure Console, select Create a resource, search for template then select Template deployment (deploy using custom templates) > Create.

2. Select Build your own template in the editor.

3. Click Load File and upload pty_protect_arm_v2.json, then click Save.

4. Select a Resource group.

5. Enter a Name for the resources. All resources will be prefixed with Protegrity-Protect except for log container which will be prefixed with ptylogs. For more information on naming rules see: Azure resource name rules.

6. For Location input specify Azure region name or leave default to deploy in the same region as resource group.

7. For Storage Account Blob Service Url Optionally use the value recorded in Create Storage Account. If value is not given, it will be automatically derived from Protect Function Blob Url.

8. For Protect Function Blob Url use the value from Upload Files.

9. For Function App Managed Identity Optionally use the value from Protect Function User-Assigned Managed Identity. If value is not given, a system-assigned managed identity will be enabled.

10. For Function Sku either EP1 or EP3 are recommended. Note that this will affect the running cost.

11. For Create Api Management Service select Do not create. API Management Service is required only for integration with Snowflake. This service is not required otherwise.

12. For Api Management Service Sku Applicable only when API Management Service is created. Skip this if API Management Service is not created. Either Consumption (if available) or Premium are recommended. Note that this will affect the running cost.

13. For Username Regex you can optionally specify regex to extract policy username from the request. See Configuring Regular Expression to Extract Policy Username for more details.

14. For Entra ID Application ID enter the value recorded in Register an Entra ID App.

15. For Forward Logs To ESA select whether audit logs are to be sent to ESA or not. If you are not planning on sending audit logs to ESA you can skip Event Hub Nameand Event Hub Namespace properties below. For details on creating and configuring Event Hubs see Audit Log Forwarder Installation

16. For Event Hub Name provide the name of Event Hub which will be used to send audit logs to ESA.

17. For Event Hub Namespace provide the name of Event Hub Namespace which is hosting Event Hub selected in previous step.

18. Under Review + create, click Create. Wait for all resources to deploy. If the deployment fails for any resources of type Microsoft.Web/sites/host/functionKeys then click Redeploy and try deploying again.

19. After deployment is complete, go to Outputs and record protectFunctionName, azureTenantId and apiGatewayUrl.

    Protect Function Name (ProtectFuncName): __________________

    Azure Tenant ID (AzureTenantID): __________________

    API Gateway URL (ApiGatewayURL): __________________

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 Protect Function User-Assigned Managed Identity, setup following role assignments for system-assigned managed identity:

1. Navigate to the function

2. Select Settings, Identity.

3. Confirm Status of system-assigned identity is already On on System Assigned tab

4. Click on Azure role assignments button.

5. Assign following roles to this identity:

   • Storage Blob Data Owner
   • Monitoring Metrics Publisher
   • Azure Event Hubs Data Sender: required only if function is sending logs to ESA

6. From Azure console, navigate to Function App and select protect function deployed in previous section.

7. Select Overview and click Restart button. Wait until function restart completes.

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

1. Navigate to the Function App service in the Azure portal.

2. Select the newly created Protect Function App instance.

3. Select the Identity option under Settings.

4. Ensure that setting System assigned is set to Status On.

5. Record the Object ID:

   Protect Function Object ID: ___________________

Update the Key vault access policies with the Protect function’s Object ID

1. From Azure console navigate to Key Vaults, select the Key Vault created in Key Vault.
2. Select Access policies.
3. Click Create.
4. Select the following permissions in Permissions tab: a. Get under Key Management Operations. b. Unwrap Key under Cryptographic Operations. c. Get under Secret Permissions.
5. Proceed Next to Principal.
6. Enter the Protect Function Object ID recorded in this section into the search field.
7. Select the Function App instance.
8. Proceed Next to Application and Next again to Review + Create.
9. Review permissions and Create.

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:

1. Go to Azure console and select Storage Account Name (StorageAccountName) recorded in step Create Storage Account.

2. Under Data storage select Blob Containers and select container created in Protect Function Policy Blob Container

3. Click Upload and select protegrity-sample-policy-<version>.zip file from your local computer.

4. Click Upload and wait for the file to complete uploading.

5. Record the sample policy blob url:

   Sample Policy Blob Url (SamplePolicyBlobUrl): ___________________

Test the Protect Function Installation

Before continuing with next steps, you may verify the protect service is installed correctly. This step is optional and can be skipped.

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

2. Select Overview and record URL value as <Protect Function URL>.

3. Navigate to Settings > Environment variables and click OPENID_ENABLED.

4. Change value to false and click Apply.

5. Select or create variable AZURE_POLICY_BLOB_URL.

6. Set value of AZURE_POLICY_BLOB_URL to value recorded for SamplePolicyBlobUrl and click Apply.

7. Select Apply and Confirm to finalize setting changes.

8. Go to Functions > App keys and record the value of default key under Host Keys (All functions) as <Protect Function app key>.

9. Run the following CURL command to test Function deployment.

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

   Note

   When you copy-paste the curl command, make sure each header is in a separate line.

10. Replace <Protect Function URL> and <Protect Function app key> with the values recorded in step 2 And 5.

11. Run curl command. Verify the following output.

    {"data":["hello world!"], "success": true, "encoding": "utf8"}
    

12. Go back to Function app. Select Settings > Environment variables and click OPENID_ENABLED,

13. Change value to true and click Apply. Select Apply and Confirm to finalize.

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:

1. Select the Tables tab.
2. Hover over one of the table names under Application Insights header, for example exceptions.
3. Click on See preview data.
4. 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.

exceptions 
| where timestamp > ago(24h)
| order by timestamp
| limit 10

Protect Function App Configuration

Protect Function app can be customized using environment variables. From Azure console, navigate to Function App service and select protect function app. Navigate to Settings > Environment variables. Add or Edit environment variables based on the following information.