Authenticate and Authorize Provider System

 

Before calling $davinci-data-export, the provider system must authenticate and obtain an access token using SMART on FHIR and OAuth 2.0. This ensures secure, System-to-System communication with Smile CDR and enforces access control based on Group membership and consent.

Authenticate and Authorize Workflow

  1. Provider System Requests Token
    • The provider system sends a request to the Identity Provider (IdP) with its client credentials.
    • Note: The IdP may be Smile (Pattern 1) or an external IdP (Pattern 2).
  2. IdP Issues Access Token
    • The IdP validates credentials and issues a JWT access token containing the necessary scopes (e.g., patient/*.read).
  3. Provider System Calls FHIR Server
    • The access token is included in the Authorization header when calling $davinci-data-export.
  4. FHIR endpoint Validates Token
    • The FHIR endpoint validates the token against the IdP configuration and confirms Group membership.
    • Consent preferences are enforced, ensuring opted-out members are excluded.
  5. Access Granted or Denied
    • Data is returned only for members the provider system is authorized to access.

Grant Permissions to the Provider System

Grant the permissions to the user or client that the provider system authenticates as.

The provider system usually does not know the ID of the Group it exports from when you configure it:

  • Attestation: each call to $provider-member-match stores a new Group, with an ID that the server assigns.
  • Attribution: the Payer can create or replace the provider system's Groups at any time.

For this reason, do not grant FHIR_OP_INITIATE_BULK_DATA_EXPORT_GROUP, which names a single Group ID, such as Group/123. Grant FHIR_OP_INITIATE_BULK_DATA_EXPORT_GROUPS_MATCHING instead, with a Group search that matches the provider system's business identifier. Smile CDR checks the Group against the search when the export starts, so the permission also covers Groups that are created later.

PermissionArgumentAllows
FHIR_OP_INITIATE_BULK_DATA_EXPORT_GROUPS_MATCHING?identifier=[system]%7C[value], followed by a space and either * (all resource types) or a space-separated list of resource types$davinci-data-export on every Group that matches the search, and polling the export status
FHIR_READ_ALL_OF_TYPEBinaryDownloading the exported files, and the result of an asynchronous $provider-member-match. Both are Binary resources.
FHIR_OP_MEMBER_MATCHNone$provider-member-match. Attestation only.
FHIR_EXTENDED_OPERATION_ON_TYPEGroup/$provider-member-match-poll-statusPolling an asynchronous $provider-member-match. Attestation only.

The provider system needs no Consent, Group, Patient or Coverage permissions for $provider-member-match. Smile CDR stores the match Group, and a treatment attestation Consent for each matched member, itself, and runs the opt-out check itself.

For example, the following permission allows the provider system with NPI 1356441356 to export all resource types from its Groups:

{
  "permission": "FHIR_OP_INITIATE_BULK_DATA_EXPORT_GROUPS_MATCHING",
  "argument": "?identifier=http://hl7.org/fhir/sid/us-npi%7C1356441356 *"
}

The identifier in the argument must match the identifier that the provider system's Groups carry:

  • Attestation: $provider-member-match copies the caller's business identifiers into Group.identifier of the Group it stores. These are the auth-business-identifiers that the authentication callback script puts in the session. See Business Identifier Methods.
  • Attribution: the Payer adds the provider system's NPI or other business identifier to Group.identifier. See Create Group Resources.

If the provider system uses the same identifier in both workflows, one permission covers both.

To discover its Group IDs in the Attribution workflow, the provider system also needs to search Group resources, for example with FHIR_READ_ALL_OF_TYPE and the argument Group. This permission is not limited to the provider system's own Groups.

For the full list of bulk export permissions and their arguments, see Authorization for Bulk Export.