udap_security_test_kit 0.11.1 → 0.11.3

data/lib/udap_security_test_kit/client_suite/client_registration_verification_test.rb

@@ -0,0 +1,244 @@
+require_relative '../tags'
+require_relative '../urls'
+require_relative '../endpoints/mock_udap_server'
+
+module UDAPSecurityTestKit
+  class UDAPClientRegistrationVerification < Inferno::Test
+    include URLs
+
+    id :udap_client_registration_verification
+    title 'Verify UDAP Registration'
+    description %(
+        During this test, Inferno will verify that the client's UDAP
+        registration request is conformant.
+      )
+    input :udap_client_uri,
+          optional: false
+
+    run do
+      omit_if udap_client_uri.blank?, # for re-use: mark the udap_client_uri input as optional when importing to enable
+              'Not configured for UDAP authentication.'
+
+      load_tagged_requests(UDAP_TAG, REGISTRATION_TAG)
+      skip_if requests.empty?, 'No UDAP Registration Requests made.'
+
+      verified_request = requests.last
+      parsed_body = MockUDAPServer.parsed_request_body(verified_request)
+      assert parsed_body.present?, 'Registration request body is not valid JSON.'
+
+      check_request_body(parsed_body)
+      check_software_statement(parsed_body['software_statement'], verified_request.created_at)
+
+      assert messages.none? { |msg|
+        msg[:type] == 'error'
+      }, 'Invalid registration request. See messages for details.'
+    end
+
+    def check_request_body(request_body)
+      if request_body['udap'].blank?
+        add_message('error', '`udap` key with a value of `1` missing in the registration request')
+      elsif request_body['udap'] != '1'
+        add_message('error',
+                    'The registration request contained an incorrect `udap` value: expected `1`, ' \
+                    "got `#{request_body['udap']}`")
+      end
+
+      return unless request_body['certifications'].present?
+
+      request_body['certifications'].each_with_index do |certification_jwt, index|
+        JWT.decond(certification_jwt)
+      rescue StandardError => e
+        add_message('error',
+                    "Certification #{index + 1} in the registration request is not a valid signed jwt: #{e}")
+      end
+    end
+
+    def check_software_statement(software_statement_jwt, request_time)
+      unless software_statement_jwt.present?
+        add_message('error',
+                    'Registration is missing a `software_statement` key')
+        return
+      end
+
+      claims, _headers = begin
+        JWT.decode(software_statement_jwt, nil, false)
+      rescue StandardError => e
+        add_message('error',
+                    "Registration software statement does not follow the jwt structure: #{e}")
+        return
+      end
+
+      # headers checked with signature
+      check_software_statement_claims(claims, request_time)
+      check_jwt_signature(software_statement_jwt)
+    end
+
+    def check_software_statement_claims(claims, request_time) # rubocop:disable Metrics/CyclomaticComplexity
+      unless claims['iss'] == udap_client_uri
+        add_message('error',
+                    'Registration software statement `iss` claim is incorrect: ' \
+                    "expected '#{udap_client_uri}', got '#{claims['iss']}'")
+      end
+      unless claims['sub'] == udap_client_uri
+        add_message('error',
+                    'Registration software statement `sub` claim is incorrect: ' \
+                    "expected '#{udap_client_uri}', got '#{claims['sub']}'")
+      end
+      unless claims['aud'] == client_registration_url
+        add_message('error',
+                    'Registration software statement `aud` claim is incorrect: ' \
+                    "expected '#{client_registration_url}', got '#{claims['aud']}'")
+      end
+
+      check_software_statement_grant_types(claims)
+      MockUDAPServer.check_jwt_timing(claims['iat'], claims['exp'], request_time)
+
+      add_message('error', 'Registration software statement `jti` claim is missing.') unless claims['jti'].present?
+      unless claims['client_name'].present?
+        add_message('error', 'Registration software statement `client_name` claim is missing.')
+      end
+      check_software_statement_contacts(claims['contacts'])
+      unless claims['token_endpoint_auth_method'] == 'private_key_jwt'
+        add_message('error', 'Registration software statement `token_endpoint_auth_method` claim is incorrect: ' \
+                             "expected `token_endpoint_auth_method`, got #{claims['token_endpoint_auth_method']}.")
+      end
+      add_message('error', 'Registration software statement `scope` claim is missing.') unless claims['scope'].present?
+
+      nil
+    end
+
+    def check_software_statement_contacts(contacts)
+      unless contacts.present?
+        add_message('error', 'Registration software statement `contacts` claim is missing.')
+        return
+      end
+      unless contacts.is_a?(Array)
+        add_message('error', 'Registration software statement `contacts` claim is missing.')
+        return
+      end
+      unless contacts.find { |contact| valid_uri?(contact, required_scheme: 'mailto') }.present?
+        add_message('error', 'Registration software statement `contacts` claim has no ' \
+                             'valid `mailto` uri entry.')
+      end
+
+      nil
+    end
+
+    def check_software_statement_grant_types(claims) # rubocop:disable Metrics/CyclomaticComplexity
+      unless claims['grant_types'].present?
+        add_message('error', 'Registration software statement `grant_types` claim is missing')
+        return
+      end
+
+      unless claims['grant_types'].is_a?(Array)
+        add_message('error', 'Registration software statement `grant_types` claim must be a list.')
+        return
+      end
+
+      has_client_credentials = claims['grant_types'].include?('client_credentials')
+      has_authorization_code = claims['grant_types'].include?('authorization_code')
+
+      unless has_client_credentials || has_authorization_code
+        add_message('error', 'Registration software statement `grant_types` claim must contain one of ' \
+                             "'authorization_code' or 'client_credentials'")
+        return
+      end
+
+      if has_client_credentials && has_authorization_code
+        add_message('error', 'Registration software statement `grant_types` claim cannot contain both ' \
+                             "'authorization_code' and 'client_credentials'")
+      end
+
+      extra_grants = claims['grant_types'].reject do |grant|
+        ['client_credentials', 'authorization_code', 'refresh_token'].include?(grant)
+      end
+      unless extra_grants.blank?
+        add_message('error', 'Registration software statement `grant_types` claim cannot contain values beyond ' \
+                             "'authorization_code', 'client_credentials', and 'refresh_token")
+      end
+
+      check_client_credentials_software_statement(claims) if has_client_credentials
+      check_authorization_code_software_statement(claims) if has_authorization_code
+
+      nil
+    end
+
+    def check_authorization_code_software_statement(claims) # rubocop:disable Metrics/CyclomaticComplexity
+      if claims['redirect_uris'].blank?
+        add_message('error', 'Registration software statement `redirect_uris` must be present when' \
+                             "the 'authorization_code' `grant_type` is requested.")
+      elsif !claims['redirect_uris'].is_a?(Array)
+        add_message('error', 'Registration software statement `redirect_uris` must be a list when' \
+                             "the 'authorization_code' `grant_type` is requested.")
+      else
+        claims['redirect_uris'].each do |redirect_uri|
+          unless valid_uri?(redirect_uri, required_scheme: 'https')
+            add_message('error', "Registration software statement `redirect_uris` entry #{index + 1} is invalid: " \
+                                 'it is not a valid https uri.')
+          end
+        end
+      end
+
+      if claims['logo_uri'].blank?
+        add_message('error', 'Registration software statement `logo_uri` must be present when' \
+                             "the 'authorization_code' `grant_type` is requested.")
+      else
+        unless valid_uri?(claims['logo_uri'], required_scheme: 'https')
+          add_message('error', 'Registration software statement `logo_uri` is invalid: it is not a valid https uri.')
+        end
+        unless ['gif', 'jpg', 'jpeg', 'png'].include?(claims['logo_uri'].split['.'].last.downcase)
+          add_message('error', 'Registration software statement `logo_uri` is invalid: it must point to a ' \
+                               'PNG, JPG, or GIF file.')
+        end
+      end
+
+      if claims['response_types'].blank?
+        add_message('error', 'Registration software statement `response_types` must be present when' \
+                             "the 'authorization_code' `grant_type` is requested.")
+      else
+        unless claims['response_types'].is_a?(Array) &&
+               claims['response_types'].size == 1 &&
+               claims['response_types'][0] == 'code'
+          add_message('error', 'Registration software statement `response_types` claim is invalid: ' \
+                               "must contain exactly one entry with the value 'code'.")
+        end
+      end
+
+      nil
+    end
+
+    def check_client_credentials_software_statement(claims)
+      unless claims['redirect_uris'].nil?
+        add_message('error', 'Registration software statement `redirect_uris` must not be present when' \
+                             "the 'client_credentials' `grant_type` is requested.")
+      end
+
+      unless claims['response_types'].nil?
+        add_message('error', 'Registration software statement `response_types` must not be present when' \
+                             "the 'client_credentials' `grant_type` is requested.")
+      end
+
+      if claims['grant_types'].include?('refresh_token')
+        add_message('error', "Registration software statement `response_types` cannot contain 'refresh_token' when" \
+                             "the 'client_credentials' `grant_type` is requested.")
+      end
+
+      nil
+    end
+
+    def check_jwt_signature(jwt)
+      error = MockUDAPServer.udap_reg_signature_verification(jwt)
+
+      return unless error.present?
+
+      add_message('error', "Signature validation failed on registration request: #{error}")
+    end
+
+    def valid_uri?(url, required_scheme: nil)
+      uri = URI.parse(url)
+      required_scheme.blank? || uri.scheme == required_scheme
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/udap_security_test_kit/client_suite/client_token_request_verification_test.rb

