Introduction

While working with the Azure Face API to implement headshot validation, I encountered the following error during a face detection task:

Error during API call: (InvalidRequest) Invalid request has been sent.

This generic error provided no actionable information, making debugging difficult. To resolve the issue, I had to:

• Dig deeper into the FaceClient SDK.
• Enable logging to capture HTTP requests and responses.
• Eventually uncover the root cause: the returnFaceId parameter.

This post will walk you through:

1. How I identified and resolved the issue.
2. Why the returnFaceId parameter caused the error.
3. How to fix and debug similar issues in the Azure Face API.
4. How to request approval for the returnFaceId feature.
5. How to directly invoke the API for maximum control.

If you’re interested in headshot validation, check out my earlier post: Headshot Validation Using Azure Face API with Python.

Initial Code

Here’s the initial code I was using for face detection:

try:
    with open(image_path, "rb") as image_stream:
        print("Sending image to Azure Face API...")
        detected_faces = face_client.face.detect_with_stream(
            image=image_stream,
            detection_model="detection_03"  # Modern detection model
        )
except Exception as e:
    print(f"Error during API call: {e}")
    return False

The output:

Error during API call: (InvalidRequest) Invalid request has been sent.

This generic message made it hard to debug the issue. I had no idea whether the problem was with my parameters, the image, or the API itself.

Adding Logging to Debug

To get more details, I enabled HTTP logging to capture the raw request and response sent to the Azure Face API. Here’s the updated code:

import logging

logging.basicConfig(level=logging.DEBUG)  # Enable detailed logging

try:
    with open(image_path, "rb") as image_stream:
        print("Sending image to Azure Face API...")
        detected_faces = face_client.face.detect_with_stream(
            image=image_stream,
            detection_model="detection_03"  # Modern detection model
        )
except Exception as e:
    if hasattr(e, 'response') and e.response is not None:
        print("Error during API call:")
        print(f"HTTP Status Code: {e.response.status_code}")
        print(f"Response Body: {e.response.text}")
    else:
        print(f"Error: {e}")
    return False

The logs provided invaluable insights into the API behavior:

DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): xxxx.cognitiveservices.azure.com:443
DEBUG:urllib3.connectionpool:https://xxxx.cognitiveservices.azure.com:443 "POST /face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&recognitionModel=recognition_01&returnRecognitionModel=false&detectionModel=detection_03&faceIdTimeToLive=86400 HTTP/11" 403 362
DEBUG:msrest.exceptions:(InvalidRequest) Invalid request has been sent.
Error during API call:
HTTP Status Code: 403
Response Body: {
  "error": {
    "code": "InvalidRequest",
    "message": "Invalid request has been sent.",
    "innererror": {
      "code": "UnsupportedFeature",
      "message": "Feature is not supported, missing approval for one or more of the following features: Identification,Verification. Please apply for access at https://aka.ms/facerecognition"
    }
  }
}

Root Cause: returnFaceId Defaults to True

The returnFaceId parameter in the Azure FaceClient SDK defaults to True, meaning the API tries to generate and return a unique Face ID for each detected face. This Face ID serves as a temporary identifier for the detected face, enabling workflows like face recognition, verification, and finding similar faces. The Face ID represents the face’s extracted features and can be used in subsequent API calls to match or compare faces.

 However:

• This feature is restricted to approved customers only.
• If you don’t have approval, the API rejects the request with an InvalidRequest error.

Since my application only required face detection (and not recognition tasks), I resolved the issue by explicitly setting return_face_id=False:

detected_faces = face_client.face.detect_with_stream(
    image=image_stream,
    detection_model="detection_03",
    return_face_id=False  # Explicitly exclude Face ID
)

Directly Invoking the Azure Face API

If you prefer full control over your API parameters, you can bypass the SDK and call the Azure Face API directly. This avoids SDK defaults like returnFaceId=True.

Using cURL

curl -X POST "https://your-endpoint.cognitiveservices.azure.com/face/v1.0/detect" \
-H "Content-Type: application/octet-stream" \
-H "Ocp-Apim-Subscription-Key: your_subscription_key" \
--data-binary "@your_image.jpg"

Using Python requests

import requests
FACE_API_KEY = "your_subscription_key"
FACE_API_ENDPOINT = "https://your-endpoint.cognitiveservices.azure.com/face/v1.0/detect"
headers = {
    "Content-Type": "application/octet-stream",
    "Ocp-Apim-Subscription-Key": FACE_API_KEY
}
params = {
    "detectionModel": "detection_03"
}
with open("your_image.jpg", "rb") as image_stream:
    response = requests.post(FACE_API_ENDPOINT, headers=headers, params=params, data=image_stream)
print(response.json())

