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:

• Token is a JSON Web Token
• Token contains an audience claim that matches the configured value
• Token contains an issuer claim that matches the configured value
• Issuer provides an OpenID Connect Discovery endpoint that provides information about how to validate the token, including a link to a JSON Web Key Set containing the signing key. This endpoint needs to be accessible to the Pathling server.

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.

→ includes

Note that pathling:read-resource, which gates the read interaction, is an operation authority and so belongs to the pathling:[operation] family above. It is distinct from the pathling:read data authority: neither implies the other, and only the root pathling authority implies both.

Authority	Description
pathling	Provides access to all operations and resources, implies all other authorities.
pathling:read	Provides read access to all resource types.
pathling:read:[resource type]	Provides read access to only a specified resource type.
pathling:write	Provides write access to all resource types.
pathling:write:[resource type]	Provides write access to only a specified resource type.
pathling:read-resource	Provides access to the read interaction.
pathling:import	Provides access to the import operation.
pathling:import-pnp	Provides access to the ping and pull import operation.
pathling:search	Provides access to the search operation.
pathling:create	Provides access to the create operation.
pathling:update	Provides access to the update operation.
pathling:delete	Provides access to the delete operation.
pathling:batch	Provides access to the batch operation.
pathling:bulk-submit	Provides access to the bulk submit operation.
pathling:export	Provides access to the export operation.
pathling:sql-run	Provides access to the $sql-run operation.
pathling:sql-export	Provides access to the $sql-export operation.
pathling:jobs	Provides access to the jobs list 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 read interaction follows this pattern like any other: reading a resource by id requires the pathling:read-resource operation authority, plus read authority for the type being read (pathling:read:[resource type], or pathling:read for all types). A token holding only pathling:read can no longer perform an instance read, which is a breaking change introduced in version 3.0.0 of the server.

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

The SQL on FHIR data operations (sql-run and sql-export) require read authority for the resource type a ViewDefinition subject projects, named in its resource element. For example, a ViewDefinition targeting Patient resources requires pathling:read:Patient authority in addition to the operation authority.

A configured external table referenced as a dependency of a SQL subject requires only the operation authority. It is operator configuration rather than FHIR data, so no resource-type read authority applies to it and none is checked when it is read. The FHIR-backed dependencies alongside it are unaffected: a ViewDefinition or SQLView joined to an external table keeps its own resource-type read requirements, and the storage read checks below.

A value set referenced as a dependency of a SQL subject likewise requires only the operation authority. Its membership comes from the terminology layer, or from a ValueSet supplied in the request's context, rather than from FHIR data held by the server, so no resource-type read authority is checked for it: a token holding pathling:sql-run alone can run a SQLQuery whose only dependency is a value set. The value set neither adds to nor waives the requirements of the dependencies alongside it; a ViewDefinition joined to a value set still requires read authority for the resource type it projects.

A concept map referenced as a dependency of a SQL subject also requires only the operation authority. Its mappings come from the terminology layer, or from a ConceptMap supplied in the request's context, and never from FHIR data held by the server, so no resource-type read authority is checked for it: a token holding pathling:sql-run alone can run a SQLQuery whose only dependency is a concept map. Like a value set, the concept map neither adds to nor waives the requirements of the dependencies alongside it; a ViewDefinition translated through a concept map still requires read authority for the resource type it projects, and a token without the operation authority is refused as for any other request.

Job ownership

Asynchronous jobs are owned by the token subject that started them. When authorisation is enabled, the jobs list operation (pathling:jobs) returns only the caller's own jobs, and both polling a job's status and cancelling it (via GET and DELETE on the job's URL) require the caller to be the job's owner and to hold the authority for the operation that started the job. A request to cancel a job owned by a different subject is refused with an access-denied error and the job is left unaffected.

Reading subjects and dependencies from storage

Resolving a metadata resource from server storage requires read authority on that resource type, in addition to the per-projected-resource checks above:

• Resolving a ViewDefinition from storage requires pathling:read:ViewDefinition. This applies to a subjectCanonical or subjectReference that names one, and to a ViewDefinition referenced as a dependency of a SQL subject.
• Resolving a SQLQuery or SQLView (both Library resources) from storage requires pathling:read:Library. This applies to a subjectCanonical or subjectReference that names one, and to a SQLView referenced as a dependency.

A resource supplied inline in the request body - a subjectResource or a context entry - is not read from storage and is therefore not subject to these metadata read checks, though the per-projected-resource read checks still apply.

SMART configuration

When authorisation is enabled, Pathling exposes a SMART configuration document at /.well-known/smart-configuration. This document advertises the OAuth endpoints and capabilities supported by the server.

Pathling automatically fetches and merges the issuer's OIDC discovery document from {issuer}/.well-known/openid-configuration. Fields from the OIDC discovery document are included in the SMART configuration response, with SMART-specific fields taking precedence. This provides clients with comprehensive metadata about supported scopes, response types, and other OAuth capabilities without requiring explicit configuration.

The following fields can be configured explicitly and will override any values from the OIDC discovery document:

• authorization_endpoint (via pathling.auth.authUrl)
• token_endpoint (via pathling.auth.tokenUrl)
• revocation_endpoint (via pathling.auth.revokeUrl)
• capabilities (via pathling.auth.capabilities)
• grant_types_supported (via pathling.auth.grantTypesSupported)
• code_challenge_methods_supported (via pathling.auth.codeChallengeMethodsSupported)