61.2.1Registration and Authentication Overview

A precursor to any exchange between parties requires setting up a secure exchange via a registration process. This section covers the registration and authentication considerations for both requesting and responding payers.

61.2.2When You Are the Requesting Payer

61.2.2.1Creating SMART Server Definitions

SMART Server Definition configuration defines how your Smile CDR instance will authenticate and communicate with external FHIR servers, enabling secure Payer-to-Payer data exchange.

61.2.2.2Using External Identity Servers

For customers who manage their authentication keys and processes within external Identity Provider (IdP) services (e.g., PingFed), Smile CDR's System-to-System (S2S) module provides a mechanism to integrate with these services.

This approach is particularly useful when:

• Your organization has an existing, established IdP that manages user authentication and authorization
• You need to leverage specific authentication flows or assertions provided by your external IdP
• You want to centralize key management within your IdP and avoid duplicating it within Smile CDR

61.2.2.3Creating Organization Resources

As part of the registration process, payers should generate an HRex Organization resource to support:

• Providing a list of supported payers to end users: Applications can query Organization resources to present a list for selecting another health insurance provider
• Documenting the source of imported records via Provenance: The system-to-system module can add an Organization reference to the source payer
• B2B registration workflows: Establishing business identity separate from technical credentials

61.2.3When You Are the Responding Payer

61.2.3.1Creating SMART Client Definitions

Creating a SMART Client Definition for the requester is a required step for responding payers.

61.2.4Authorizing Access

Two key considerations when designing the authorization layer:

1. Storing business identity: Consent is often linked to a business identifier, not a set of client credentials. Your system must be able to store a business identifier for the requesting payer that can be linked with credentials

2. Validating business identity: At the time of the request, an interceptor can cross reference the credentials against resources that validate authorization

61.2.4.1Single-Member Authorization via Consent

For responding payers supporting Patient-level $export flows:

• Primary document linking requester to member's consent is the Consent resource sent as part of $member-match request
• Smile's implementation stores this Consent resource and adds an extension linking it to a SMART Client Definition
• In a callback script after successful authentication, the system can reference the Consent to:
  • Ensure the member's Consent exists for the requester
  • Ensure it is still valid (if an end date is defined)

61.2.4.2Multi-Member Authorization via Token Claims

For responding payers supporting Group-level $davinci-data-export flows:

• A Group resource is the primary document linking a requester to member's opt-in
• The token includes a claim declaring relevant business identifier(s) for the client
• In a callback script after successful authentication, the system cross-references identifiers in the claim with "match" Groups

61.2.4.3Multi-Member Authorization via Organization

For FHIR-resource based design:

• An Organization resource is created for the requesting payer at registration
• Contains a reference to the SMART Client Definition in an extension
• In a callback script, the system cross-references client credentials with linked Organization resources

61.2.4.4Business Identifier Methods

Two recommended methods for obtaining business identifiers during group creation:

61.2.4.5Sample Callback Script

function onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext) {
    theOutcome.addUserData('business-id', 's2sBusId');
    return theOutcome;
}

Note: s2sBusId is a fixed value for demonstration. In reality, this will be a value either supplied by the external IAM or a lookup of an Organization resource.

61.2.5Configuration Considerations

To implement external IdP integration:

1. Deploy Interceptors: Ensure custom interceptor scripts are properly deployed within your Smile CDR environment

2. S2S OIDC Server Settings: Configure settings to point to your external IdP's endpoints (e.g., .well-known/jwks.json for JWKS-based authentication)

3. Client Registration: Ensure your Smile CDR instance is registered as a client with your external IdP

4. Refactor Token Request Code: Use OIDC libraries as appropriate within interceptor scripts