Direct API calls allow you to explicitly include or exclude parameters, ensuring greater flexibility.

How to Fix returnFaceId Errors

Set return_face_id=False:

• Unless your application requires face recognition workflows, explicitly exclude Face IDs:

detected_faces = face_client.face.detect_with_stream(
    image=image_stream,
    detection_model="detection_03",
    return_face_id=False
)

Request Approval for returnFaceId:

• Submit a request here: Request Face ID Access.
• Learn more about Azure’s limited-access features here: Limited Access Services.

Best Practices for Debugging Azure Face API

Enable Logging:

• Use Python’s logging module to capture HTTP requests and responses:

import logging
logging.basicConfig(level=logging.DEBUG)

Check API Documentation:

• Verify parameter compatibility in the Azure Face API Documentation.

Use cURL for Simple Tests:

• Test the API using cURL to isolate issues before implementing in Python.

Handle API Exceptions Gracefully:

• Extract and print detailed responses from exceptions:

if hasattr(e, 'response') and e.response is not None:
    print(f"HTTP Status Code: {e.response.status_code}")
    print(f"Response Body: {e.response.text}")

Conclusion

The returnFaceId parameter is powerful for face recognition workflows but requires approval for use. If you don’t need face IDs, explicitly set return_face_id=False to avoid errors. For advanced use cases requiring face IDs, submit a request for access.

By adding logging and carefully reviewing the API response, you can effectively debug and resolve issues in the Azure Face API, making it a reliable tool for tasks like headshot validation and face detection.

For a practical implementation of headshot validation, check out my post: Headshot Validation Using Azure Face API.

A reverse proxy acts as an intermediary server between clients and backend servers, forwarding requests and responses. Using NGINX as a reverse proxy enhances performance, strengthens security, simplifies application routing, and facilitates session sharing.

Refer to the following posts to understand more about the reverse proxy - Apache Reverse Proxy: Content From Different Websites | by Albin Issac | The Startup | Medium

Implementing Cross-Domain Cookie Handling for Seamless API Integration | by Albin Issac | Tech Learnings | Medium

Steps to Set Up NGINX as a Reverse Proxy on Windows:

 Install NGINX:

       
start nginx      
 

Configure Reverse Proxy:

Add the reverse proxy configuration: Here is the minimal configuration to proxy the requests to the backend server. You can add multiple servers and locations.

           
#user  nobody;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}



http {
    include       mime.types;
    default_type  application/octet-stream;
	
	log_format upstream_logging '[$time_local] $remote_addr - $remote_user - $server_name '
                                 'to: $upstream_addr: $request '
                                 'status $status upstream_response_time $upstream_response_time '
                                 'request_time $request_time '
                                 'headers: "$http_user_agent, 
                                 $http_x_forwarded_for, $http_x_cip_client_id" '
                                 'upstream_headers: "$upstream_http_content_type, 
                                 $upstream_http_content_length"';

    sendfile        on;

    keepalive_timeout  65;
	
	
	

server {
    listen 8000;
    listen [::]:8000;
	
    #SSL Support
    #listen 8000 ssl;
    #listen [::]:8000 ssl;

    server_name localhost;
	
    #Debug Logging
    #error_log logs/error.log debug;
	
    access_log logs/api_logging.log upstream_logging;
	
    #Configurations to support SSL
	
    #ssl_certificate      C://cert/localhost.crt;
    #ssl_certificate_key  C://cert/localhost.key;

    #ssl_session_cache    shared:SSL:1m;
    #ssl_session_timeout  5m;

    #ssl_ciphers  HIGH:!aNULL:!MD5;
    #ssl_prefer_server_ciphers  on;

    proxy_buffering off;
    proxy_busy_buffers_size   512k;
    proxy_buffers   4 512k;
    proxy_buffer_size   256k;	
	
	location / {
            root   html;
            index  index.html index.htm;
    }


    location /test/api {
		proxy_pass https://api.server.com;   

		proxy_set_header Host $proxy_host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header Header1  Header1 value;
                proxy_set_header Header2  Header2 value;
		proxy_ssl_name   $proxy_host;    
		proxy_ssl_server_name on; 
		
		#Set the Response Header with backend response headers for debugging
		
		#add_header X-Backend-Status $upstream_status;
		#add_header X-Backend-Server $upstream_addr;
		#add_header X-Backend-Content-Type $upstream_http_content_type;
		#add_header X-Backend-Content-Length $upstream_http_content_length;
		
		proxy_connect_timeout 60s;       # Timeout for connecting to the upstream
		proxy_send_timeout 60s;          # Timeout for sending to the upstream
		proxy_read_timeout 60s;          # Timeout for reading from the upstream


    }
}

   
}


       
 

       
 nginx -s reload
       
 

       
 nginx -s stop      
 

