This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Cloud API Configuration

Configure Cloud API for tokenization service required by the Protegrity Browser Protector extension.

Configuring Cloud API for Protegrity Browser Protector

The Protegrity Browser Protector relies on a serverless REST API tokenization service provided by the Protegrity Cloud API. This section outlines the essential configuration steps for enabling JWT authentication in the Cloud API.

For more information about the Cloud API on AWS, refer to the Cloud API on AWS Guide 3.2.1.

Fetch Available Public Keys from the Azure AD OpenID Configuration Endpoint

  1. The public keys for JWT authentication can be retrieved by calling the Azure AD OpenID configuration endpoint:

    https://login.microsoftonline.com/{tenant_id}/discovery/keys?appid={client_id}
    • Replace {tenant_id} with your Azure AD tenant ID.
    • Replace {client_id} with your app registration’s client ID.

  2. Use a Python script or another method to fetch the public keys.

    • Example Python script to fetch and print public keys:
         import argparse
   import jwt  
   import base64 
   import requests
   from cryptography.hazmat.primitives import serialization

   parser = argparse.ArgumentParser(
                     prog='JWK To PEM converter',
                     description='Helper program to download and convert public keys.',
                     epilog='Protegrity')

   parser.add_argument('tenant')   
   parser.add_argument('-c', '--client', help="appid for the Azure client application to narrow down keys result") 
   args = parser.parse_args()

   jwks_uri = f'https://login.microsoftonline.com/{args.tenant}/discovery/keys'
   if args.client:
      jwks_uri += f"?appid={args.client}"
   jwks_response = requests.get(jwks_uri)  

   if jwks_response.status_code != 200:
      print(f"Azure Entra request error: {jwks_response.text}")
      exit()

   for key in jwks_response.json()['keys']:
      public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)  
      public_pem = public_key.public_bytes(  
         encoding=serialization.Encoding.PEM,  
         format=serialization.PublicFormat.SubjectPublicKeyInfo  
      )  
      print(f"-----------Key Id: {key['kid']}--------------")
      print(f"{base64.encodebytes(public_pem).decode('utf-8').replace('\n', '')}\n")
    • Run python3.12 ./tools/jwk_to_pem.py app_registration_tenant_id -c app_registration_client_id
      • Replace app_registration_tenant_id and app_registration_client_id with values recorded in Entra ID Configuration section.
      • Install pyjwt==.10.1 Python library before running the script.

  3. Record PEM base64 formatted keys required by the Cloud API configuration.

  • The script will print multiple public keys with their corresponding key Ids. Refer to example output below.

       -----------Key Id: CNv0AB3RwqlHFEVnaoMAshCH2XE--------------
   LS0tLS1CRUdJTiBQV...S0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==

   -----------Key Id: PoVKeBDIOvmTyLQ9G9BenBwos7k--------------
   LS0tLS1CRUdJTiBQV...KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==

   -----------Key Id: _jNwjBDnvTTK8XEdr5QUPkBRLLo--------------
   LS0tLS1CRUdJTiBQV...QUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==

  • Record the the output for the next step.

Retrieve JWT Public Signing Key

Microsoft Azure AD maintains multiple public signing keys to ensures continuity in token validation during key transitions.

Follow the steps below to find the active signing key used for the Entra ID app registration configured in Entra ID Configuration section.

  1. Set Cloud API Log Level to config:

    • Update your Cloud API configuration to set the log level to config.
    • This enables detailed logging, which will display the JWT token in the logs for debugging purposes.

    Set the log level back to its original value after debugging to avoid exposing sensitive information.

  2. Retrieve the JWT Token from Logs:

    • Trigger the API call that generates the error.
    • Check the Cloud API CloudWatch logs to locate the JWT token. It will typically appear in the request logs.

  3. Decode the JWT Token:

    • Use a tool like jwt.ms or any other JWT decoding tool to inspect the token.
    • Copy and paste the token into the decoding tool.
    • The decoded JWT header will look something like this:
      {  
  "alg": "RS256",  
  "typ": "JWT",  
  "kid": "exampleKeyId123"  
}
    • Note the kid value, for example, "exampleKeyId123". This identifies the public key used to sign the token.
    • Match the kid with the Key Id from step 1. Record the corresponding base64 value, for example, LS0tLS1CRUdJTiBQV…QUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==: jwt_signing_key: <>

    Microsoft may update or maintain the Azure AD service, which can involve replacing signing keys as part of operational processes. When public signing keys change, the Cloud API returns HTTP error 403 - Invalid JWT token. Verification failed.. which manifests as Protector service unavailable error in browser extension.

Cloud API Configuration for JWT Authentication

Please use the appropriate link below depending on the cloud provider in use.

