smart_app_launch_test_kit 0.5.1 → 0.6.1

data/lib/smart_app_launch/client_suite/client_access_interaction_test.rb

@@ -0,0 +1,64 @@
+require_relative '../urls'
+require_relative '../endpoints/mock_smart_server'
+
+module SMARTAppLaunch
+  class SMARTClientAccessInteraction < Inferno::Test
+    include URLs
+
+    id :smart_client_access_interaction
+    title 'Perform SMART-secured Access'
+    description %(
+      During this test, Inferno will wait for the client to access data
+      using a SMART token obtained during earlier tests.
+    )
+    input :client_id,
+          title: 'Client Id',
+          type: 'text',
+          locked: true,
+          description: %(
+            The registered Client Id for use in obtaining access tokens.
+            Create a new session if you need to change this value.
+          )
+    input :smart_jwk_set,
+          title: 'JSON Web Key Set (JWKS)',
+          type: 'textarea',
+          optional: true,
+          locked: true,
+          description: %(
+            The SMART client's JSON Web Key Set in the form of either a publicly accessible url
+            containing the JWKS, or the raw JWKS JSON. Must include the key(s) Inferno will need to
+            verify signatures on token requests made by the client.
+            Create a new session if you need to change this value.
+          )
+    input :echoed_fhir_response,
+          title: 'FHIR Response to Echo',
+          type: 'textarea',
+          description: %(
+            JSON representation of a FHIR resource for Inferno to echo when a request
+            is made to the simulated FHIR server. The provided content will be echoed
+            back exactly and no check will be made that it is appropriate for the request
+            made. If nothing is provided, an OperationOutcome will be returned.
+          ),
+          optional: true
+
+    run do
+      wait(
+        identifier: client_id,
+        message: %(
+            **Access**
+
+            Use the registered client id (#{client_id}) to obtain an access
+            token using SMART Backend Services
+            and use that token to access a FHIR endpoint under the simulated server's base URL
+
+            `#{client_fhir_base_url}`
+
+            Inferno will echo the response provided in the **FHIR Response to Echo** input.
+
+            [Click here](#{client_resume_pass_url}?token=#{client_id}) once you performed
+            the access.
+          )
+      )
+    end
+  end
+end

data/lib/smart_app_launch/client_suite/client_registration_group.rb

@@ -0,0 +1,15 @@
+require_relative 'client_registration_verification_test'
+
+module SMARTAppLaunch
+  class SMARTClientRegistration < Inferno::TestGroup
+    id :smart_client_registration
+    title 'Client Registration'
+    description %(
+      During these tests, Inferno will verify the registration details provided as inputs,
+      including the client's JSON Web Key Set.
+    )
+    run_as_group
+
+    test from: :smart_client_registration_verification
+  end
+end

data/lib/smart_app_launch/client_suite/client_registration_verification_test.rb

@@ -0,0 +1,52 @@
+require_relative '../tags'
+require_relative '../endpoints/mock_smart_server'
+
+module SMARTAppLaunch
+  class SMARTClientRegistrationVerification < Inferno::Test
+
+    id :smart_client_registration_verification
+    title 'Verify SMART Registration'
+    description %(
+      During this test, Inferno will verify that the SMART registration details
+      provided are conformant.
+    )
+    input :smart_jwk_set,
+          title: 'SMART JSON Web Key Set (JWKS)',
+          type: 'textarea',
+          description: %(
+            The SMART client's JSON Web Key Set including the key(s) Inferno will need to
+            verify signatures on token requests made by the client. May be provided as either
+            a publicly accessible url containing the JWKS, or the raw JWKS JSON.
+          )
+    input :client_id,
+          title: 'Client Id',
+          type: 'text',
+          optional: true,
+          description: %(
+            If a particular client id is desired, put it here. Otherwise a
+            default of the Inferno session id will be used.
+          )
+
+    output :client_id
+
+    run do
+      omit_if smart_jwk_set.blank?, # for re-use: mark the smart_jwk_set input as optional when importing to enable
+        'Not configured for SMART authentication.'
+
+      if client_id.blank?
+        client_id = test_session_id
+        output(client_id:)
+      end
+
+      jwks_warnings = []
+      parsed_smart_jwk_set = MockSMARTServer.jwk_set(smart_jwk_set, jwks_warnings)
+      jwks_warnings.each { |warning| add_message('warning', warning) }
+
+      assert parsed_smart_jwk_set.length.positive?, 'JWKS content does not include any valid keys.'
+
+      # TODO: add key-specific verification per end of https://build.fhir.org/ig/HL7/smart-app-launch/client-confidential-asymmetric.html#registering-a-client-communicating-public-keys
+
+      assert messages.none? { |msg| msg[:type] == 'error' }, 'Invalid key set provided. See messages for details'
+    end
+  end
+end

data/lib/smart_app_launch/client_suite/client_token_request_verification_test.rb

@@ -0,0 +1,146 @@
+require_relative '../tags'
+require_relative '../urls'
+require_relative '../endpoints/mock_smart_server'
+
+module SMARTAppLaunch
+  class SMARTClientTokenRequestVerification < Inferno::Test
+    include URLs
+
+    id :smart_client_token_request_verification
+    title 'Verify SMART Token Requests'
+    description %(
+        Check that SMART token requests are conformant.
+      )
+
+    input :client_id,
+          title: 'Client Id',
+          type: 'text',
+          optional: false,
+          locked: true,
+          description: %(
+            The registered Client Id for use in obtaining access tokens.
+            Create a new session if you need to change this value.
+          )
+    input :smart_jwk_set,
+          title: 'JSON Web Key Set (JWKS)',
+          type: 'textarea',
+          optional: false,
+          locked: true,
+          description: %(
+            The SMART client's JSON Web Key Set in the form of either a publicly accessible url
+            containing the JWKS, or the raw JWKS JSON. Must include the key(s) Inferno will need to
+            verify signatures on token requests made by the client.
+            Create a new session if you need to change this value.
+          )
+    output :smart_tokens
+
+    run do
+      omit_if smart_jwk_set.blank?, # for re-use: mark the smart_jwk_set input as optional when importing to enable
+              'SMART Backend Services authentication not demonstrated as a part of this test session.'
+
+      load_tagged_requests(TOKEN_TAG, SMART_TAG)
+      skip_if requests.blank?, 'No SMART token requests made.'
+
+      jti_list = []
+      token_list = []
+      requests.each_with_index do |token_request, index|
+        request_params = URI.decode_www_form(token_request.request_body).to_h
+        check_request_params(request_params, index + 1)
+        check_client_assertion(request_params['client_assertion'], index + 1, jti_list)
+        token_list << extract_token_from_response(token_request)
+      end
+
+      output smart_tokens: token_list.compact.join("\n")
+
+      assert messages.none? { |msg|
+        msg[:type] == 'error'
+      }, 'Invalid token requests detected. See messages for details.'
+    end
+
+    def check_request_params(params, request_num)
+      if params['grant_type'] != 'client_credentials'
+        add_message('error',
+                    "Token request #{request_num} had an incorrect `grant_type`: expected 'client_credentials', " \
+                    "but got '#{params['grant_type']}'")
+      end
+      if params['client_assertion_type'] != 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+        add_message('error',
+                    "Token request #{request_num} had an incorrect `client_assertion_type`: " \
+                    "expected 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer', " \
+                    "but got '#{params['client_assertion_type']}'")
+      end
+      return unless params['scope'].blank?
+
+      add_message('error', "Token request #{request_num} did not include the requested `scope`")
+    end
+
+    def check_client_assertion(assertion, request_num, jti_list)
+      decoded_token =
+        begin
+          JWT::EncodedToken.new(assertion)
+        rescue StandardError => e
+          add_message('error', "Token request #{request_num} contained an invalid client assertion jwt: #{e}")
+          nil
+        end
+
+      return unless decoded_token.present?
+
+      check_jwt_header(decoded_token.header, request_num)
+      check_jwt_payload(decoded_token.payload, request_num, jti_list)
+      check_jwt_signature(decoded_token, request_num)
+    end
+
+    def check_jwt_header(header, request_num)
+      return unless header['typ'] != 'JWT'
+
+      add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `typ` header: " \
+                           "expected 'JWT', got '#{header['typ']}'")
+    end
+
+    def check_jwt_payload(claims, request_num, jti_list)
+      if claims['iss'] != client_id
+        add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `iss` claim: " \
+                             "expected '#{client_id}', got '#{claims['iss']}'")
+      end
+
+      if claims['sub'] != client_id
+        add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `sub` claim: " \
+                             "expected '#{client_id}', got '#{claims['sub']}'")
+      end
+
+      if claims['aud'] != client_token_url
+        add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `aud` claim: " \
+                             "expected '#{client_token_url}', got '#{claims['aud']}'")
+      end
+
+      if claims['exp'].blank?
+        add_message('error', "client assertion jwt on token request #{request_num} is missing the `exp` claim.")
+      end
+
+      if claims['jti'].blank?
+        add_message('error', "client assertion jwt on token request #{request_num} is missing the `jti` claim.")
+      elsif jti_list.include?(claims['jti'])
+        add_message('error', "client assertion jwt on token request #{request_num} has a `jti` claim that was " \
+                             "previouly used: '#{claims['jti']}'.")
+      else
+        jti_list << claims['jti']
+      end
+    end
+
+    def check_jwt_signature(encoded_token, request_num)
+      error = MockSMARTServer.smart_assertion_signature_verification(encoded_token, smart_jwk_set)
+
+      return unless error.present?
+
+      add_message('error', "Signature validation failed on token request #{request_num}: #{error}")
+    end
+
+    def extract_token_from_response(request)
+      return unless request.status == 200
+
+      JSON.parse(request.response_body)&.dig('access_token')
+    rescue
+      nil
+    end
+  end
+end

data/lib/smart_app_launch/client_suite/client_token_use_verification_test.rb

@@ -0,0 +1,47 @@
+require_relative '../tags'
+require_relative '../endpoints/mock_smart_server'
+
+module SMARTAppLaunch
+  class SMARTClientTokenUseVerification < Inferno::Test
+
+    id :smart_client_token_use_verification
+    title 'Verify SMART Token Use'
+    description %(
+        Check that a SMART token returned to the client was used for request
+        authentication.
+      )
+
+    input :smart_tokens,
+          optional: true # verified in the test to return a more specific error message
+    input :smart_jwk_set,
+          optional: false,
+          locked: true
+
+    def access_request_tags
+      return config.options[:access_request_tags] if config.options[:access_request_tags].present?
+
+      [ACCESS_TAG]
+    end
+
+    run do
+      omit_if smart_jwk_set.blank?, # for re-use: mark the smart_jwk_set input as optional when importing to enable
+        'SMART Authentication not demonstrated as a part of this test session.'
+
+      access_requests = access_request_tags.map do |access_request_tag|
+        load_tagged_requests(access_request_tag).reject { |access| access.status == 401 }
+      end.flatten
+      obtained_tokens = smart_tokens&.split("\n")
+
+      skip_if obtained_tokens.blank?, 'No token requests made.'
+      skip_if access_requests.blank?, 'No successful access requests made.'
+
+      used_tokens = access_requests.map do |access_request|
+        access_request.request_headers.find do |header|
+          header.name.downcase == 'authorization'
+        end&.value&.delete_prefix('Bearer ')
+      end.compact
+
+      assert (used_tokens & obtained_tokens).present?, 'Returned tokens never used in any requests.'
+    end
+  end
+end

data/lib/smart_app_launch/cors_openid_fhir_user_claim_test.rb

@@ -16,11 +16,11 @@ module SMARTAppLaunch
     optional
 
     input :url, :id_token_fhir_user
-    input :smart_credentials, type: :oauth_credentials
+    input :smart_auth_info, type: :auth_info
 
     fhir_client do
       url :url
-      oauth_credentials :smart_credentials
+      auth_info :smart_auth_info
       headers 'Origin' => Inferno::Application['inferno_host']
     end
 

data/lib/smart_app_launch/cors_token_exchange_test.rb

@@ -15,10 +15,10 @@ module SMARTAppLaunch
 
     uses_request :cors_token_request
 
-    input :client_auth_type
+    input :smart_auth_info, type: :auth_info, options: { mode: 'auth' }
 
     run do
-      omit_if client_auth_type != 'public', %(
+      omit_if smart_auth_info.auth_type != 'public', %(
         Client type is not public, Cross-Origin Resource Sharing (CORS) is not required to be supported for
         non-public client types
       )

data/lib/smart_app_launch/discovery_stu1_group.rb

@@ -40,8 +40,12 @@ module SMARTAppLaunch
       * [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
     )
 
-    test from: :well_known_endpoint,
-         id: 'Test01'
+    test from: :well_known_endpoint do
+      id 'Test01'
+      input :smart_auth_info,
+            type: :auth_info
+    end
+
     test from: :well_known_capabilities_stu1,
          id: 'Test02'
 

data/lib/smart_app_launch/docs/demo/FHIR Request.postman_collection.json

@@ -0,0 +1,81 @@
+{
+	"info": {
+		"_postman_id": "22f52416-c6ae-4ffc-a388-54616465d149",
+		"name": "FHIR Request",
+		"description": "Make a simple FHIR request with a specific bearer token. Useful for security client tests like SMART and UDAP.\n\n- base_url: points to a running instance of inferno. Typical values will be\n    \n    - Inferno production: [https://inferno.healthit.gov/suites](https://inferno.healthit.gov/suites)\n        \n    - Inferno QA: [https://inferno-qa.healthit.gov/suites](https://inferno-qa.healthit.gov/suites)\n        \n    - Local docker: [http://localhost](http://localhost)\n        \n    - Local development: [http://localhost:4567](http://localhost:4567)",
+		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+		"_exporter_id": "32597978"
+	},
+	"item": [
+		{
+			"name": "Patient Read",
+			"request": {
+				"auth": {
+					"type": "bearer",
+					"bearer": [
+						{
+							"key": "token",
+							"value": "{{bearer_token}}",
+							"type": "string"
+						}
+					]
+				},
+				"method": "GET",
+				"header": [],
+				"url": {
+					"raw": "{{base_url}}/custom/{{target_suite}}/fhir/Patient/example",
+					"host": [
+						"{{base_url}}"
+					],
+					"path": [
+						"custom",
+						"{{target_suite}}",
+						"fhir",
+						"Patient",
+						"example"
+					]
+				}
+			},
+			"response": []
+		}
+	],
+	"event": [
+		{
+			"listen": "prerequest",
+			"script": {
+				"type": "text/javascript",
+				"packages": {},
+				"exec": [
+					""
+				]
+			}
+		},
+		{
+			"listen": "test",
+			"script": {
+				"type": "text/javascript",
+				"packages": {},
+				"exec": [
+					""
+				]
+			}
+		}
+	],
+	"variable": [
+		{
+			"key": "base_url",
+			"value": "https://inferno.healthit.gov/suites",
+			"type": "string"
+		},
+		{
+			"key": "target_suite",
+			"value": "smart_client_stu2_2",
+			"type": "string"
+		},
+		{
+			"key": "bearer_token",
+			"value": "",
+			"type": "string"
+		}
+	]
+}

data/lib/smart_app_launch/docs/smart_stu2_2_client_suite_description.md

@@ -0,0 +1,121 @@
+## Overview
+
+The SMART App Launch STU 2.2 Client Test Suite verifies the conformance of
+client systems to the STU 2.2.0 version of the HL7® FHIR®
+[SMART App Launch IG](https://hl7.org/fhir/smart-app-launch/STU2.2/).
+
+## Scope
+
+The SMART App Launch Client Test Suite verifies that systems correctly implement
+the [SMART App Launch IG](http://hl7.org/fhir/smart-app-launch/STU2.2/)
+for authorizating and/or authenticating with a server in order to gain 
+access to HL7® FHIR® APIs. At this time, the suite only contains tests for
+the [Backend Services](https://hl7.org/fhir/smart-app-launch/STU2.2/backend-services.html)
+flow.
+
+These tests are a **DRAFT** intended to allow implementers to perform
+preliminary checks of their systems against SMART requirements and 
+[provide feedback](https://github.com/inferno-framework/smart-app-launch-test-kit/issues)
+on the tests. Future versions of these tests may verify other
+requirements and may change the test verification logic.
+
+## Test Methodology
+
+For these tests Inferno simulates a SMART server that supports the backend services
+flow. Testers will
+1. Provide registration details as inputs, including a JSON Web Key Set (JWKS)
+   an optionally a client id if a specific one should be used.
+2. Request an access token using the registered JWKS and client id.
+3. Use that access token on a FHIR API request.
+
+The simulated server is relatively permissive in the sense that it will often
+provide successful responses even when the request is not conformant. When
+requesting tokens, Inferno will return an access token as long as it can find
+the client id and the signature is valid. This allows incomplete systems to
+run the tests. However, these non-conformant requests will be flagged by
+the tests as failures so that systems will not pass the tests without being
+fully conformant.
+
+## Running the Tests
+
+### Quick Start
+
+The following inputs must be provided by the tester at a minimum to execute
+any tests in this suite:
+1. **SMART JSON Web Key Set (JWKS)**: The SMART client's public JSON Web Key Set including
+   key(s) that Inferno will use to verify the signature on incoming token requests. May
+   be provided as either a publicly accessible url containing the JWKS, or the raw JWKS.
+
+The *Additional Inputs* section below describes options available to customize
+the behavior of Inferno's server simulation.
+
+### Demonstration
+
+To try out these tests without a SMART client implementation, these tests can be exercised
+using the SMART App Launch server test suite and a simple HTTP request generator. The following
+steps use [Postman](https://www.postman.com/) to generate the access request using 
+[this collection](https://github.com/inferno-framework/smart-app-launch-test-kit/blob/main/lib/smart_app_launch/docs/demo/FHIR%20Request.postman_collection.json). Install the app and import the collection before following these
+steps.
+
+1. Start an instance of the SMART App Launch STU2.2 Client test suite.
+2. From the drop down in the upper left, select preset "Demo: Run Against the SMART Server Suite".
+3. Click the "RUN ALL TESTS" button in the upper right and click "SUBMIT"
+4. In a new tab, start an instance of the SMART App Launch STU2.2 Test Suite
+5. From the drop down in the upper left, select preset "Demo: Run Against the SMART Client Suite"
+6. Select test group **3** Backend Services from the left panel, click the "RUN TESTS" button
+   in the upper right, and click "SUBMIT"
+7. Find the access token to use for the data access request by opening test **3.2.05** Authorization
+   request succeeds when supplied correct information, click on the "REQUESTS" tab, clicking on the "DETAILS"
+   button, and expanding the "Response Body". Copy the "access_token" value, which will be a ~100 character
+   string of letters and numbers (e.g., eyJjbGllbnRfaWQiOiJzbWFydF9jbGllbnRfdGVzdF9kZW1vIiwiZXhwaXJhdGlvbiI6MTc0MzUxNDk4Mywibm9uY2UiOiJlZDI5MWIwNmZhMTE4OTc4In0)
+8. Open Postman and open the "FHIR Request" Collection. Click the "Variables" tab and add the copied access token
+   as the current value of the `bearer_token` variable. Also update the
+   `base_url` value for where the test is running (see details on the "Overview" tab).
+   Save the collection.
+9. Select the "Patient Read" request and click "Send". A FHIR Patient resource should be returned.
+10. Return to the client tests and click the link to continue and complete the tests.
+
+The client tests should pass with the exception of test **1.2.02** Verify SMART Token Requests. This is
+expected as the Server tests make several intentionally invalid token requests. Inferno's simulated SMART
+server responds successfully to those requests when the client id can be identified, but flags them as
+not conformant causing these expected failures. Because responding with an access token to non-conformant
+token requests is itself not conformant there are corresponding failures on the server test in tests **3.2.02**,
+**3.2.04**, and **3.2.04**. There may be other SMART server test failures due to an assumption that
+servers support the app launch capabilities in addition to backend services.
+
+### Additional Inputs
+
+Two additional inputs are available to support testers 
+- **Client Id**: Testers may specify a client id for Inferno to use for the test session if they
+  have one already configured.
+- **FHIR Response to Echo**: The focus of this test kit is on the auth protocol, so the
+  simulated FHIR server implemented in this test suite is very simple and will by default
+  return a FHIR OperationOutcome to any request made. Testers may provide a static
+  FHIR JSON body for Inferno to return instead. In this case, the simulation is a simple
+  echo and Inferno does not check that the response if appropriate for the request made.
+
+## Current Limitations
+
+This test kit is still in draft form and does not test all of the requirements and features
+described in the SMART App Launch IG for clients. Notably, only the backend services flow
+is tested at this time.
+
+The following sections list other known gaps and limitations.
+
+### SMART Server Simulation Limitations
+
+This test suite contains a simulation of a SMART Backend Services server which is not fully
+general and not all conformant clients may be able to interact with it. However, the intention
+is not to prevent systems from passing for making conformant choices that Inferno's simulation
+does not support. One specific example is that the SMART configuration metadata available at
+`.well-known/smart-configuration` for the simulated server is fixed and cannot be changed by
+testers at this time. Please report any issues that prevent conformant systems from passing in
+the [github repository's issues page](https://github.com/inferno-framework/smart-app-launch-test-kit/issues/).
+
+### FHIR Server Simulation Limitations
+
+The FHIR server simulation used to support clients in demonstrating their ability to access
+FHIR APIs using access tokens obtained using the SMART flows is very limited. Testers are currently
+able to provide a single static response that will be echoed for any FHIR request made. While
+Inferno will never implement a fully general FHIR server simulation, additional options may be added
+in the future based on community feedback.