eirikhaughom/adme-notification-relay repository overview

⁠OSDU Notification Broker (Azure Functions) – Container Image

Small Azure Functions relay that accepts OSDU notifications, validates HMAC signatures (incl. OSDU challenge/handshake), optionally translates OSDU DataNotification payloads into Azure Event Grid events, and forwards them to an Event Grid topic.

• HTTP endpoint: /api/osdu-relay
• Exposed container port: 80 (map to your host, e.g., -p 7071:80)
• Base image: mcr.microsoft.com/azure-functions/python:4-python3.12

⁠Quick start

Pull and run with required environment variables:

# PowerShell
$IMAGE = "docker pull eirikhaughom/adme-notification-relay:main"

docker pull $IMAGE

docker run --rm --name adme-notification-relay `
  -p 7071:80 `
  -e EVENT_GRID_ENDPOINT="https://<topic-or-domain>.<region>.eventgrid.azure.net/api/events" `
  -e EVENT_GRID_AUTH="key" `
  -e EVENT_GRID_KEY="<event-grid-access-key>" `
  -e HMAC_SECRET="<hex-or-string-secret>" `
  $IMAGE

Then call the function:

• Readiness: GET http://localhost:7071/api/osdu-relay
• Handshake: GET http://localhost:7071/api/osdu-relay?crc=...&hmac=...
• Post events: POST http://localhost:7071/api/osdu-relay

For local dev with Azurite, use docker compose so the function can reach a local Storage emulator. See the repo’s docker-compose.yml for an example.

⁠What this image does

• Verifies incoming HMAC signatures from header/query (supports raw HMAC or OSDU token format).
• Handles OSDU challenge handshake and returns the responseHash expected by clients.
• Detects payload schema:
  • If already Event Grid schema, forwards as-is.
  • If OSDU DataNotification array, translates each item into Event Grid events and forwards the batch.
• Publishes to Azure Event Grid using either Managed Identity/AAD, Service Principal, or Access Key.

⁠Configuration (environment variables)

Minimum to run:

• EVENT_GRID_ENDPOINT (required): Event Grid publish endpoint.
  • Basic Topic/Domain: https://<topic or domain>.<region>.eventgrid.azure.net/api/events
  • Namespace: the Namespace endpoint host or URL.
• HMAC_SECRET or Key Vault settings (one of): HMAC secret to validate signatures.
  • HMAC_SECRET (simple local/dev), OR one of the Key Vault options below.

Auth modes for Event Grid (set EVENT_GRID_AUTH):

• managed (default): Managed Identity/AAD using environment credentials
  • Recommended in Azure Container Apps/AKS with a managed identity and RBAC role "Event Grid Data Sender" on the target.
• sp: Service Principal (Client ID/Secret)
  • Provide AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET (or the EVENT_GRID_* overrides below).
• key: Access Key header
  • Provide EVENT_GRID_KEY.

Key Vault (optional, to fetch HMAC_SECRET at runtime):

• KEY_VAULT_SECRET_URI OR KEY_VAULT_URL + KEY_VAULT_SECRET_NAME
• KEY_VAULT_AUTH = managed (default) or sp with AZURE_* or KEY_VAULT_* overrides

Event Grid Namespace (optional):

• EVENT_GRID_NAMESPACE_TOPIC: Namespace Topic name (only for Namespace endpoints)
• EVENT_GRID_CLOUD_SOURCE (default /osdu/relay): CloudEvent source when converting for Namespace

Service Principal overrides (optional, when using *_AUTH=sp):

• Shared defaults: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
• Key Vault specific: KEY_VAULT_TENANT_ID, KEY_VAULT_CLIENT_ID, KEY_VAULT_CLIENT_SECRET
• Event Grid specific: EVENT_GRID_TENANT_ID, EVENT_GRID_CLIENT_ID, EVENT_GRID_CLIENT_SECRET

Signature and translation settings (optional):

• HMAC_HEADER (default Authorization), SIGNATURE_PREFIX (default hmac), SIGNATURE_FORMAT (hex|base64)
• CHALLENGE_HMAC_REQUIRED (default true), CHALLENGE_HASH_ENCODING (base64-hex default, base64, or hex)
• EVENT_TYPE_MODE (single default or by_op), EVENT_TYPE_* variables

For the full list and details, see the project README in the repository.

⁠Usage examples

⁠1) Access Key auth (simple local run)

# PowerShell
$env:AzureWebJobsStorage = "<YOUR_STORAGE_CONN_STRING>"
$env:EVENT_GRID_ENDPOINT = "https://<topic>.<region>.eventgrid.azure.net/api/events"
$env:EVENT_GRID_AUTH = "key"
$env:EVENT_GRID_KEY = "<event-grid-access-key>"
$env:HMAC_SECRET = "<hex-or-string-secret>"

docker run --rm -p 7071:80 --name osdu-notification-broker `
  -e AzureWebJobsStorage `
  -e EVENT_GRID_ENDPOINT -e EVENT_GRID_AUTH -e EVENT_GRID_KEY `
  -e HMAC_SECRET `
  <IMAGE>:<TAG>

Send an OSDU payload; the service will translate and forward when appropriate:

curl -X POST "http://localhost:7071/api/osdu-relay" \
  -H "Content-Type: application/json" \
  -H "Authorization: hmac <signature>" \
  --data '[{"id":"opendes:doc:123","kind":"opendes:doc:0.2.0","op":"create"}]'

Add ?dryRun=1 to see the translated Event Grid batch without forwarding.

⁠2) Azure Container Apps with Managed Identity

• Assign a managed identity to your Container App.
• Grant it RBAC role "Event Grid Data Sender" on the target topic/domain/namespace topic.
• Optionally, grant Key Vault access (e.g., "Key Vault Secrets User") and set KEY_VAULT_SECRET_URI.

Set app env vars:

• EVENT_GRID_AUTH=managed
• EVENT_GRID_ENDPOINT=...
• KEY_VAULT_SECRET_URI=... (or HMAC_SECRET)
• EVENT_GRID_NAMESPACE_TOPIC=... if using a Namespace

⁠Ports and health

• Exposed port: 80 (map as needed)
• Ready check: GET /api/osdu-relay returns 200 OK when the host is up
• Handshake: GET /api/osdu-relay?crc=...&hmac=... returns { "responseHash": "..." } on success

⁠Notes and best practices

• Do not bake real secrets into images. Use environment variables and (in Azure) Managed Identity + Key Vault.
• For local use, a real Storage connection string is simplest. If you prefer Azurite, run it alongside this container and point AzureWebJobsStorage at the Azurite endpoints.
• If signature checks fail, ensure the client computes the HMAC over the exact bytes sent (UTF‑8) and uses the same SIGNATURE_FORMAT.