Skip to main content

Authorization

Pathling can perform the role of a resource server within the OpenID Connect framework.

When authorization is enabled through configuration, Pathling will refuse any requests which are not accompanied by a valid bearer token. The following requirements must be met:

Authorities

Pathling supports a set of authorities that control access to resources and operations. Authorities must be provided within the authorities claim within the JWT bearer token provided with each request.

Authorities Authorities

AuthorityDescription
pathlingProvides access to all operations and resources, implies all other authorities.
pathling:readProvides read access to all resource types.
pathling:read:[resource type]Provides read access to only a specified resource type.
pathling:writeProvides write access to all resource types.
pathling:write:[resource type]Provides write access to only a specified resource type.
pathling:importProvides access to the import operation.
pathling:aggregateProvides access to the aggregate operation.
pathling:searchProvides access to the search operation.
pathling:extractProvides access to the extract operation.
pathling:updateProvides access to the update operation.
pathling:batchProvides access to the batch operation.

In order to enable access to an operation, an operation authority (e.g. pathling:search) must be provided along with a read or write authority (e.g. pathling:read:Patient).

Where expressions within a request reference multiple different resource types (e.g. through resource references), authority for read access to all those resources must be present within the token.

The import and batch operations require write authority for all resource types that are referenced within the request.

GA4GH passports

Pathling supports an opt-in implementation of GA4GH Passport v1 , which is a way of encoding permission to access patient data within the access token presented to the server.

You can enable GA4GH passport authentication by enabling the ga4gh Spring profile when running Pathling. Note that this profile is not enabled by default, and is not enabled within the pre-built Docker image.

The Pathling implementation supports a visa type of ControlledAccessGrants, with a value that is interpreted as a dataset ID.

The issuer and the dataset ID are used to construct a URL of the form [issuer]/api/manifest/[dataset ID], which is used to retrieve a manifest document. The manifest contains additional information on how to enforce permissions for the visa.

The manifest document is expected to take the following form:

{
"patientIds": [
"patient-1",
"patient-2",
...
]
}

The patient IDs are combined with the pathling.auth.ga4ghPassports.patientIdSystem configuration parameter to create FHIR identifiers that Pathling can match against resources in the database.

When running with GA4GH passports enabled, all queries will be scoped to return only records that relate to white-listed patients, according to the joining logic defined within the FHIR Patient compartment .

The presence of a ControlledAccessGrants visa implies the following authorities within Pathling: pathling:aggregate, pathling:search, pathling:extract (plus read access to all resources within the Patient compartment).