@@ -0,0 +1,178 @@
+require_relative '../tags'
+require_relative '../urls'
+require_relative '../endpoints/mock_udap_server'
+
+module UDAPSecurityTestKit
+  class UDAPClientTokenRequestVerification < Inferno::Test
+    include URLs
+
+    id :udap_client_token_request_verification
+    title 'Verify UDAP Token Requests'
+    description %(
+      Check that UDAP token requests are conformant.
+    )
+
+    output :udap_demonstrated
+    output :udap_tokens
+
+    run do
+      load_tagged_requests(REGISTRATION_TAG, UDAP_TAG)
+      output udap_demonstrated: requests.present? ? 'Yes' : 'No'
+      omit_if requests.blank?, 'UDAP Authentication not demonstrated as a part of this test session.'
+      registration_request = requests.last
+      registration_assertion = MockUDAPServer.parsed_request_body(registration_request)['software_statement']
+      registration_token =
+        begin
+          JWT::EncodedToken.new(registration_assertion)
+        rescue StandardError => e
+          assert false, "Registration request parsing failed: #{e}"
+        end
+      registered_client_id = JSON.parse(registration_request.response_body)['client_id']
+
+      requests.clear
+      load_tagged_requests(TOKEN_TAG, UDAP_TAG)
+      skip_if requests.blank?, 'No UDAP 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, registration_token,
+                               registered_client_id, token_request.created_at)
+        token_list << extract_token_from_response(token_request)
+      end
+
+      output udap_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['udap'].to_s != '1'
+
+      add_message('error',
+                  "Token request #{request_num} had an incorrect `udap`: " \
+                  "expected '1', " \
+                  "but got '#{params['udap']}'")
+    end
+
+    def check_client_assertion(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(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(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
+
+      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
+  end
+end

data/lib/udap_security_test_kit/client_suite/client_token_use_verification_test.rb

@@ -0,0 +1,43 @@
+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_demonstrated # from test :udap_client_token_request_verification based on registrations
+    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
+      omit_if udap_demonstrated == 'No', 'UDAP 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 = 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,78 @@
+require_relative 'endpoints/mock_udap_server/registration'
+require_relative 'endpoints/mock_udap_server/token'
+require_relative 'endpoints/echoing_fhir_responder'
+require_relative 'urls'
+require_relative 'client_suite/client_registration_group'
+require_relative 'client_suite/client_access_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/'
+      }
+    ]
+
+    route(:get, UDAP_DISCOVERY_PATH, ->(_env) { MockUDAPServer.udap_server_metadata(id) })
+    suite_endpoint :post, REGISTRATION_PATH, MockUDAPServer::RegistrationEndpoint
+    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 do
+      title 'UDAP Client Credentials Flow'
+      description %(
+        During these tests, the client will use the UDAP Client Credentials
+        flow as specified in the [B2B section of the IG](https://hl7.org/fhir/us/udap-security/STU1/b2b.html)
+        to access a FHIR API. Clients will register, obtain an access token,
+        and use the access token when making a request to a FHIR API.
+      )
+
+      group from: :udap_client_registration
+      group from: :udap_client_access
+    end
+  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"
+		}
+	]
+}