Skip to content

Home

Jump to bottom
blangley28 edited this page Jun 21, 2021 · 7 revisions

Welcome to the cpcds-server-ri wiki!

Getting Started (Connectathon)

If you are looking to connect to this server see the Connectathon README Wiki Page.

Getting Started (Code Developer)

This repo is built onto of the HAPI FHIR JPA server. It then adds a couple of additional features:

  1. SMART on FHIR Authorization server
  2. SMART on FHIR Patient Authorization Interceptor
  3. SMART on FHIR .well-known/smart-configuration file
  4. ReadOnlyInterceptor
  5. SearchInterceptor
  6. Debug endpoints

You may also care to view the CPCDS Postman Collection

Note about versions

There are a couple branches with the same "base" code but to support different versions. There are differences in the code based on capability statement but the majority of it is the same. These different branches are then also loaded with different data. These branches are 1.1.0, stu2, and patient-access.

SMART on FHIR Authorization server

The ca.uhn.fhir.jpa.starter.authorization package contains a very basic OAuth server. It includes functionality for token introspection, client registration, user registration, and OAuth 2.0 authorization_code grant flow (token and authorize endpoints). You can learn more about the endpoints here and more about the OAuth flow here or from the SMART on FHIR IG.

This authorization server uses a SQL database to store users and clients. This is exposed in the debug endpoint. A homegrown auth server was built here instead of using a 3rd party identity provider because the SMART on FHIR flow includes non-standard patient context details. This would require proxying requests to the identity server. For production systems it is not recommended to use this authorization server.

The configuration for these endpoints is found in src/main/webapp/WEB-INF/web.xml.

SMART on FHIR PatientAuthorizationInterceptor

The PatientAuthorizationInterceptor checks the access token on every request to determine what resources the request will have access to. There are 4 rules here:

  1. If the token is the admin token (from environment variable ADMIN_TOKEN), then the user has access to everything (all CRUD operations on all resources).
  2. If the token is valid and the patientId claim is "admin" then the user has access to read all of the resources.
  3. If the token is valid then the user has access to specific resources within their compartment and non-personalized resources (i.e. Organization or MedicationKnowledge).
  4. Otherwise, the only FHIR endpoint available is the metadata.

SMART on FHIR .well-known/smart-configuration file

To support the SMART on FHIR spec a .well-known/smart-configuration file is hosted. The configuration for this endpoint is found in src/main/webapp/WEB-INF/web.xml. The controller is found in the ca.uhn.fhir.jpa.starter.wellknown package.

Note: the Metadata.java file also includes the authorization details.

ReadOnlyInterceptor

By default the server is read only (unless you use the ADMIN_TOKEN).

SearchInterceptor

By default the server only allows requests marked as SHALL by the implementation guide capability statement (unless you use the ADMIN_TOKEN).

Note: the Metadata.java file also includes which search parameters, profiles, and interactions are supported.

Debug endpoints

The ca.uhn.fhir.jpa.starter.debug package contains endpoints for debug use. They include:

  • /Clients to get a webpage view of the Clients table in the authorization server
  • /Users to get a webpage view of the Users table in the authorization server
  • /Log to get the raw text of the logs
  • /UpdateClient?client_id={id} to PUT a client.
{
    "id": "{id}",
    "secret": "{secret}",
    "redirectUri": "{redirect uri}"
}

This last request is helpful in connectathons since everytime the server is restarted the clients table is not persisted. As such instead of making clients re-register and obtain new credentials everytime you can add the client back with the same details as before.

Clone this wiki locally