As businesses increasingly rely on digital documentation, protecting sensitive information within PDFs has become a top priority. PDFs are widely used because they preserve document formatting across devices, but without adequate security measures, they can be vulnerable to unauthorized access, copying, or editing. In Java applications that generate PDFs, adding protection layers can ensure that confidential information stays secure.

In this guide, we’ll explore how to enhance the security of PDFs generated using Java. From implementing password protection to setting user permissions and encryption, we’ll cover various approaches to safeguard your documents.

Why Protect PDFs?

Sensitive information—like financial records, proprietary research, and personal data—often ends up in PDF format. Securing these files not only helps prevent data breaches but also supports compliance with data privacy regulations like GDPR and HIPAA. Implementing PDF protection in your Java application can ensure that only authorized users have access and prevent alterations or copying of sensitive content.

Techniques for Securing PDFs in Java

Password Protection

Password-protecting PDFs provides an effective security layer to limit access. Java libraries like iText and Apache PDFBox offer methods to apply two types of passwords:

• User Password: Required to open the document, ensuring only authorized users can view its contents.
• Owner Password: Grants full control over document permissions (such as printing or editing) and allows modification of the document’s security settings.

Encryption:

Encryption secures PDF content by converting it into unreadable code, making it accessible only to users with the correct credentials. PDF encryption can use different approaches depending on security requirements:

Password-Based Encryption (Symmetric)

This is the most common form of PDF encryption, where a single password or key is used to both encrypt and decrypt the document. Password-based encryption ensures that only users who know the user password can open and view the document. An owner password can also be set to control permissions, such as printing, copying, or editing.

• Supported Encryption Algorithms: Libraries like PDFBox and iText support AES-128 and AES-256 encryption, providing strong security for PDF content.
• Use Case: Ideal for general document security when you need a straightforward way to limit access.

Setting Permissions:

Permissions offer granular control over document actions, such as printing, copying, editing, and content extraction. The owner password allows you to set these permissions in the PDF. This is especially useful for documents with sensitive content where you want to prevent unauthorized actions. Libraries like iText and PDFBox enable developers to configure these permissions during PDF creation.

Digital Signatures:

Digital signatures authenticate a document’s origin and confirm that it hasn’t been altered since signing, making them essential for legal, financial, and compliance-focused documents. Created using a private key embedded in a certificate, digital signatures provide document authenticity and tamper-evidence.

• Self-Signed Certificates: Useful for internal testing and validation, as they verify document integrity without requiring external validation. You can generate a self-signed certificate for demonstration purposes with the following keytool command:

  keytool -genkeypair -alias testkey -keyalg RSA -keysize 2048 -validity 365 -keystore keystore.p12 
  	-storetype PKCS12 -storepass changeit -keypass changeit -dname "CN=Test User, 
  		OU=Development, O=YourCompany, L=City, S=State, C=US"

• CA-Signed Certificates: Issued by trusted Certificate Authorities (CAs), CA-signed certificates are recommended for production environments as they provide credibility for official, external-facing documents. These certificates ensure maximum authenticity and compatibility, particularly in regulated industries.

When obtaining a document signing certificate from a CA, there are typically two private key storage options:

1. Hardware Tokens: Many CAs, including DigiCert, GlobalSign, and Entrust, require document signing certificates to be stored on a hardware token (usually a USB device). This token-based storage provides high security by storing the private key in a tamper-resistant environment. However, it has limitations for cloud applications and may not support fully automated workflows.

2. Cloud HSM (Hardware Security Module): Some CAs support storing document signing keys in a Cloud HSM. Cloud HSMs are FIPS-compliant, secure environments that allow the private key to remain secure while still being accessible to cloud-hosted applications. Examples of cloud HSM services include:

   • AWS CloudHSM
   • Azure Dedicated HSM
   • Google Cloud HSM

   Cloud HSMs offer several advantages for cloud-based and automated workflows:

   • Secure Remote Access: Allows cloud applications to access the signing key securely.
   • Programmatic Access: Enables automated, high-volume signing directly from applications.
   • Compliance and Security: Meets FIPS standards for handling sensitive data.

For production use, a CA-signed certificate is preferred to ensure that digital signatures are universally trusted and recognized. Be aware that some CAs may impose restrictions on the number of documents that can be signed per year or month, so choose an option that meets your specific needs.

Watermarking: 

Watermarking places visible text or images (e.g., "Confidential" or "Draft") across each page to visually indicate the document’s purpose or confidentiality level. Watermarks do not restrict access but serve as a deterrent to unauthorized distribution, making them particularly useful for internal or sensitive documents.

iText:

PDFBox: