Follow the specs more closely, switch to JWTs.jl, and fix the tests

[devmotion]

This is a larger PR that extends #8:

• The package follows the specs (https://hl7.org/fhir/smart-app-launch/backend-services.html) more closely: Token endpoint is retrieved from the server configuration available at .well-known/smart-configuration (instead users have to specify the arguably more intuitive base URL of the server), iss and sub are enforced to be the same client_id, and it is mandatory to specify the scope
• The package is switched to JWTs.jl which, in contrast to JSONWebTokens.jl, already supports header claims required by the specs
• The PR fixes the tests with the public SMART test server (and adds documentation)

Tests fail currently due to tanmaykm/JWTs.jl#25: https://github.com/JuliaHealth/SMARTBackendServices.jl/actions/runs/7563819763/job/20596913050?pr=9#step:6:128

With the fix in tanmaykm/JWTs.jl#25, tests pass locally.

[DilumAluthge]

So, if I recall correctly, not all servers support /.well-known/smart-configuration. So I think we should first check /.well-known/smart-configuration, but if that doesn't exist (or if it exists but we can't extract all of the required info), we should still fallback to checking /metadata.

[devmotion]

I could not find the metadata endpoint in the specification (only in Epic-internal docs) whereas .well-known/smart-configuration is explicitly documented and part of the suggested implementation: https://hl7.org/fhir/smart-app-launch/backend-services.html#top-level-steps-for-backend-services-authorization (Therefore I think we should also use it rather than metadata in the EHR Launch implementation.)

[DilumAluthge]

I could not find the metadata endpoint in the specification

For the /metadata endpoint in general, the spec is here:

1. FHIR 4.0.1: https://hl7.org/fhir/R4/http.html#capabilities
2. FHIR 5.0.0: https://hl7.org/fhir/R5/http.html#capabilities
3. CI build of FHIR: https://build.fhir.org/http.html#capabilities

For the CapabilityStatement (which is the resource type returned by the /metadata endpoint), the spec is here:

1. FHIR 4.0.1: https://hl7.org/fhir/R4/capabilitystatement.html
2. FHIR 5.0.0: https://hl7.org/fhir/R5/capabilitystatement.html
3. CI build of FHIR: https://build.fhir.org/capabilitystatement.html

For the specific use of the CapabilityStatement in SMART App Launch, you can look at historical versions of the relevant IGs (implementation guides), such as:

1. SMART App Launch: https://hl7.org/fhir/smart-app-launch/2021May/ (based on FHIR R4)

The reality is that there are still R4 systems out there in the wild that only support /metadata and don't support well-known, so I do think that we need to continue using /metadata as a fallback, at least for the foreseeable future.

[devmotion]

For the specific use of the CapabilityStatement in SMART App Launch, you can look at historical versions of the relevant IGs (implementation guides), such as:

1. SMART App Launch: https://hl7.org/fhir/smart-app-launch/2021May/ (based on FHIR R4)

Even in this document the .well-known/smart-configuration endpoint is mentioned. In fact, it seems that already since version 1.0.0 (from 2018, based on R3) the specification requires that this endpoint exists and reports the token_endpoint: https://hl7.org/fhir/smart-app-launch/1.0.0/conformance/index.html#using-well-known

The reality is that there are still R4 systems out there in the wild that only support /metadata and don't support well-known, so I do think that we need to continue using /metadata as a fallback, at least for the foreseeable future.

I'm sure you have better experience with these systems, so maybe that's what we have to do regardless of the specifications.

[codecov]

Codecov Report

Attention: 4 lines in your changes are missing coverage. Please review.

Comparison is base (465e6ad) 100.00% compared to head (337cccb) 94.20%.

Files	Patch %	Lines
src/backend_services.jl	90.90%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##            master       #9      +/-   ##
===========================================
- Coverage   100.00%   94.20%   -5.80%     
===========================================
  Files            5        4       -1     
  Lines           38       69      +31     
===========================================
+ Hits            38       65      +27     
- Misses           0        4       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[devmotion]

@DilumAluthge the PR is ready for a re-review, I added a fallback with the metadata endpoint and a test for it.

[DilumAluthge]

Should we use struct-mapping instead?

[devmotion]

My initial implementation used struct mapping but it felt a bit too verbose since it requires a struct for every level of this nested structure.

[DilumAluthge]

@devmotion Looks like you need some tests to increase code coverage, and then we're good to go here?

[devmotion]

I had checked the codecov analysis and I think there's not much nothing we can improve unfortunately:

• https://app.codecov.io/gh/JuliaHealth/SMARTBackendServices.jl/pull/9?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=checks&utm_campaign=pr+comments&utm_term=JuliaHealth#0aad7972eace7a7df65936f12d25c885-R53 and https://app.codecov.io/gh/JuliaHealth/SMARTBackendServices.jl/pull/9?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=checks&utm_campaign=pr+comments&utm_term=JuliaHealth#0aad7972eace7a7df65936f12d25c885-R105 can't be tested without a server that violates the FHIR specifications
• https://app.codecov.io/gh/JuliaHealth/SMARTBackendServices.jl/pull/9?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=checks&utm_campaign=pr+comments&utm_term=JuliaHealth#0aad7972eace7a7df65936f12d25c885-R99 and https://app.codecov.io/gh/JuliaHealth/SMARTBackendServices.jl/pull/9?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=checks&utm_campaign=pr+comments&utm_term=JuliaHealth#0aad7972eace7a7df65936f12d25c885-R102 seem wrong since we test the metadata endpoint (including the for-loop here, as indicated by the coverage of the lines just above)

[DilumAluthge]

I've removed Codecov from the list of required checks.