The following methods may be implemented in a consent service script:
This method is called once at the start of each request. The purpose is to determine whether a request should be permitted to proceed, and whether to apply the rest of the consent service logic to the request. It may also pre-fetch any relevant data or resources that will be used to provide consent rules in subsequent method calls.
Inputs:
theRequestDetails – This object contains details about the FHIR request being made. The object will be of type RequestDetailsJson.theUserSession – This object contains details about the authenticated user and their session. This includes demographics, permissions, approved scopes, etc. The object will be of type UserSessionDetailsJson.theContextServices – This object has utility methods for interacting with the environment, and indicating a consent outcome to the rest of the framework. The object will be of type ScriptConsentContextServices.theClientSession – This object contains details about the authenticated OIDC client and their OAuth2 session. The object will be of type OAuth2ClientSession.Outputs:
theContextServices.Example:
function consentStartOperation(theRequestDetails, theUserSession, theContextServices, theClientSession) {
// For superusers, we will skip the rest of the consent service entirely
if (theUserSession != null && theUserSession.hasAuthority('ROLE_SUPERUSER')) {
theContextServices.authorized();
return;
}
// By default, this request should continue but still be evaluated by the service
theContextServices.proceed();
}
This method is called once for each resource that may be returned to the user. It has the ability to authorize the release of data, or to block it, or to request that it be passed to consentWillSeeResource for masking.
Note that this method will not be called if theContextServices.authorized() was invoked by the consent script in the consentStartOperation(...) method. This method can carry a significant performance impact, so it should only be used if necessary.
Inputs:
theRequestDetails – This object contains details about the FHIR request being made. The object will be of type RequestDetailsJson.theUserSession – This object contains details about the authenticated user and their session. This includes demographics, permissions, approved scopes, etc. The object will be of type UserSessionDetailsJson.theContextServices – This object has utility methods for interacting with the environment, and indicating a consent outcome to the rest of the framework. The object will be of type ScriptConsentContextServices.theResource – The resource that will be returned. The object will be a FHIR resource and can be examined using the techniques described in FHIR Model API.theClientSession – This object contains details about the authenticated OIDC client and their OAuth2 session. The object will be of type OAuth2ClientSession.Outputs:
theContextServices.Example:
/**
* If present, this function is called before every resource that may be returned
* to the user.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @package theResource The resource that will be accessed.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentCanSeeResource(theRequestDetails, theUserSession, theContextServices, theResource, theClientSession) {
if ( ...some condition... ) {
theContextServices.reject();
} else {
theContextServices.proceed();
}
}
This method is called once for each resource that is being returned to the user. It has the ability to mask specific elements (or even the whole resource) from being returned to the user.
Inputs:
theRequestDetails – This object contains details about the FHIR request being made. The object will be of type RequestDetailsJson.theUserSession – This object contains details about the authenticated user and their session. This includes demographics, permissions, approved scopes, etc. The object will be of type UserSessionDetailsJson.theContextServices – This object has utility methods for interacting with the environment, and indicating a consent outcome to the rest of the framework. The object will be of type ScriptConsentContextServices.theResource – The resource that will be returned. The object will be a FHIR resource and can be examined using the techniques described in FHIR Model API.theClientSession – This object contains details about the authenticated OIDC client and their OAuth2 session. The object will be of type OAuth2ClientSession.Outputs:
theContextServices.Example:
/**
* If present, this function is called before every resource that may be returned
* to the user.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @package theResource The resource that will be accessed.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentWillSeeResource(theRequestDetails, theUserSession, theContextServices, theResource, theClientSession) {
if ( ...some condition... ) {
theResource.clear('value');
}
}
This function will be called exactly once for each request that completes successfully (i.e. returns an HTTP 2xx response). Note that in the case of failed requests (HTTP 4xx or 5xx), completeOperationFailure will be called instead.
Inputs:
theRequestDetails – This object contains details about the FHIR request being made. The object will be of type RequestDetailsJson.theUserSession – This object contains details about the authenticated user and their session. This includes demographics, permissions, approved scopes, etc. The object will be of type UserSessionDetailsJson.theContextServices – This object has utility methods for interacting with the environment, and indicating a consent outcome to the rest of the framework. The object will be of type ScriptConsentContextServices.theClientSession – This object contains details about the authenticated OIDC client and their OAuth2 session. The object will be of type OAuth2ClientSession.Outputs:
Example:
/**
* If present, this function is called when a request has been handled
* successfully (i.e. an HTTP 2xx response)
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function completeOperationSuccess(theRequestDetails, theUserSession, theContextServices, theClientSession) {
// some functions...
}
This function will be called exactly once for each request that completes unsuccessfully (i.e. returns an HTTP 4xx or 5xx response).
Inputs:
theRequestDetails – This object contains details about the FHIR request being made. The object will be of type RequestDetailsJson.theUserSession – This object contains details about the authenticated user and their session. This includes demographics, permissions, approved scopes, etc. The object will be of type UserSessionDetailsJson.theContextServices – This object has utility methods for interacting with the environment, and indicating a consent outcome to the rest of the framework. The object will be of type ScriptConsentContextServices.theClientSession – This object contains details about the authenticated OIDC client and their OAuth2 session. The object will be of type OAuth2ClientSession.Outputs:
Example:
/**
* If present, this function is called when a request has been handled
* unsuccessfully (i.e. an HTTP 4xx/5xx response)
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function completeOperationFailure(theRequestDetails, theUserSession, theContextServices, theClientSession) {
// some functions
}
The following example shows a simple consent script, implementing consent rules based on user permissions and resource security labels.
In this example:
RULE_SUPERUSER permission do not have any consent rules appliedR (restricted) security label will have their Observation.value and Observation.note fields cleared before they are returned to the user.V (very restricted) security label will not be shown to the user at all./**
* If present, this function is called before every request. It serves two
* primary purposes:
*
* 1. It can be used to proactively determine that a request does not need
* to have the consent service applied to it. This is good for
* performance, since applying the consent service has performance
* implications.
* 2. It can be used to proactively load consent directives, user
* information, etc. that will be used in future methods.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentStartOperation(theRequestDetails, theUserSession, theContextServices, theClientSession) {
// For superusers, we will skip the rest of the consent service entirely
if (theUserSession != null && theUserSession.hasAuthority('ROLE_SUPERUSER')) {
theContextServices.authorized();
return;
}
// By default, this request should continue but still be evaluated by the service
theContextServices.proceed();
}
/**
* If present, this function is called before every resource that may be returned
* to the user.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @package theResource The resource that will be accessed.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentCanSeeResource(theRequestDetails, theUserSession, theContextServices, theResource, theClientSession) {
if (theResource.meta.hasSecurity('https://www.hl7.org/fhir/v3/Confidentiality/cs.html', 'V')) {
// Any resources with a security label of "V" (very restricted) is rejected,
// meaning that the client doesn't see them and doesn't even know that they
// exist
theContextServices.reject();
} else if (theResource.meta.hasSecurity('https://www.hl7.org/fhir/v3/Confidentiality/cs.html', 'R')) {
// Any resources with a security label of "R" (restricted) is allowed to
// proceed, but will still pass through consentWillSeeResource(...) for
// filtering
theContextServices.proceed();
} else {
// Any other resources are authorized, meaning that the client will get
// to see the resources, and consentWillSeeResource(...) is not called. This
// is good for performance but means that no filtering can take place.
theContextServices.authorized();
}
}
/**
* If present, this function is called before every resource that will be
* shown to the user.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @package theResource The resource that will be accessed.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentWillSeeResource(theRequestDetails, theUserSession, theContextServices, theResource, theClientSession) {
// For Observation resources with a confidentiality code of "R" (restricted),
// we will strip the value and notes from what the user will see
if (theResource.meta.hasSecurity('https://www.hl7.org/fhir/v3/Confidentiality/cs.html', 'R')) {
if (theResource.resourceType === 'Observation') {
theResource.clear('value');
theResource.clear('note');
}
}
// Let the user see the resource
theContextServices.proceed();
}
Another approach to applying consent rules involves using rules based on OpenID Connect Scopes. In this example, a custom scope is defined in the OIDC Client Definition. Unless the application explicitly requests this scope, and the user has approved it, the application will not be able to access SARS-COV-2 Serum/Plasma test results.
The custom scope is named observation_view_covid19. See Custom Scopes Example for more information on how to define this scope and request user approval for it.
/**
* If present, this function is called before every resource that may be returned
* to the user.
*
* @param theRequestDetails Contains details about the request (e.g. the
* FHIR operation being performed, the HTTP method,
* the URL, etc.
* @param theUserSession Contains details about the logged in user and
* their session.
* @param theContextServices Contains various utility methods for accessing
* relevant information about the request, as well
* as providing a response.
* @package theResource The resource that will be accessed.
* @param theClientSession Contains details about the OIDC client and
* their OAuth2 session.
*/
function consentCanSeeResource(theRequestDetails, theUserSession, theContextServices, theResource, theClientSession) {
// In this example, we are applying consent rules only to Observation resources
if (theResource.resourceType === 'Observation') {
let resourceSystem = theResource.code.coding[0].system;
let resourceCode = theResource.code.coding[0].code;
// Any non-LOINC coded Observations will be allowed
if (resourceSystem !== 'http://loinc.org') {
theContextServices.authorized();
return;
}
// The LOINC code 94767-1 corresponds to a SARS-COV-2 Serum/Plasma test. Unless the session
// has an appropriate scope approved, we'll filter this result.
if (resourceCode === '94767-1') {
let approvedScopes = theRequestDetails.approvedScopes;
if (!approvedScopes.contains('observation_view_covid19')) {
theContextServices.reject();
return;
}
}
}
// Any other resources are authorized, meaning that the client will get
// to see the resources, and consentWillSeeResource(...) is not called. This
// is good for performance but means that no filtering can take place.
theContextServices.authorized();
}