Skip to content

idp.md

Latest commit

 

History

History
119 lines (90 loc) · 5.01 KB

idp.md

File metadata and controls

119 lines (90 loc) · 5.01 KB

IDP (CAVE) configuration

This document covers configuration for the CAVE IDP proxy endpoints (/v0/cave*) and Idp::Client.

API endpoints

Authenticated vets-api routes exposed for CAVE are:

  • POST /v0/cave: submit a base64-encoded PDF and filename for intake.
  • GET /v0/cave/:id/status: retrieve the current processing state for a submitted document.
  • GET /v0/cave/:id/output: retrieve extracted output for a processed document. type=form is supported; omitted type defaults to artifact.
  • GET /v0/cave/:id/download?kvpid=...: download the JSON payload for a specific extracted KVP record.
  • POST /v0/cave/:id/update?kvpid=...: replace the JSON payload for a specific extracted KVP record.
  • POST /v0/cave/diff: compare two JSON objects locally and return field-level differences. This route is handled in vets-api and is not proxied upstream.

API reference docs:

  • Swagger 2.0 route reference: GET /v0/apidocs
  • OpenAPI 3.0 route reference: GET /v0/openapi when the generated public/openapi.json artifact is present

Settings keys

IDP settings live under cave.idp:

cave:
  idp:
    base_url: ~
    connect_url: ~
    timeout: ~
    mock: true
    hmac:
      key_id: ~
      secret: ~
  • base_url: Logical base URL for the IDP API. This remains the request URL and provides the host used for Host, TLS SNI, and certificate validation.
  • connect_url: Optional alternate network destination used when the client must reach IDP through a different hostname, such as a VPCE endpoint. Only the hostname is used for the TCP connection override; the request path still comes from base_url.
  • timeout: Request timeout in seconds.
  • mock: When true, Idp.client uses Idp::MockClient (outside production).
  • hmac.key_id: Optional key identifier sent as X-IDP-Key-Id.
  • hmac.secret: Shared secret used to sign outbound IDP requests.

Environment variables

Idp::Client and Idp.client use the following env vars:

  • bio__IDP_API_BASE_URL: Logical IDP API base URL.
  • bio__IDP_API_CONNECT_URL: Optional network connect URL for VPCE/private API access.
  • bio__IDP_API_TIMEOUT: Timeout in seconds.
  • IDP_USE_LIVE: If present, forces live client outside production.
  • bio__IDP_HMAC_KEY_ID: Optional HMAC key identifier for outbound signed requests.
  • bio__IDP_HMAC_SECRET: HMAC shared secret for outbound signed requests.

Resolution order

For Idp::Client config:

  1. Constructor args (base_url, connect_url, timeout, hmac_key_id, hmac_secret)
  2. Settings.cave.idp.base_url / Settings.cave.idp.connect_url / Settings.cave.idp.timeout / Settings.cave.idp.hmac.*
  3. bio__IDP_API_BASE_URL / bio__IDP_API_CONNECT_URL / bio__IDP_API_TIMEOUT / bio__IDP_HMAC_*
  4. Default timeout of 15

Outbound identity/signature behavior:

  • Idp::Client always forwards X-IDP-User-Id from the authenticated current_user.
  • When connect_url is configured, Idp::Client keeps the logical base_url for the request URL and resolves the connect_url host to an alternate TCP destination, similar to curl --connect-to.
  • When bio__IDP_HMAC_SECRET (or cave.idp.hmac.secret) is configured, requests are signed and include:
    • X-IDP-Timestamp
    • X-IDP-Key-Id (when configured)
    • X-IDP-Signature (HMAC SHA-256)

For client type (Idp.client):

  1. Production: always live (Idp::Client)
  2. IDP_USE_LIVE present: live
  3. Settings.cave.idp.mock
  • true => Idp::MockClient
  • false => Idp::Client

Local development

Use config/settings.local.yml to override local behavior, for example:

cave:
  idp:
    base_url: https://logical-api.execute-api.us-gov-west-1.amazonaws.com/stg/api/v1/doc
    connect_url: https://vpce-connect.execute-api.us-gov-west-1.vpce.amazonaws.com/stg/api/v1/doc
    timeout: 15
    mock: true
    hmac:
      key_id: idp-hmac-v1
      secret: your-shared-secret

To test the live client in development/test, either set mock: false or set IDP_USE_LIVE=true.

Deployment (non-local and production)

Set environment-specific values in deployment config and parameter store/secrets.

  • Vets API deployment config location (private repo):
    • devops/ansible/deployment/config/vets-api/
    • Environment templates include dev, staging, and prod settings files.
  • Add or update these env vars per environment:
    • bio__IDP_API_BASE_URL
    • bio__IDP_API_CONNECT_URL
    • bio__IDP_API_TIMEOUT
    • bio__IDP_HMAC_KEY_ID
    • bio__IDP_HMAC_SECRET
  • Keep production/staging mock: false and do not set IDP_USE_LIVE unless intentionally overriding behavior.

Production checklist

  1. Add/update bio__IDP_API_BASE_URL, bio__IDP_API_CONNECT_URL, bio__IDP_API_TIMEOUT, bio__IDP_HMAC_KEY_ID, and bio__IDP_HMAC_SECRET in production deployment config.
  2. Confirm runtime settings resolve to the expected values in production pods.
  3. Verify /v0/cave* requests can reach the IDP API and time out as expected.
  4. Verify IDP receives X-IDP-User-Id and HMAC headers on all five routes (intake, status, output, download, update).