Tenant Service

Overview

The Tenant service is the entry point for configuring a tenant into Link Cloud. The service is responsible for maintaining and generating events for the scheduled measure reporting periods that the tenant is configured for. These events contain the initial information needed for Link Cloud to query resources and perform measure evaluations based on a specific reporting period.

The Tenant service uses Quartz with ADO Job Stores to manage jobs across multiple instances of the service, primarily for producing ReportScheduled Kafka events.

flowchart LR
nTenantService_29AF3ECE["Service: Tenant Service"]
  nTenantService_29AF3ECE -->|produces| nAuditableEventOccurred_AF8D6F7["Event: AuditableEventOccurred"]
  nTenantService_29AF3ECE -->|produces| nReportScheduled_4CB82B8["Event: ReportScheduled"]
  nTenantService_29AF3ECE -->|sends| nGenerateReportRequested_5FF13A3F["Command: GenerateReportRequested"]
  nTenantService_29AF3ECE -->|provides| nGetFacilitiesList_48F17BCD["Query: GetFacilitiesList"]
  nTenantService_29AF3ECE -->|provides| nGetFacilityConfig_3026B4B5["Query: GetFacilityConfig"]
  nTenantService_29AF3ECE -->|provides| nGetServiceInfo_56528670["Query: GetServiceInfo"]
  nTenantService_29AF3ECE -->|requests| nGetFacilitiesList_48F17BCD["Query: GetFacilitiesList"]
  nTenantService_29AF3ECE -->|requests| nGetFacilityConfig_3026B4B5["Query: GetFacilityConfig"]
  nTenantService_29AF3ECE -->|requests| nGetServiceInfo_56528670["Query: GetServiceInfo"]
  subgraph nCompliance_11EAF98F_domain["Domain: Compliance"]
    nAuditableEventOccurred_AF8D6F7
  end
  subgraph nReport_523BC237_domain["Domain: Report"]
    nGenerateReportRequested_5FF13A3F
    nReportScheduled_4CB82B8
  end
  subgraph nTenant_223E8F95_domain["Domain: Tenant"]
    nGetFacilitiesList_48F17BCD
    nGetFacilityConfig_3026B4B5
    nGetServiceInfo_56528670
    nTenantService_29AF3ECE
  end

Common Configurations

• Swagger
• Azure App Configuration
• Kafka Configuration
• Kafka Consumer Retry Configuration
• Service Registry Configuration
• CORS Configuration
• Token Service Configuration
• Service Authentication
• SQL Server Database Configuration

Custom Configuration

Soft Delete

The Tenant service supports soft deletion of facilities. Rather than permanently removing a facility record, the soft delete endpoint marks the facility with an isDeleted flag set to true. This preserves the facility's configuration and historical data while effectively removing it from active use.

DELETE /api/Facility/softDelete/{facilityId}

Soft deletes a facility by setting its isDeleted flag to true.

Parameters:

• facilityId (path, required): The unique identifier of the facility to soft delete.

Response:

• 200 OK: Facility soft deleted successfully. Returns the updated facility configuration.
• 400 Bad Request: If the request is invalid.
• 404 Not Found: If no facility exists for the specified facilityId.
• 500 Internal Server Error: If an error occurs during processing.

Features and Functionality

Key Management

Keys are managed independently by the tenant service, and then associated with tenants. These keys are used for signing authentication JWTs that are passed to /token endpoints at the EHRs. EHRs check that the JWTs are signed using a key found in the JWKS endpoint exposed by Link.

• Key Registry: A global repository where all JWT signing keys are stored and managed. Each key includes metadata such as kid, algorithm, creation timestamp, status (active, disabled, expired), and an optional primary flag.
• Lifecycle Operations:
  • Create: Keys can be generated through the admin API/UI with algorithm selection and optional designation as primary.
  • Disable/Delete: Keys no longer in use can be deactivated or removed without disrupting tenant authentication, unless actively in use. This can occur when needing to rotate a key.
  • Rotating Keys:
    1. Create a new key
    2. Associate the new key with tenants
    3. Delete the old key.
• Tenant Association (handled separately):
  • Tenants reference keys by kid through the Tenant Service configuration interface.
  • A tenant may use a shared or unique key from the registry.
  • Changing a tenant’s associated key does not impact the underlying key object—it only changes the reference.
• JWKS documents are managed automatically
  • When keys change the JWKS document is re-generated
  • The JWKS document is stored on the file system
  • The JWKS document on the file system is exposed via proxy to external parties for verification (such as EHRs)

The following sequence diagram illustrates how the keys are used during the authentication requests to EHRs:

sequenceDiagram
    participant L as Link
    participant J as JWKS Endpoint
    participant E as EHR Vendor

    L->>L: Create JWT
    L->>L: Sign JWT (with kid)
    L->>J: Publish key to JWKS
    L->>E: POST /token (with JWT)
    E->>J: GET /.well-known/jwks.json
    J-->>E: Return JWKS document
    E->>E: Verify signature using kid
    E-->>L: Return access token

Database Schema

OpenAPI Operations

Relationships

flowchart LR
nTenantService_29AF3ECE["Service: Tenant Service"]
  nTenantService_29AF3ECE -->|produces| nAuditableEventOccurred_AF8D6F7["Event: AuditableEventOccurred"]
  nTenantService_29AF3ECE -->|produces| nReportScheduled_4CB82B8["Event: ReportScheduled"]
  nTenantService_29AF3ECE -->|sends| nGenerateReportRequested_5FF13A3F["Command: GenerateReportRequested"]
  nTenantService_29AF3ECE -->|provides| nGetFacilitiesList_48F17BCD["Query: GetFacilitiesList"]
  nTenantService_29AF3ECE -->|provides| nGetFacilityConfig_3026B4B5["Query: GetFacilityConfig"]
  nTenantService_29AF3ECE -->|provides| nGetServiceInfo_56528670["Query: GetServiceInfo"]
  nTenantService_29AF3ECE -->|requests| nGetFacilitiesList_48F17BCD["Query: GetFacilitiesList"]
  nTenantService_29AF3ECE -->|requests| nGetFacilityConfig_3026B4B5["Query: GetFacilityConfig"]
  nTenantService_29AF3ECE -->|requests| nGetServiceInfo_56528670["Query: GetServiceInfo"]
  subgraph nCompliance_11EAF98F_domain["Domain: Compliance"]
    nAuditableEventOccurred_AF8D6F7
  end
  subgraph nReport_523BC237_domain["Domain: Report"]
    nGenerateReportRequested_5FF13A3F
    nReportScheduled_4CB82B8
  end
  subgraph nTenant_223E8F95_domain["Domain: Tenant"]
    nGetFacilitiesList_48F17BCD
    nGetFacilityConfig_3026B4B5
    nGetServiceInfo_56528670
    nTenantService_29AF3ECE
  end