udap_security_test_kit 0.11.2 → 0.11.4

data/lib/udap_security_test_kit/client_suite/token_request_verification.rb

@@ -0,0 +1,223 @@
+module UDAPSecurityTestKit
+  module TokenRequestVerification
+    def verify_token_requests(oauth_flow)
+      registration_token =
+        begin
+          JWT::EncodedToken.new(udap_registration_jwt)
+        rescue StandardError => e
+          assert false, "Registration request parsing failed: #{e}"
+        end
+
+      jti_list = []
+      token_list = []
+      requests.each_with_index do |token_request, index|
+        request_params = URI.decode_www_form(token_request.request_body).to_h
+        if request_params['grant_type'] == 'refresh_token'
+          check_refresh_request_params(oauth_flow, request_params, index + 1)
+        else
+          check_request_params(oauth_flow, request_params, index + 1)
+        end
+        check_client_assertion(oauth_flow, request_params['client_assertion'], index + 1, jti_list, registration_token,
+                               client_id, token_request.created_at)
+        token_list << extract_token_from_response(token_request)
+      end
+
+      output udap_tokens: token_list.compact.join("\n")
+    end
+
+    def check_request_params(oauth_flow, params, request_num)
+      if params['grant_type'] != oauth_flow
+        add_message('error',
+                    "Token request #{request_num} had an incorrect `grant_type`: expected '#{oauth_flow}', " \
+                    "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
+      unless params['udap'].to_s == '1'
+        add_message('error',
+                    "Token request #{request_num} had an incorrect `udap`: " \
+                    "expected '1', " \
+                    "but got '#{params['udap']}'")
+      end
+
+      check_authorization_code_request_params(params, request_num) if oauth_flow == AUTHORIZATION_CODE_TAG
+
+      nil
+    end
+
+    def check_authorization_code_request_params(params, request_num)
+      if params['code'].present?
+
+        authorization_request = MockUDAPServer.authorization_request_for_code(params['code'], test_session_id)
+
+        if authorization_request.present?
+          authorization_body = MockUDAPServer.authorization_code_request_details(authorization_request)
+
+          if params['redirect_uri'] != authorization_body['redirect_uri']
+            add_message('error', "Authorization code token request #{request_num} included an incorrect " \
+                                 "`redirect_uri` value: expected '#{authorization_body['redirect_uri']} " \
+                                 "but got '#{params['redirect_uri']}'")
+          end
+
+          return unless params['code_verifier'].present? # optional in UDAP
+
+          pkce_error = MockUDAPServer.pkce_error(params['code_verifier'],
+                                                 authorization_body['code_challenge'],
+                                                 authorization_body['code_challenge_method'])
+          if pkce_error.present?
+            add_message('error', 'Error performing pkce verification on the `code_verifier` value in ' \
+                                 "authorization code token request #{request_num}: #{pkce_error}")
+          end
+        else
+          add_message('error', "Authorization code token request #{request_num} included a code not " \
+                               "issued during this test session: '#{params['code']}'")
+        end
+      else
+        add_message('error', "Authorization code token request #{request_num} missing a `code`")
+      end
+    end
+
+    def check_client_assertion(oauth_flow, assertion, request_num, jti_list, registration_token, registered_client_id,
+                               request_time)
+      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?
+
+      # header checked with signature
+      check_jwt_payload(oauth_flow, decoded_token.payload, request_num, jti_list, registered_client_id, request_time)
+      check_jwt_signature(decoded_token, registration_token, request_num)
+    end
+
+    def check_jwt_payload(oauth_flow, claims, request_num, jti_list, registered_client_id, request_time) # rubocop:disable Metrics/CyclomaticComplexity
+      if claims['iss'] != registered_client_id
+        add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `iss` claim: " \
+                             "expected '#{registered_client_id}', got '#{claims['iss']}'")
+      end
+
+      if claims['sub'] != registered_client_id
+        add_message('error', "client assertion jwt on token request #{request_num} has an incorrect `sub` claim: " \
+                             "expected '#{registered_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
+
+      MockUDAPServer.check_jwt_timing(claims['iat'], claims['exp'], request_time)
+
+      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
+
+      return unless oauth_flow == CLIENT_CREDENTIALS_TAG
+
+      if claims['extensions'].present?
+        if claims['extensions'].is_a?(Hash)
+          check_b2b_auth_extension(claims.dig('extensions', 'hl7-b2b'), request_num)
+        else
+          add_message('error', "client assertion jwt on token request #{request_num} has an `extensions` claim that " \
+                               'is not a json object.')
+        end
+      else
+        add_message('error', "client assertion jwt on token request #{request_num} missing the `hl7-b2b` extension.")
+      end
+    end
+
+    def check_b2b_auth_extension(b2b_auth, request_num)
+      if b2b_auth.blank?
+        add_message('error', "client assertion jwt on token request #{request_num} missing the `hl7-b2b` extension.")
+        return
+      end
+
+      if b2b_auth['version'].blank?
+        add_message('error', "the `hl7-b2b` extension on client assertion jwt on token request #{request_num} is " \
+                             'missing the required `version` key.')
+      elsif b2b_auth['version'].to_s != '1'
+        add_message('error', "the `hl7-b2b` extension on client assertion jwt on token request #{request_num} has an " \
+                             "incorrect `version` value: expected `1`, got #{b2b_auth['version']}.")
+      end
+
+      if b2b_auth['organization_id'].blank?
+        add_message('error', "the `hl7-b2b` extension on client assertion jwt on token request #{request_num} is " \
+                             'missing the required `organization_id` key.')
+      else
+        begin
+          URI.parse(b2b_auth['organization_id'])
+        rescue URI::InvalidURIError
+          add_message('error', 'the `organization_id` key in the `hl7-b2b` extension on client assertion jwt on ' \
+                               "token request #{request_num} is not a valid URI.")
+        end
+      end
+
+      if b2b_auth['purpose_of_use'].blank?
+        add_message('error', "the `hl7-b2b` extension on client assertion jwt on token request #{request_num} is " \
+                             'missing the required `purpose_of_use` key.')
+      end
+
+      nil
+    end
+
+    def check_jwt_signature(encoded_token, registration_token, request_num)
+      error = MockUDAPServer.udap_token_signature_verification(encoded_token.jwt, registration_token.jwt)
+
+      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 StandardError
+      nil
+    end
+
+    def check_refresh_request_params(oauth_flow, params, request_num)
+      if oauth_flow == CLIENT_CREDENTIALS_TAG
+        add_message('error',
+                    "Invalid refresh request #{request_num} found during client_credentials flow.")
+        return
+      end
+
+      if params['grant_type'] != 'refresh_token'
+        add_message('error',
+                    "Refresh request #{request_num} had an incorrect `grant_type`: expected 'refresh_token', " \
+                    "but got '#{params['grant_type']}'")
+      end
+      if params['client_assertion_type'] != 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+        add_message('error',
+                    "Token refresh 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
+
+      authorization_code = MockUDAPServer.refresh_token_to_authorization_code(params['refresh_token'])
+      authorization_request = MockUDAPServer.authorization_request_for_code(authorization_code, test_session_id)
+      if authorization_request.present?
+        # TODO: - check that the scope is a subset of the original authorization code request
+      else
+        add_message('error', "Authorization code token refresh request #{request_num} included a refresh token not " \
+                             "issued during this test session: '#{params['refresh_token']}'")
+      end
+
+      nil
+    end
+  end
+end

data/lib/udap_security_test_kit/client_suite/token_use_verification_test.rb

@@ -0,0 +1,40 @@
+require_relative '../tags'
+require_relative '../endpoints/mock_udap_server'
+
+module UDAPSecurityTestKit
+  class UDAPTokenUseVerification < Inferno::Test
+    id :udap_client_token_use_verification
+    title 'Verify UDAP Token Use'
+    description %(
+        Check that a UDAP token returned to the client was used for request
+        authentication.
+      )
+
+    input :udap_tokens,
+          optional: true
+
+    def access_request_tags
+      return config.options[:access_request_tags] if config.options[:access_request_tags].present?
+
+      [ACCESS_TAG]
+    end
+
+    run do
+      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 = udap_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/udap_security_test_kit/client_suite.rb

@@ -0,0 +1,107 @@
+require_relative 'endpoints/mock_udap_server/registration_endpoint'
+require_relative 'endpoints/mock_udap_server/authorization_endpoint'
+require_relative 'endpoints/mock_udap_server/token_endpoint'
+require_relative 'endpoints/echoing_fhir_responder_endpoint'
+require_relative 'urls'
+require_relative 'client_suite/registration_ac_group'
+require_relative 'client_suite/registration_cc_group'
+require_relative 'client_suite/access_ac_group'
+require_relative 'client_suite/access_cc_group'
+
+module UDAPSecurityTestKit
+  class UDAPSecurityClientTestSuite < Inferno::TestSuite
+    id :udap_security_client
+    title 'UDAP Security Client'
+    description File.read(File.join(__dir__, 'docs', 'udap_client_suite_description.md'))
+
+    links [
+      {
+        type: 'source_code',
+        label: 'Open Source',
+        url: 'https://github.com/inferno-framework/udap-security-test-kit/'
+      },
+      {
+        type: 'report_issue',
+        label: 'Report Issue',
+        url: 'https://github.com/inferno-framework/udap-security-test-kit/issues/'
+      },
+      {
+        type: 'download',
+        label: 'Download',
+        url: 'https://github.com/inferno-framework/udap-security-test-kit/releases/'
+      },
+      {
+        type: 'ig',
+        label: 'Implementation Guide',
+        url: 'https://hl7.org/fhir/us/udap-security/STU1/'
+      }
+    ]
+
+    suite_option :client_type,
+                 title: 'UDAP Client Type',
+                 list_options: [
+                   {
+                     label: 'UDAP Authorization Code Client',
+                     value: UDAPClientOptions::UDAP_AUTHORIZATION_CODE
+                   },
+                   {
+                     label: 'UDAP Client Credentials Client',
+                     value: UDAPClientOptions::UDAP_CLIENT_CREDENTIALS
+                   }
+                 ]
+
+    route(:get, UDAP_DISCOVERY_PATH, ->(_env) { MockUDAPServer.udap_server_metadata(id) })
+    route(:get, OIDC_DISCOVERY_PATH, ->(_env) { MockUDAPServer.openid_connect_metadata(id) })
+    route(
+      :get,
+      OIDC_JWKS_PATH,
+      ->(_env) { [200, { 'Content-Type' => 'application/json' }, [OIDCJWKS.jwks_json]] }
+    )
+
+    suite_endpoint :post, REGISTRATION_PATH, MockUDAPServer::RegistrationEndpoint
+    suite_endpoint :get, AUTHORIZATION_PATH, MockUDAPServer::AuthorizationEndpoint
+    suite_endpoint :post, AUTHORIZATION_PATH, MockUDAPServer::AuthorizationEndpoint
+    suite_endpoint :post, TOKEN_PATH, MockUDAPServer::TokenEndpoint
+    suite_endpoint :get, FHIR_PATH, EchoingFHIRResponderEndpoint
+    suite_endpoint :post, FHIR_PATH, EchoingFHIRResponderEndpoint
+    suite_endpoint :put, FHIR_PATH, EchoingFHIRResponderEndpoint
+    suite_endpoint :delete, FHIR_PATH, EchoingFHIRResponderEndpoint
+    suite_endpoint :get, "#{FHIR_PATH}/:one", EchoingFHIRResponderEndpoint
+    suite_endpoint :post, "#{FHIR_PATH}/:one", EchoingFHIRResponderEndpoint
+    suite_endpoint :put, "#{FHIR_PATH}/:one", EchoingFHIRResponderEndpoint
+    suite_endpoint :delete, "#{FHIR_PATH}/:one", EchoingFHIRResponderEndpoint
+    suite_endpoint :get, "#{FHIR_PATH}/:one/:two", EchoingFHIRResponderEndpoint
+    suite_endpoint :post, "#{FHIR_PATH}/:one/:two", EchoingFHIRResponderEndpoint
+    suite_endpoint :put, "#{FHIR_PATH}/:one/:two", EchoingFHIRResponderEndpoint
+    suite_endpoint :delete, "#{FHIR_PATH}/:one/:two", EchoingFHIRResponderEndpoint
+    suite_endpoint :get, "#{FHIR_PATH}/:one/:two/:three", EchoingFHIRResponderEndpoint
+    suite_endpoint :post, "#{FHIR_PATH}/:one/:two/:three", EchoingFHIRResponderEndpoint
+    suite_endpoint :put, "#{FHIR_PATH}/:one/:two/:three", EchoingFHIRResponderEndpoint
+    suite_endpoint :delete, "#{FHIR_PATH}/:one/:two/:three", EchoingFHIRResponderEndpoint
+
+    resume_test_route :get, RESUME_PASS_PATH do |request|
+      request.query_parameters['token']
+    end
+
+    resume_test_route :get, RESUME_FAIL_PATH, result: 'fail' do |request|
+      request.query_parameters['token']
+    end
+
+    group from: :udap_client_registration_ac,
+          required_suite_options: {
+            client_type: UDAPClientOptions::UDAP_AUTHORIZATION_CODE
+          }
+    group from: :udap_client_registration_cc,
+          required_suite_options: {
+            client_type: UDAPClientOptions::UDAP_CLIENT_CREDENTIALS
+          }
+    group from: :udap_client_access_ac,
+          required_suite_options: {
+            client_type: UDAPClientOptions::UDAP_AUTHORIZATION_CODE
+          }
+    group from: :udap_client_access_cc,
+          required_suite_options: {
+            client_type: UDAPClientOptions::UDAP_CLIENT_CREDENTIALS
+          }
+  end
+end

data/lib/udap_security_test_kit/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": "udap_security_client",
+			"type": "string"
+		},
+		{
+			"key": "bearer_token",
+			"value": "",
+			"type": "string"
+		}
+	]
+}

