Skip to main content

Quick Start

Get the AJ FHIR Consent Manager running and enforcing consent on your HAPI FHIR server.

Prerequisites​

  • Java 21 and Maven 3.9+, or Docker + Docker Compose v2
  • A running HAPI FHIR JPA server
  • A SMART-compliant auth server issuing RS256 Bearer tokens

1. Clone and build​

git clone https://github.com/AKHester-Technologies/ajfhir-consent-manager.git
cd consent-manager
cp .env.example .env

Edit .env and fill in the required values (see Configuration).

2. Configure environment​

Minimum required variables:

# Database
DB_URL=jdbc:postgresql://localhost:5432/ajfhir_consent
DB_USER=ajfhir
DB_PASS=<strong-random-password>

# HAPI FHIR server
FHIR_BASE_URL=http://localhost:8080/fhir
FHIR_SERVICE_TOKEN=<service-account-token>

# JWT validation — pick one key source
CONSENT_JWKS_URI=https://your-auth-server/oauth2/jwks
# or: RSA_PUBLIC_KEY_JWK={"keys":[...]}

# JWT validation claims
JWT_EXPECTED_ISSUER=https://your-auth-server
JWT_EXPECTED_AUDIENCE=http://localhost:8080/fhir
warning

If no JWT key source is configured the application refuses to start. This is intentional — no key means no token can be validated.

3. Start with Docker Compose​

docker compose up -d

The docker-compose.yml starts the Consent Manager and PostgreSQL together. HAPI FHIR must be running separately.

4. Verify it is running​

curl http://localhost:8082/actuator/health
# {"status":"UP"}

Without a consent record the interceptor denies by default:

curl -H "Authorization: Bearer <patient-token>" \
  http://localhost:8080/fhir/Observation/obs-001

# 403 Forbidden
{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "forbidden",
    "details": {
      "text": "Consent denied for READ on Observation. Patient consent does not permit this access. Regulatory basis: GDPR Art.9 · DISHA §4.2."
    }
  }]
}

Create a consent record and the same request returns 200:

curl -X POST http://localhost:8082/api/consent \
  -H "Authorization: Bearer <clinician-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId":       "Patient/patient-123",
    "actorReference":  "Device/my-smart-app",
    "provisionType":   "permit",
    "resourceClasses": ["Observation"],
    "scopeValues":     ["patient/Observation.rs"],
    "periodStart":     "2025-01-01",
    "periodEnd":       "2027-12-31",
    "regulatoryBasis": "GDPR Art.9"
  }'

6. Open the patient portal​

http://localhost:8082/consent/portal

Patients authenticate via OAuth2 login and see their consent dashboard, history, and revocation options.

7. Run the tests​

mvn test
# 182 tests, 179 active, BUILD SUCCESS

Tests run against H2 in-memory — no PostgreSQL required for the test suite.

Connecting to an EHR​

See the Configuration page for Epic, Cerner, and Azure AD setup.

Next: Architecture →