Fact Of Death Direct Enquiry Response Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Security

Security and Authorization

Overview

FODDER implements the FHIR Patient/$match operation as a system-to-system service for querying deceased patient records from the Veritas Data Research Fact of Death API. This section documents the security model and authorization requirements for accessing this service.

Authentication and Authorization Framework

FODDER uses OAuth 2.0 Client Credentials Flow as defined in SMART App Launch Framework STU 2.2.0 for system-to-system authentication.

OAuth 2.0 Client Credentials Flow

The Client Credentials flow is used when:

• The client (system) is requesting access on its own behalf (not on behalf of a user)
• No user interaction is required for authentication
• The client is a trusted backend system with long-lived credentials

Authorization Requirements

Clients requesting access to the FODDER /Patient/$match operation must obtain an OAuth 2.0 access token with the following scope:

system/Patient.s?operation=match

This scope indicates that the client has authorization to execute the $match operation on Patient resources at the system level.

Scope Breakdown

• system: Indicates a system-level scope (no specific patient context)
• Patient.s: Refers to the Patient resource in search context
• ?operation=match: Specifies the $match operation

Token Endpoint Authentication

Clients must authenticate when requesting tokens using one of the following methods:

1. Client Secret Basic (Recommended for Server-to-Server)

Authorization: Basic base64(client_id:client_secret)
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=system/Patient.s?operation=match

2. Private Key JWT (Recommended for Enhanced Security)

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=<signed-jwt>&
scope=system/Patient.s?operation=match

For details on JWT-based authentication, refer to SMART App Launch - Asymmetric Client Authentication.

Access Control and Patient Privacy

Patient Matching Query Rights

The FODDER service is designed for death record inquiries only. Clients should:

1. Limit queries to confirmed-deceased records - Do not use $match to search for living patients
2. Respect data minimization principles - Only query the minimum necessary patient identifiers
3. Maintain audit logs - Track all API calls and results for compliance purposes
4. Implement rate limiting - Respect API rate limits to prevent abuse

Data Protection Obligations

Implementers of FODDER clients must:

• Encrypt sensitive data - Use TLS 1.2 or higher for all API communications
• Implement appropriate access controls - Restrict access to the $match operation to authorized personnel
• Document use cases - Maintain records of why death record lookups are being performed
• Comply with applicable regulations - Follow HIPAA, state privacy laws, and other relevant regulations

Token Lifecycle

Token Acquisition

Clients obtain a token by making a request to the token endpoint with their credentials:

Request Example (Client Secret Basic):

POST /oauth/token HTTP/1.1
Host: auth.example.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWxwaGE6c3VwZXJzZWNyZXQ=

grant_type=client_credentials&scope=system/Patient.s?operation=match

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "system/Patient.s?operation=match"
}

Token Usage

The access token is included in the Authorization header of FODDER API requests:

GET /fhir/Patient/$match?identifier=<value> HTTP/1.1
Host: api.example.org
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/fhir+json

Token Expiration and Refresh

• Tokens are issued with an expiration time (expires_in)
• Clients must refresh tokens before expiration by requesting a new token
• Expired tokens will be rejected by the API with a 401 Unauthorized response

API Security Best Practices

Transport Security

1. Use HTTPS/TLS 1.2+ - All API communication must be encrypted
2. Verify SSL certificates - Validate server certificates to prevent man-in-the-middle attacks
3. Disable weak cipher suites - Configure clients to use strong cryptographic algorithms

Credential Management

1. Secure storage - Store client credentials securely (e.g., environment variables, secrets management systems)
2. Credential rotation - Regularly rotate client secrets or certificates
3. Never hardcode credentials - Avoid embedding credentials in source code
4. Use dedicated service accounts - Create separate credentials for each application/environment

API Request Security

1. Validate requests - Ensure all query parameters are properly escaped
2. Implement request signing (optional) - Sign requests to prevent tampering
3. Track request IDs - Use correlation IDs to trace requests through logs
4. Implement rate limiting - Respect API rate limits and implement backoff strategies

Error Handling

Security-related errors are returned with appropriate HTTP status codes:

Important: Never expose sensitive information (credentials, PII) in error messages.

Compliance and Auditing

Audit Logging

Implementers must maintain audit logs for all Patient/$match operations including:

• Client identifier - Who made the request
• Timestamp - When the request was made
• Query parameters - What patient identifiers were used
• Response status - Whether the query succeeded
• Results summary - Number of matches returned (not the full patient records)

Example audit log entry:

{
  "timestamp": "2024-01-10T14:30:00Z",
  "client_id": "oncology-system-01",
  "operation": "/Patient/$match",
  "query_identifiers": ["SSN"],
  "matches_found": 1,
  "response_status": 200
}

Regulatory Compliance

Organizations using FODDER must ensure compliance with:

• HIPAA - Health Insurance Portability and Accountability Act
• State Privacy Laws - Including California Consumer Privacy Act (CCPA), GDPR applicability
• Institutional Policies - Internal data governance and privacy policies
• Professional Codes of Ethics - If applicable to the use case

Troubleshooting Authentication Issues

401 Unauthorized

Cause: Missing or invalid authentication credentials

• Solution: Verify the access token is included in the Authorization header with correct format (Bearer <token>)
• Solution: Check if the token has expired and obtain a new one

403 Forbidden

Cause: Valid credentials but insufficient permissions for the operation

• Solution: Verify the token includes the system/Patient.s?operation=match scope
• Solution: Check that the client has been granted permission to perform $match operations

429 Too Many Requests

Cause: Rate limit exceeded

• Solution: Implement exponential backoff in retry logic
• Solution: Contact the API administrator to discuss rate limit adjustments

References

• SMART App Launch Framework STU 2.2.0
• SMART Scopes for System-to-System
• SMART Client Credentials - Asymmetric Keys
• FHIR Patient/$match Operation
• HIPAA Security Rule Overview