1 - Configuration for AWS

Enable JWT Authentication in Cloud API Configuration for AWS.

When deploying the Cloud API on AWS using CloudFormation, ensure that JWT authentication is properly configured by setting the following parameters:

CloudFormation Parameters:

  1. Set authorization to jwt:

    • This specifies that JWT authentication will be used to secure the API.

  2. Set jwt_verify to 1:

    • Enables verification of the JWT token during API requests.

  3. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

  4. Set jwt_user_claim to upn or email:

    • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Obtain the API Gateway Endpoint

After deploying the Cloud API using CloudFormation, retrieve the API Gateway endpoint URL for the service:

  1. Navigate to the CloudFormation stack in your AWS Management Console.
  2. Locate the Outputs section of the deployed stack.
  3. Find the output parameter labeled ApiGatewayId.
  4. Use the ApiGatewayId and your AWS region to construct the endpoint URL for the Protegrity Cloud API:
    • Format: https://{ApiGatewayId}.execute-api.{Region}.amazonaws.com/pty
    • Example: If ApiGatewayId is abc123xyz and the region is us-east-1, the service endpoint URL will be:
    https://abc123xyz.execute-api.us-east-1.amazonaws.com/pty
  5. Record this endpoint URL for use in the Browser Protector configuration.
    • protector_endpoint_url: <>

Disable IAM Authentication for the /v1/unprotect Endpoint

By default, AWS API Gateway might enforce IAM authentication for API methods. Since authentication is already handled within the Cloud API protect Lambda function, IAM authentication for the /v1/unprotect endpoint must be disabled.

  1. Navigate to the API Gateway:
    Open the AWS Management Console and go to the API Gateway service.

  2. Locate the API Gateway:
    Find the API Gateway deployed for the Cloud API (use the ApiGatewayId obtained in Step 4).

  3. Select the /v1/unprotect Resource:
    Locate the /v1/unprotect resource in the API Gateway.

  4. Choose the POST Method:
    Under Method Execution, select the POST method.

  5. Set Authorization to None:
    In the Method Request settings, set Authorization to None.

  6. Save the Changes:
    Confirm and save the changes.

2 - Configuration for GCP

Enable JWT Authentication in Cloud API Configuration for GCP.

When deploying the Cloud API on GCP, ensure that JWT authentication is properly configured by setting the following parameters:

Cloud Function Parameters (Can be set in terraform template or by GCP UI):

  1. Set authorization to jwt:

    • This specifies that JWT authentication will be used to secure the API.

  2. Set jwt_verify to 1:

    • Enables verification of the JWT token during API requests.

  3. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

  4. Set jwt_user_claim to upn or email:

    • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Configure GCP cloud protect function Authentication security setting:

By default, GCP cloud function might enforce IAM authentication for API methods. Since authentication is already handled within the Cloud API protect function, we can change the authentication setting to “allow for public access” as below:

  1. Navigate to the GCP cloud protect function
  2. On the service details screen, select the security tab
  3. In the Authentication section - ensure “allow public access” is selected.

Obtain the Gateway URL:

After deploying the Cloud API using terraform, retrieve the API endpoint URL for the service:

From Google Cloud Management console,

  1. Navigate to API Gateway.
  2. Select the deployed API Gateway instance.
  3. Under the “Gateway Details” section, copy the “Gateway URL” or “Managed Service URL”.
  4. Record the displayed URL for use in the Browser Protector configuration.
    • protector_endpoint_url: <>

example: https://{gateway-id}-{hash}.{region}.gateway.dev/api

3 - Configuration for Azure

Enable JWT Authentication in Cloud API Configuration for Azure.

Ensure that JWT authentication is properly configured by setting the following parameters:

Navigation:

  1. From Azure console, navigate to Function App and select protect function app.
  2. Navigate to Settings > Environment variables

Configuration Parameters to add / update:

  1. Set OPENID_ENABLED to false.

  2. Set authorization to jwt:

    • This specifies that JWT authentication will be used to secure the API.

  3. Set jwt_verify to 1:

    • Enables verification of the JWT token during API requests.

  4. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

  5. Set jwt_user_claim to upn or email:

    • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Obtain the Gateway URL:

After deploying the Cloud API using ARM, retrieve the API endpoint URL for the service:

From Azure Management console,

  1. Navigate to the deployed API Management gateway.
  2. Under APIs, select the Cloud API.
  3. Locate the Gateway URL (base URL) for the API.
  4. Append the operation path /v1/unprotect to the gateway URL.
  5. Record the complete endpoint URL for use in the Browser Protector configuration and also pass code query parameter.
    • protector_endpoint_url: <>

example: https://{apim-name}.azure-api.net/api/v1/unprotect?code={appKey}