udap_security_test_kit 0.11.3 → 0.11.4

data/lib/udap_security_test_kit/docs/udap_client_suite_description.md

@@ -9,8 +9,11 @@ client systems to the STU 1.0.0 version of the HL7® FHIR®
 The UDAP Security Client Test Suite verifies that systems correctly implement
 the [UDAP Security IG](https://hl7.org/fhir/us/udap-security/STU1/)
 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 [Business-to-Business Client Credentials flow](https://hl7.org/fhir/us/udap-security/STU1/b2b.html).
+access to HL7® FHIR® APIs. The suite contains options for testing clients that follow the
+- Authorization Code flow for [consumer facing](https://hl7.org/fhir/us/udap-security/STU1/consumer.html)
+  or [Business-to-Business](https://hl7.org/fhir/us/udap-security/STU1/b2b.html) access.
+- Client Credentials flow for [Business-to-Business](https://hl7.org/fhir/us/udap-security/STU1/b2b.html)
+  access.
 
 These tests are a **DRAFT** intended to allow implementers to perform
 preliminary checks of their systems against UDAP Security IG
@@ -20,8 +23,8 @@ requirements and may change the test verification logic.
 
 ## Test Methodology
 
-For these tests Inferno simulates a UDAP server that supports the business-to-business
-client credentials flow. Testers will
+For these tests Inferno simulates a UDAP server that supports both the authorization code
+and the client credentials flows. In both cases, testers will
 1. Provide to Inferno the client URI with which they will register their system.
 2. Make a dynamic registration request to Inferno using the provided client URI
    and including the X.509 certificate used to sign the registeration and subsequent
@@ -59,24 +62,26 @@ steps use [Postman](https://www.postman.com/) to generate the access request usi
 [this collection](https://github.com/inferno-framework/udap-security-test-kit/blob/main/lib/udap_security_test_kit/docs/demo/FHIR%20Request.postman_collection.json).
 Install the app and import the collection before following these steps.
 
-1. Start an instance of the UDAP Security Client test suite.
-2. From the drop down in the upper left, select preset "Demo: Run Against the UDAP Security 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 UDAP Security Server Test Suite
-5. From the drop down in the upper left, select preset "Demo: Run Against the UDAP Security Client Suite"
-6. Select test group **2** UDAP Client Credentials Flow from the left panel, click the "RUN ALL TESTS" button
-   in the upper right, and click "SUBMIT"
-7. In the Client suite tab, click the link in the wait dialog to continue the tests.
-8. In the Server suite tab, find the access token to use for the data access request by opening
-   test **2.3.01** OAuth token exchange request succeeds when supplied correct information, click
-   on the "REQUESTS" tab, clicking on the "DETAILS" button, and expanding the "Response Body".
+1. Start an instance of the UDAP Security Client test suite and choose either option: *Authorization Code*,
+   or *Client Credentials* flow. Remember your choice for use later.
+1. From the drop down in the upper left, select preset "Demo: Run Against the UDAP Security Server Suite".
+1. Click the "RUN ALL TESTS" button in the upper right and click "SUBMIT"
+1. In a new tab, start an instance of the UDAP Security Server Test Suite
+1. From the drop down in the upper left, select preset "Demo: Run Against the UDAP Security Client Suite"
+1. Select the test group corresponding to your choice in step 1: **1** for *Authorization Code* and **2**
+   for *Client Credentials*. Click the "RUN ALL TESTS" button in the upper right, and click "SUBMIT".
+1. If testing the *Authorization Code* flow, click the link to authorize with the server.
+1. In the Client suite tab, click the link in the wait dialog to continue the tests.
+1. In the Server suite tab, find the access token to use for the data access request by opening
+   test **1.3.03** or **2.3.01** OAuth token exchange 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)
-9. Open Postman and open the "FHIR Request" Collection. Click the "Variables" tab and add the
+1. 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.
-10. Select the "Patient Read" request and click "Send". A FHIR Patient resource should be returned.
-11. Return to the client tests and click the link to continue and complete the tests.
+1. Select the "Patient Read" request and click "Send". A FHIR Patient resource should be returned.
+1. Return to the client tests and click the link to continue and complete the tests.
 
 The client tests should pass. On the server side some of the registration tests will fail. This is
 expected as the Server tests make several intentionally invalid token requests. Inferno's simulated UDAP
@@ -86,20 +91,58 @@ registration requests is itself not conformant there are corresponding failures
 
 ### Additional Inputs
 
-One additional input is available to support testers 
-- **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.
+#### Inputs Controlling Token Responses
+
+The UDAP simulation incorporates some aspects of SMART App launch including its approach to
+[context data](https://hl7.org/fhir/smart-app-launch/STU2.2/scopes-and-launch-context.html)
+in token responses during the authorization code flow.
+Inferno's SMART simulation does not include the details needed to populate
+these details into the token response when requested by apps using scopes.
+If the tested app needs and will request these details, the tester must provide them for Inferno
+to respond with using the following inputs:
+- **Launch Context** (available for all *SMART App Launch* clients): Testers can provide a JSON
+  array for Inferno to use as the base for building a token response on. This can include
+  keys like `"patient"` when the `launch/patient` scope will be requested. Note that when keys that Inferno
+  also populates (e.g. `access_token` or `id_token`) are included, the Inferno value will be returned.
+- **FHIR User Relative Reference** (available for all *SMART App Launch* clients): Testers
+  can provide a FHIR relative reference (`<resource type>/<id>`) for the FHIR user record
+  to return with the `id_token` when the `openid` and `fhirUser` scopes are requested. If populated,
+  include the corresponding resource in the **Available Resources** input (See the "Inputs
+  Controlling FHIR Responses" section) so that it can be accessed via FHIR read.
+
+#### Inputs Controlling FHIR Responses
+The focus of this test kit is on the auth protocol, so the simulated FHIR server implemented
+in this test suite is very simple. It will respond to any FHIR request with either:
+  - A resource from a tester-provided Bundle in the **Available Resources** input
+    if the request is a read matching a resource type and id found in the Bundle.
+  - Otherwise, the contents of the **Default FHIR Response** input, if provided.
+  - Otherwise, an OperationOutcome indicating no response was available.
+
+The two inputs that control these response include:
+- **Available Resources**: A FHIR Bundle of resources to make available via the
+  simulated FHIR sever. Each entry must contain a resource with the id element
+  populated. Each instance present will be available for retrieval from Inferno
+  at the endpoint: `<fhir-base>/<resource type>/<instance id>`. These will only
+  be available through the read interaction.
+- **FHIR Response to Echo**: A static FHIR JSON body for Inferno to return for all FHIR requests
+  not covered by reads of instances in the **Available Resources** input. In this case,
+  the simulation is a simple echo and Inferno does not check that the response is
+  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 UDAP Security IG for clients. Notably, only the B2B client credentials flow
-is tested at this time.
+described in the UDAP Security IG for clients.
 
-The following sections list other known gaps and limitations.
+The following sections list known gaps and limitations.
+
+### SMART Scope Checking and Fulfilment
+
+These tests do not verify any details about scopes, including that the
+- Requested scopes are conformant, such as that they have a valid format and are consistent
+  between authorization and refresh token requests.
+- Provided **Launch Context** input fullfils the requested data context scopes.
+- Access performed is allowed by the requested scope.
 
 ### UDAP Server Simulation Limitations
 
@@ -114,7 +157,7 @@ systems from passing in the [github repository's issues page](https://github.com
 ### 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 UDAP 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.
+FHIR APIs using access tokens obtained using the SMART flows is very limited. Testers are currently
+able to provide a list of resources to be read and a single static response that will be echoed for any
+other FHIR request made. While Inferno will never implement a fully general FHIR server simulation,
+additional options, such as may be added in the future based on community feedback.

data/lib/udap_security_test_kit/endpoints/echoing_fhir_responder_endpoint.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative '../urls'
+require_relative '../tags'
+require_relative 'mock_udap_server'
+
+module UDAPSecurityTestKit
+  class EchoingFHIRResponderEndpoint < Inferno::DSL::SuiteEndpoint
+    def test_run_identifier
+      MockUDAPServer.issued_token_to_client_id(request.headers['authorization']&.delete_prefix('Bearer '))
+    end
+
+    def make_response
+      return if response.status == 401 # set in update_result (expired token handling there)
+
+      response.content_type = 'application/fhir+json'
+      response.headers['Access-Control-Allow-Origin'] = '*'
+      response.status = 200
+
+      # look for read of provided resources
+      read_response = tester_provided_read_response_body
+      if read_response.present?
+        response.body = read_response.to_json
+        return
+      end
+
+      # If the tester provided a response, echo it
+      # otherwise, operation outcome
+      echo_response = JSON.parse(result.input_json)
+        .find { |input| input['name'].include?('echoed_fhir_response') }
+        &.dig('value')
+      if echo_response.present?
+        response.body = echo_response
+        return
+      end
+
+      response.status = 400
+      response.body = FHIR::OperationOutcome.new(
+        issue: FHIR::OperationOutcome::Issue.new(
+          severity: 'fatal', code: 'required',
+          details: FHIR::CodeableConcept.new(text: 'No response provided to echo.')
+        )
+      ).to_json
+    end
+
+    def update_result
+      if MockUDAPServer.request_has_expired_token?(request)
+        MockUDAPServer.update_response_for_expired_token(response, 'Bearer token')
+        return
+      end
+
+      nil # never update for now
+    end
+
+    def tags
+      [ACCESS_TAG]
+    end
+
+    def tester_provided_read_response_body
+      resource_type = request.params[:one]
+      id = request.params[:two]
+
+      return unless resource_type.present? && id.present?
+
+      resource_type_class =
+        begin
+          FHIR.const_get(resource_type)
+        rescue NameError
+          nil
+        end
+      return unless resource_type_class.present?
+
+      resource_bundle = ehr_input_bundle
+      return unless resource_bundle.present?
+
+      find_resource_in_bundle(resource_bundle, resource_type_class, id)
+    end
+
+    def ehr_input_bundle
+      ehr_bundle_input =
+        JSON.parse(result.input_json).find { |input| input['name'] == 'fhir_read_resources_bundle' }&.dig('value')
+      ehr_bundle = FHIR.from_contents(ehr_bundle_input) if ehr_bundle_input.present?
+      return ehr_bundle if ehr_bundle.is_a?(FHIR::Bundle)
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def find_resource_in_bundle(bundle, resource_type_class, id)
+      bundle.entry&.find do |entry|
+        entry.resource.is_a?(resource_type_class) && entry.resource.id == id
+      end&.resource
+    end
+  end
+end

data/lib/udap_security_test_kit/endpoints/mock_udap_server/authorization_endpoint.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../../tags'
+require_relative 'udap_authorization_response_creation'
+
+module UDAPSecurityTestKit
+  module MockUDAPServer
+    class AuthorizationEndpoint < Inferno::DSL::SuiteEndpoint
+      include UDAPAuthorizationResponseCreation
+
+      def test_run_identifier
+        request.params[:client_id]
+      end
+
+      def make_response
+        make_udap_authorization_response
+      end
+
+      def update_result
+        nil # never update for now
+      end
+
+      def tags
+        [AUTHORIZATION_TAG, AUTHORIZATION_CODE_TAG, UDAP_TAG]
+      end
+    end
+  end
+end

data/lib/udap_security_test_kit/endpoints/mock_udap_server/registration_endpoint.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../tags'
+require_relative '../mock_udap_server'
+require_relative 'udap_registration_response_creation'
+
+module UDAPSecurityTestKit
+  module MockUDAPServer
+    class RegistrationEndpoint < Inferno::DSL::SuiteEndpoint
+      include UDAPRegistrationResponseCreation
+
+      def test_run_identifier
+        MockUDAPServer.client_uri_to_client_id(
+          MockUDAPServer.udap_client_uri_from_registration_payload(MockUDAPServer.parsed_io_body(request))
+        )
+      end
+
+      def make_response
+        make_udap_registration_response
+      end
+
+      def update_result
+        nil # never update for now
+      end
+
+      def tags
+        [REGISTRATION_TAG, UDAP_TAG]
+      end
+    end
+  end
+end

data/lib/udap_security_test_kit/endpoints/mock_udap_server/token_endpoint.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../../tags'
+require_relative '../../urls'
+require_relative '../mock_udap_server'
+require_relative 'udap_token_response_creation'
+
+module UDAPSecurityTestKit
+  module MockUDAPServer
+    class TokenEndpoint < Inferno::DSL::SuiteEndpoint
+      include UDAPTokenResponseCreation
+      include URLs
+
+      def test_run_identifier
+        case request.params[:grant_type]
+        when CLIENT_CREDENTIALS_TAG
+          MockUDAPServer.client_id_from_client_assertion(request.params[:client_assertion])
+        when AUTHORIZATION_CODE_TAG
+          MockUDAPServer.issued_token_to_client_id(request.params[:code])
+        when REFRESH_TOKEN_TAG
+          MockUDAPServer.issued_token_to_client_id(
+            MockUDAPServer.refresh_token_to_authorization_code(request.params[:refresh_token])
+          )
+        end
+      end
+
+      def make_response
+        case request.params[:grant_type]
+        when CLIENT_CREDENTIALS_TAG
+          make_udap_client_credential_token_response
+        when AUTHORIZATION_CODE_TAG
+          make_udap_authorization_code_token_response
+        when REFRESH_TOKEN_TAG
+          make_udap_refresh_token_response
+        else
+          MockUDAPServer.update_response_for_error(
+            response,
+            "unsupported grant_type: #{request.params[:grant_type]}"
+          )
+        end
+      end
+
+      def update_result
+        nil # never update for now
+      end
+
+      def tags
+        tags = [TOKEN_TAG, UDAP_TAG]
+        if [CLIENT_CREDENTIALS_TAG, AUTHORIZATION_CODE_TAG, REFRESH_TOKEN_TAG].include?(request.params[:grant_type])
+          tags << request.params[:grant_type]
+        end
+        tags
+      end
+    end
+  end
+end

data/lib/udap_security_test_kit/endpoints/mock_udap_server/udap_authorization_response_creation.rb

@@ -0,0 +1,63 @@
+require 'jwt'
+require_relative '../mock_udap_server'
+
+module UDAPSecurityTestKit
+  module MockUDAPServer
+    module UDAPAuthorizationResponseCreation
+      def make_udap_authorization_response
+        redirect_uri = request.params[:redirect_uri]
+        registered_redirect_uri_list = udap_registered_redirect_uris
+
+        if redirect_uri.blank?
+          # need one from the registered list
+          if registered_redirect_uri_list.blank?
+            response.status = 400
+            response.body = {
+              error: 'Bad request',
+              message: 'Missing required redirect_uri parameter with no default provided in the registration.'
+            }.to_json
+            response.content_type = 'application/json'
+            return
+          elsif registered_redirect_uri_list.length > 1
+            response.status = 400
+            response.body = {
+              error: 'Bad request',
+              message: 'Missing required redirect_uri parameter with multiple options provided in the registration.'
+            }.to_json
+            response.content_type = 'application/json'
+            return
+          else
+            redirect_uri = registered_redirect_uri_list.first
+          end
+        end
+
+        client_id = request.params[:client_id]
+        state = request.params[:state]
+
+        exp_min = 10
+        token = MockUDAPServer.client_id_to_token(client_id, exp_min)
+        code_query_string = "code=#{ERB::Util.url_encode(token)}"
+        query_string =
+          if state.present?
+            "#{code_query_string}&state=#{ERB::Util.url_encode(state)}"
+          else
+            code_query_string
+          end
+        response.headers['Location'] = "#{redirect_uri}#{redirect_uri.include?('?') ? '&' : '?'}#{query_string}"
+        response.status = 302
+      end
+
+      def udap_registered_redirect_uris
+        registered_software_statement = MockUDAPServer.udap_registration_software_statement(test_run.test_session_id)
+        return unless registered_software_statement.present?
+
+        registration_jwt_body, _registration_jwt_header = JWT.decode(registered_software_statement, nil, false)
+        return [] unless registration_jwt_body['redirect'].present?
+        return registration_jwt_body['redirect'] if registration_jwt_body['redirect'].is_a?(Array)
+
+        # invalid registration, but we'll succeed here and fail during registration verification
+        [registration_jwt_body['redirect']]
+      end
+    end
+  end
+end

data/lib/udap_security_test_kit/endpoints/mock_udap_server/udap_registration_response_creation.rb

@@ -0,0 +1,28 @@
+require_relative '../mock_udap_server'
+
+module UDAPSecurityTestKit
+  module MockUDAPServer
+    module UDAPRegistrationResponseCreation
+      def make_udap_registration_response
+        parsed_body = MockUDAPServer.parsed_io_body(request)
+        client_id = MockUDAPServer.client_uri_to_client_id(
+          MockUDAPServer.udap_client_uri_from_registration_payload(parsed_body)
+        )
+        ss_jwt = MockUDAPServer.udap_software_statement_jwt(parsed_body)
+
+        response_body = {
+          client_id:,
+          software_statement: ss_jwt
+        }
+        response_body.merge!(MockUDAPServer.jwt_claims(ss_jwt).except(['iss', 'sub', 'exp', 'iat', 'jti']))
+
+        response.body = response_body.to_json
+        response.headers['Cache-Control'] = 'no-store'
+        response.headers['Pragma'] = 'no-cache'
+        response.headers['Access-Control-Allow-Origin'] = '*'
+        response.content_type = 'application/json'
+        response.status = 201
+      end
+    end
+  end
+end