Operation: $offboard

Overview

$offboard is the counterpart to Operation: $initiate-onboarding. Where $initiate-onboarding supplies a Backend Service with the initial context needed to begin interacting with a PoC, $offboard supplies the same context so the Backend Service can identify, and subsequently withdraw, the established backend service relationship with the requesting PoC.

Within HALO, the PoC discovers the Backend Service's App Catalog offboardingEndpoint from the App Catalog and invokes the $offboard operation at that endpoint to end the backend services relationship previously established via $initiate-onboarding. The PoC passes its FHIR server base URL as the iss parameter along with the offboardingVerifier it retained from the original $initiate-onboarding invocation, allowing the Backend Service to confirm that the request originates from the same PoC (or one of its trusted subsystems) that completed onboarding before it withdraws the relationship. The Backend Service uses the supplied iss to locate any corresponding client registration, credentials, or discovered metadata, and to retire them according to its own deployment-specific processes. See Operation: $initiate-onboarding for the trust considerations and challenge/verifier mechanism established during onboarding.

To view the underlying FHIR OperationDefinition resource, see Offboard.

URL: [base]/$offboard

Expected Behavior

When a PoC no longer wishes for a Backend Service to interact with it, for example after an administrator disables or removes the Backend Service from the PoC's local configuration, the PoC invokes that Backend Service's $offboard operation using an HTTP POST to the offboardingEndpoint advertised in the App Catalog. The request includes the PoC FHIR server base URL in the iss parameter and the offboardingVerifier retained from the original $initiate-onboarding invocation.

Upon receiving the request, the Backend Service uses the supplied iss to locate the corresponding backend service relationship, if any. Where a relationship is found, the Backend Service SHALL check that the supplied offboardingVerifier is valid by hashing it using a Base64url-encoded SHA-256 hash and confirming the result matches the offboardingChallenge recorded during onboarding. Only when the two match does the Backend Service treat the request as authoritative, using the supplied context to locate any client registration, stored credentials, cached SMART configuration metadata, or other artifacts associated with the identified PoC. The Backend Service SHALL then cease requesting new access tokens from that PoC's authorization server and SHALL cease attempting to access that PoC's FHIR APIs. Depending on the jurisdiction and implementation, offboarding may also involve the Backend Service revoking or deleting its own Dynamic Client Registration record with the PoC, discarding cached tokens, or removing the PoC from its own list of active integrations.

The $offboard operation does not itself revoke any tokens already issued by the PoC's authorization server; token revocation, where supported, is a distinct mechanism defined by that authorization server. The role of $offboard is to formally notify the Backend Service that the backend service relationship should be withdrawn and that no further token requests or FHIR API access attempts should occur going forward.

A PoC SHOULD invoke $offboard any time it removes or disables a previously onboarded Backend Service, even if no backend service interactions ultimately occurred, so that the Backend Service can reliably reconcile its own records of active integrations.

Once a Backend Service has accepted an $offboard request for a given relationship, the corresponding offboardingChallenge and verifier SHALL be considered retired. If the PoC later re-onboards with that Backend Service, it SHALL generate a new verifier and offboardingChallenge via $initiate-onboarding rather than reusing the original pair.

Operation Failure

If the Backend Service cannot process the invocation or validate the supplied request parameters, it SHALL return an OperationOutcome describing the issue so the PoC can surface an actionable offboarding error to the administrator.

If the Backend Service does not recognize the supplied iss as corresponding to an existing backend service relationship, it SHALL still return a successful OperationOutcome, since the desired end state (no active relationship for that PoC) already holds. Implementers SHALL treat $offboard as idempotent for this reason.

If the Backend Service recognizes the supplied iss but the supplied offboardingVerifier does not produce the offboardingChallenge stored for that relationship, the Backend Service SHALL reject the request and SHALL NOT withdraw the relationship, since the caller has not demonstrated that it is the same system (or a trusted subsystem) that completed the original $initiate-onboarding invocation.

HTTP Response Codes

The $offboard operation is a HALO-defined offboarding operation and does not map directly to a standard FHIR create, update, or transaction interaction. The following HTTP response codes are the expected baseline for implementers:

• 200 OK - The Backend Service accepted the offboarding request and returned an OperationOutcome confirming the result, whether or not an active relationship was found.
• 400 Bad Request - The request was malformed, including cases where the required iss parameter was missing or invalid.
• 401 Unauthorized / 403 Forbidden - The supplied offboardingVerifier did not match the offboardingChallenge stored for the identified relationship.
• 405 Method Not Allowed - The caller used a method other than HTTP POST, or the server does not support this operation at the addressed endpoint.
• 422 Unprocessable Entity - The request was syntactically valid but could not be processed according to server rules (for example, the iss and/or offboardingVerifier parameters were malformed).

Other standard HTTP status codes such as 404 and 500 may also be returned depending on deployment-specific security and operational behavior.

Examples

Invocation

See the offboard-invocation-example example for more information.

Success Response

See the offboard-success-response-example example for more information.

Error Response

See the offboard-error-response-example example for more information.