data/lib/udap_security_test_kit/docs/udap_client_suite_description.md

@@ -0,0 +1,163 @@
+## Overview
+
+The UDAP Security Client Test Suite verifies the conformance of
+client systems to the STU 1.0.0 version of the HL7® FHIR®
+[Security for Scalable Registration, Authentication, and Authorization (UDAP Security) FHIR IG](https://hl7.org/fhir/us/udap-security/STU1/).
+
+## Scope
+
+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. 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
+and [provide feedback](https://github.com/inferno-framework/udap-security-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 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
+   token requests which must also have the client URI as a Subject Alternative Name (SAN)
+   value in the certificate.
+3. Obtain an access token with a request using the client Id returned during registration
+   and signed using same X.509 certificate supplied during registration.
+4. Use that access token on a FHIR API request.
+
+The simulated UDAP 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. **UDAP Client URI**: The UDAP Client URI that will be used to register with
+   Inferno's simulated UDAP server.
+
+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 UDAP client implementation, these tests can be exercised
+using the UDAP Security 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/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 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)
+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.
+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
+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 successfully to non-conformant
+registration requests is itself not conformant there are corresponding failures on the server test.
+
+### Additional Inputs
+
+#### 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.
+
+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
+
+This test suite contains a simulation of a UDAP server which is not fully
+general and not all conformant clients may be able to interact with it. One
+specific example is that the UDAP configuration metadata available at
+`.well-known/udap` for the simulated server is fixed and cannot be changed by
+testers at this time. Despite the current limitations, the intention is for Inferno to
+support a variety of conformant choices, so please report issues that prevent conformant
+systems from passing in the [github repository's issues page](https://github.com/inferno-framework/udap-security-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 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.