smart_app_launch_test_kit 0.4.3 → 0.4.4

data/lib/smart_app_launch/smart_access_brands_validate_endpoint_urls_test.rb

@@ -0,0 +1,120 @@
+module SMARTAppLaunch
+  class SMARTAccessBrandsValidateEndpointURLs < Inferno::Test
+    id :smart_access_brands_valid_endpoint_urls
+    title 'All Endpoint resource referenced URLS should be valid and available'
+    description %(
+      Verify that User Access Brands Bundle contains Endpoints that contain URLs that are both valid
+      and available.
+    )
+
+    input :user_access_brands_bundle,
+          optional: true
+
+    input :endpoint_availability_limit,
+          title: 'Endpoint Availability Limit',
+          description: %(
+      Input a number to cap the number of Endpoints that Inferno will send requests to check for availability.
+      This can help speed up validation when there are large number of endpoints in the Service Base URL Bundle.
+    ),
+          optional: true
+
+    input :endpoint_availability_success_rate,
+          title: 'Endpoint Availability Success Rate',
+          description: %(
+      Select an option to choose how many Endpoints have to be available and send back a valid capability
+      statement for the Endpoint validation test to pass.
+    ),
+          type: 'radio',
+          options: {
+            list_options: [
+              {
+                label: 'All',
+                value: 'all'
+              },
+              {
+                label: 'At Least 1',
+                value: 'at_least_1'
+              },
+              {
+                label: 'None',
+                value: 'none'
+              }
+            ]
+          },
+          default: 'all'
+
+    def get_endpoint_availability_limit(endpoint_availability_limit)
+      return if endpoint_availability_limit.blank?
+
+      endpoint_availability_limit.to_i
+    end
+
+    def skip_message
+      %(
+        No User Access Brands request was made in the previous test, and no User Access Brands Bundle was provided as
+        input instead. Either provide a User Access Brands Publication URL to retrieve the Bundle via a HTTP GET
+        request, or provide the Bundle as an input.
+      )
+    end
+
+    run do
+      bundle_response = if user_access_brands_bundle.blank?
+                          load_tagged_requests('smart_access_brands_bundle')
+                          skip skip_message if requests.length != 1
+                          requests.first.response_body
+                        else
+                          user_access_brands_bundle
+                        end
+
+      skip_if bundle_response.blank?, 'No SMART Access Brands Bundle contained in the response'
+
+      assert_valid_json(bundle_response)
+      bundle_resource = FHIR.from_contents(bundle_response)
+
+      skip_if bundle_resource.entry.empty?, 'The given Bundle does not contain any resources'
+
+      endpoint_list = bundle_resource
+        .entry
+        .map(&:resource)
+        .select { |resource| resource.resourceType == 'Endpoint' }
+        .map(&:address)
+        .uniq
+
+      check_limit = get_endpoint_availability_limit(endpoint_availability_limit)
+      one_endpoint_valid = false
+
+      endpoint_list.each_with_index do |address, index|
+        assert_valid_http_uri(address)
+
+        next if endpoint_availability_success_rate == 'none' || (check_limit.present? && index >= check_limit)
+
+        address = address.delete_suffix('/')
+        get("#{address}/metadata", client: nil, headers: { Accept: 'application/fhir+json' })
+
+        if endpoint_availability_success_rate == 'all'
+          assert_response_status(200)
+          assert resource.present?, 'The content received does not appear to be a valid FHIR resource'
+          assert_resource_type(:capability_statement)
+        else
+          warning do
+            assert_response_status(200)
+            assert resource.present?, 'The content received does not appear to be a valid FHIR resource'
+            assert_resource_type(:capability_statement)
+          end
+
+          if !one_endpoint_valid && response[:status] == 200 && resource.present? &&
+             resource.resourceType == 'CapabilityStatement'
+            one_endpoint_valid = true
+          end
+        end
+      end
+
+      if endpoint_availability_success_rate == 'at_least_1'
+        assert(one_endpoint_valid, %(
+            There were no Endpoints that were available and returned a valid Capability Statement in the Service Base
+            URL Bundle'
+          ))
+      end
+    end
+  end
+end

data/lib/smart_app_launch/smart_access_brands_validate_endpoints_test.rb

@@ -0,0 +1,70 @@
+module SMARTAppLaunch
+  class SMARTAccessBrandsValidateEndpoints < Inferno::Test
+    id :smart_access_brands_valid_endpoints
+    title 'SMART Access Brands Bundle contains valid User Access Endpoints'
+    description %(
+      Verify that Bundle of User Access Brands and Endpoints contains Endpoints that are valid
+      Endpoint resources according to the [User Access Endpoint Profile](https://hl7.org/fhir/smart-app-launch/STU2.2/StructureDefinition-user-access-endpoint.html).
+
+      Along with validating the Endpoint resources, this test also ensures that each endpoint contains a primary brand
+      by checking if it is referenced by at least 1 Organization resource.
+      )
+
+    def find_referenced_org(bundle_resource, endpoint_id)
+      bundle_resource
+        .entry
+        .map(&:resource)
+        .select { |resource| resource.resourceType == 'Organization' }
+        .map(&:endpoint)
+        .flatten
+        .map(&:reference)
+        .select { |reference| reference.include? endpoint_id }
+    end
+
+    def skip_message
+      %(
+        No User Access Brands request was made in the previous test, and no User Access Brands Bundle was provided as
+        input instead. Either provide a User Access Brands Publication URL to retrieve the Bundle via a HTTP GET
+        request, or provide the Bundle as an input.
+      )
+    end
+
+    input :user_access_brands_bundle,
+          optional: true
+
+    run do
+      bundle_response = if user_access_brands_bundle.blank?
+                          load_tagged_requests('smart_access_brands_bundle')
+                          skip skip_message if requests.length != 1
+                          requests.first.response_body
+                        else
+                          user_access_brands_bundle
+                        end
+
+      skip_if bundle_response.blank?, 'No SMART Access Brands Bundle contained in the response'
+
+      assert_valid_json(bundle_response)
+      bundle_resource = FHIR.from_contents(bundle_response)
+
+      skip_if bundle_resource.entry.empty?, 'The given Bundle does not contain any resources'
+
+      assert_valid_bundle_entries(bundle: bundle_resource,
+                                  resource_types: {
+                                    Endpoint: 'http://hl7.org/fhir/smart-app-launch/StructureDefinition/user-access-endpoint'
+                                  })
+
+      endpoint_ids =
+        bundle_resource
+          .entry
+          .map(&:resource)
+          .select { |resource| resource.resourceType == 'Endpoint' }
+          .map(&:id)
+
+      endpoint_ids.each do |endpoint_id|
+        endpoint_referenced_orgs = find_referenced_org(bundle_resource, endpoint_id)
+        assert !endpoint_referenced_orgs.empty?,
+               "Endpoint with id: #{endpoint_id} does not have any associated Organizations in the Bundle."
+      end
+    end
+  end
+end

data/lib/smart_app_launch/smart_access_brands_validation_group.rb

@@ -0,0 +1,24 @@
+require_relative 'smart_access_brands_validate_bundle_test'
+require_relative 'smart_access_brands_validate_endpoints_test'
+require_relative 'smart_access_brands_validate_endpoint_urls_test'
+require_relative 'smart_access_brands_validate_brands_test'
+
+module SMARTAppLaunch
+  class SMARTAccessBrandsValidationGroup < Inferno::TestGroup
+    id :smart_access_brands_validation
+    title 'Validate SMART Access Brands Bundle'
+    description %(
+      These tests ensure that the publisher's User Access Brands publication is in
+      a valid Bundle according to the [User Access Brand Bundle Profile](https://hl7.org/fhir/smart-app-launch/STU2.2/StructureDefinition-user-access-brands-bundle.html).
+      It ensures that this User Access Brand Bundle has its brand and endpoint
+      details contained in valid Endpoints according to the [User Access Endpoint Profile](https://hl7.org/fhir/smart-app-launch/STU2.2/StructureDefinition-user-access-endpoint.html)
+      and valid Brands (Organizations) according to the [User Access Brand Profile](https://hl7.org/fhir/smart-app-launch/STU2.2/StructureDefinition-user-access-brand.html).
+    )
+    run_as_group
+
+    test from: :smart_access_brands_valid_bundle
+    test from: :smart_access_brands_valid_endpoints
+    test from: :smart_access_brands_valid_endpoint_urls
+    test from: :smart_access_brands_valid_brands
+  end
+end

data/lib/smart_app_launch/smart_stu2_2_suite.rb

@@ -0,0 +1,243 @@
+require 'tls_test_kit'
+
+require_relative 'jwks'
+require_relative 'version'
+require_relative 'discovery_stu2_group'
+require_relative 'standalone_launch_group_stu2_2'
+require_relative 'ehr_launch_group_stu2_2'
+require_relative 'openid_connect_group'
+require_relative 'token_introspection_group_stu2_2'
+require_relative 'token_refresh_stu2_group'
+require_relative 'backend_services_authorization_group'
+
+module SMARTAppLaunch
+  class SMARTSTU22Suite < Inferno::TestSuite
+    id 'smart_stu2_2'
+    title 'SMART App Launch STU2.2'
+    version VERSION
+
+    resume_test_route :get, '/launch' do |request|
+      request.query_parameters['iss']
+    end
+
+    resume_test_route :get, '/redirect' do |request|
+      request.query_parameters['state']
+    end
+
+    route(
+      :get,
+      '/.well-known/jwks.json',
+      ->(_env) { [200, { 'Content-Type' => 'application/json' }, [JWKS.jwks_json]] }
+    )
+
+    @post_auth_page = File.read(File.join(__dir__, 'post_auth.html'))
+    post_auth_handler = proc { [200, {}, [@post_auth_page]] }
+
+    route :get, '/post_auth', post_auth_handler
+
+    config options: {
+      redirect_uri: "#{Inferno::Application['base_url']}/custom/smart_stu2_2/redirect",
+      launch_uri: "#{Inferno::Application['base_url']}/custom/smart_stu2_2/launch",
+      post_authorization_uri: "#{Inferno::Application['base_url']}/custom/smart_stu2_2/post_auth"
+    }
+
+    description <<~DESCRIPTION
+      The SMART App Launch Test Suite verifies that systems correctly implement
+      the [SMART App Launch IG](http://hl7.org/fhir/smart-app-launch/STU2.2/)
+      for providing authorization and/or authentication services to client
+      applications accessing HL7® FHIR® APIs. To get started, please first register
+      the Inferno client as a SMART App with the following information:
+
+      * SMART Launch URI: `#{config.options[:launch_uri]}`
+      * OAuth Redirect URI: `#{config.options[:redirect_uri]}`
+
+      If using asymmetric client authentication, register Inferno with the
+      following JWK Set URL:
+
+      * `#{Inferno::Application[:base_url]}/custom/smart_stu2_2/.well-known/jwks.json`
+    DESCRIPTION
+
+    input_instructions %(
+      When running tests at this level, the token introspection endpoint is not available as a manual input.
+      Instead, group 3 Token Introspection will assume the token introspection endpoint
+      will be output from group 1 Standalone Launch tests, specifically the SMART On FHIR Discovery tests that query
+      the .well-known/smart-configuration endpoint. However, including the token introspection
+      endpoint as part of the well-known ouput is NOT required and is not formally checked in the SMART On FHIR Discovery
+      tests.  RFC-7662 on Token Introspection says that "The means by which the protected resource discovers the location of the introspection
+      endpoint are outside the scope of this specification" and the Token Introspection IG does not add any further
+      requirements to this.
+
+      If the token introspection endpoint of the system under test is NOT available at .well-known/smart-configuration,
+      please run the test groups individually and group 3 Token Introspection will include the introspection endpoint as a manual input.
+    )
+
+    group do
+      title 'Standalone Launch'
+      id :smart_full_standalone_launch
+
+      input_instructions <<~INSTRUCTIONS
+        Please register the Inferno client as a SMART App with the following
+        information:
+
+        * OAuth Redirect URI: `#{config.options[:redirect_uri]}`
+
+        If using asymmetric client authentication, register Inferno with the
+        following JWK Set URL:
+
+        * `#{Inferno::Application[:base_url]}/custom/smart_stu2_2/.well-known/jwks.json`
+      INSTRUCTIONS
+
+      run_as_group
+
+      group from: :smart_discovery_stu2
+      group from: :smart_standalone_launch_stu2_2
+
+      group from: :smart_openid_connect,
+            config: {
+              inputs: {
+                id_token: { name: :standalone_id_token },
+                client_id: { name: :standalone_client_id },
+                requested_scopes: { name: :standalone_requested_scopes },
+                access_token: { name: :standalone_access_token },
+                smart_credentials: { name: :standalone_smart_credentials }
+              }
+            }
+
+      group from: :smart_token_refresh_stu2,
+            id: :smart_standalone_refresh_without_scopes,
+            title: 'SMART Token Refresh Without Scopes',
+            config: {
+              inputs: {
+                refresh_token: { name: :standalone_refresh_token },
+                client_id: { name: :standalone_client_id },
+                client_secret: { name: :standalone_client_secret },
+                received_scopes: { name: :standalone_received_scopes }
+              },
+              outputs: {
+                refresh_token: { name: :standalone_refresh_token },
+                received_scopes: { name: :standalone_received_scopes },
+                access_token: { name: :standalone_access_token },
+                token_retrieval_time: { name: :standalone_token_retrieval_time },
+                expires_in: { name: :standalone_expires_in },
+                smart_credentials: { name: :standalone_smart_credentials }
+              }
+            }
+
+      group from: :smart_token_refresh_stu2,
+            id: :smart_standalone_refresh_with_scopes,
+            title: 'SMART Token Refresh With Scopes',
+            config: {
+              options: { include_scopes: true },
+              inputs: {
+                refresh_token: { name: :standalone_refresh_token },
+                client_id: { name: :standalone_client_id },
+                client_secret: { name: :standalone_client_secret },
+                received_scopes: { name: :standalone_received_scopes }
+              },
+              outputs: {
+                refresh_token: { name: :standalone_refresh_token },
+                received_scopes: { name: :standalone_received_scopes },
+                access_token: { name: :standalone_access_token },
+                token_retrieval_time: { name: :standalone_token_retrieval_time },
+                expires_in: { name: :standalone_expires_in },
+                smart_credentials: { name: :standalone_smart_credentials }
+              }
+            }
+    end
+
+    group do
+      title 'EHR Launch'
+      id :smart_full_ehr_launch
+
+      input_instructions <<~INSTRUCTIONS
+        Please register the Inferno client as a SMART App with the following
+        information:
+
+        * SMART Launch URI: `#{config.options[:launch_uri]}`
+        * OAuth Redirect URI: `#{config.options[:redirect_uri]}`
+
+        If using asymmetric client authentication, register Inferno with the
+        following JWK Set URL:
+
+        * `#{Inferno::Application[:base_url]}/custom/smart_stu2_2/.well-known/jwks.json`
+      INSTRUCTIONS
+
+      run_as_group
+
+      group from: :smart_discovery_stu2
+
+      group from: :smart_ehr_launch_stu2_2
+
+      group from: :smart_openid_connect,
+            config: {
+              inputs: {
+                id_token: { name: :ehr_id_token },
+                client_id: { name: :ehr_client_id },
+                requested_scopes: { name: :ehr_requested_scopes },
+                access_token: { name: :ehr_access_token },
+                smart_credentials: { name: :ehr_smart_credentials }
+              }
+            }
+
+      group from: :smart_token_refresh_stu2,
+            id: :smart_ehr_refresh_without_scopes,
+            title: 'SMART Token Refresh Without Scopes',
+            config: {
+              inputs: {
+                refresh_token: { name: :ehr_refresh_token },
+                client_id: { name: :ehr_client_id },
+                client_secret: { name: :ehr_client_secret },
+                received_scopes: { name: :ehr_received_scopes }
+              },
+              outputs: {
+                refresh_token: { name: :ehr_refresh_token },
+                received_scopes: { name: :ehr_received_scopes },
+                access_token: { name: :ehr_access_token },
+                token_retrieval_time: { name: :ehr_token_retrieval_time },
+                expires_in: { name: :ehr_expires_in },
+                smart_credentials: { name: :ehr_smart_credentials }
+              }
+            }
+
+      group from: :smart_token_refresh_stu2,
+            id: :smart_ehr_refresh_with_scopes,
+            title: 'SMART Token Refresh With Scopes',
+            config: {
+              options: { include_scopes: true },
+              inputs: {
+                refresh_token: { name: :ehr_refresh_token },
+                client_id: { name: :ehr_client_id },
+                client_secret: { name: :ehr_client_secret },
+                received_scopes: { name: :ehr_received_scopes }
+              },
+              outputs: {
+                refresh_token: { name: :ehr_refresh_token },
+                received_scopes: { name: :ehr_received_scopes },
+                access_token: { name: :ehr_access_token },
+                token_retrieval_time: { name: :ehr_token_retrieval_time },
+                expires_in: { name: :ehr_expires_in },
+                smart_credentials: { name: :ehr_smart_credentials }
+              }
+            }
+    end
+
+    group do
+      title 'Backend Services'
+      id :smart_backend_services
+
+      input_instructions <<~INSTRUCTIONS
+        Please register the Inferno client with the authorization services with the
+        following JWK Set URL:
+
+        * `#{Inferno::Application[:base_url]}/custom/smart_stu2_2/.well-known/jwks.json`
+      INSTRUCTIONS
+
+      run_as_group
+
+      group from: :smart_discovery_stu2
+      group from: :backend_services_authorization
+    end
+
+    group from: :smart_token_introspection_stu2_2
+  end
+end

data/lib/smart_app_launch/standalone_launch_group_stu2_2.rb

@@ -0,0 +1,52 @@
+require_relative 'token_response_body_test_stu2_2'
+require_relative 'standalone_launch_group_stu2'
+
+module SMARTAppLaunch
+  class StandaloneLaunchGroupSTU22 < StandaloneLaunchGroupSTU2
+    id :smart_standalone_launch_stu2_2
+    description %(
+      # Background
+
+      The [Standalone
+      Launch Sequence](http://hl7.org/fhir/smart-app-launch/STU2.2/app-launch.html#launch-app-standalone-launch)
+      allows an app, like Inferno, to be launched independent of an
+      existing EHR session. It is one of the two launch methods described in
+      the SMART App Launch Framework alongside EHR Launch. The app will
+      request authorization for the provided scope from the authorization
+      endpoint, ultimately receiving an authorization token which can be used
+      to gain access to resources on the FHIR server.
+
+      # Test Methodology
+
+      Inferno will redirect the user to the the authorization endpoint so that
+      they may provide any required credentials and authorize the application.
+      Upon successful authorization, Inferno will exchange the authorization
+      code provided for an access token.
+
+      For more information on the #{title}:
+
+      * [Standalone Launch Sequence](http://hl7.org/fhir/smart-app-launch/STU2.2/app-launch.html#launch-app-standalone-launch)
+    )
+
+    config(
+      inputs: {
+        use_pkce: {
+          default: 'true',
+          locked: true
+        },
+        pkce_code_challenge_method: {
+          default: 'S256',
+          locked: true
+        },
+        requested_scopes: {
+          default: 'launch/patient openid fhirUser offline_access patient/*.rs'
+        }
+      }
+    )
+
+    test from: :smart_token_response_body_stu2_2
+
+    token_response_body_index = children.find_index { |child| child.id.to_s.end_with? 'token_response_body' }
+    children[token_response_body_index] = children.pop
+  end
+end

data/lib/smart_app_launch/token_introspection_access_token_group_stu2_2.rb

@@ -0,0 +1,28 @@
+require_relative 'standalone_launch_group_stu2_2'
+
+module SMARTAppLaunch
+  class SMARTTokenIntrospectionAccessTokenGroupSTU22 < SMARTTokenIntrospectionAccessTokenGroup
+    title 'Request New Access Token to Introspect'
+    run_as_group
+
+    id :smart_token_introspection_access_token_group_stu2_2
+
+    description %(
+      These tests are repeated from the Standalone Launch tests in order to receive a new, active access token that
+      will be provided for token introspection. This test group may be skipped if the tester can obtain an access token
+      __and__ the contents of the access token response body by some other means.
+
+      These tests are currently designed such that the token introspection URL must be present in the SMART well-known endpoint.
+
+    )
+
+    input_instructions %(
+      Register Inferno as a Standalone SMART App and provide the registration details below.
+    )
+
+    group from: :smart_standalone_launch_stu2_2
+
+    standalone_launch_index = children.find_index { |child| child.id.to_s.end_with? 'standalone_launch_stu2' }
+    children[standalone_launch_index] = children.pop
+  end
+end

data/lib/smart_app_launch/token_introspection_group_stu2_2.rb

@@ -0,0 +1,68 @@
+require_relative 'token_introspection_access_token_group_stu2_2'
+require_relative 'token_introspection_group'
+
+module SMARTAppLaunch
+  class SMARTTokenIntrospectionGroupSTU22 < SMARTTokenIntrospectionGroup
+    title 'Token Introspection'
+    id :smart_token_introspection_stu2_2
+    description %(
+      # Background
+
+      OAuth 2.0 Token introspection, as described in [RFC-7662](https://datatracker.ietf.org/doc/html/rfc7662), allows
+      an authorized resource server to query an OAuth 2.0 authorization server for metadata on a token.  The
+      [SMART App Launch STU2.2 Implementation Guide Section on Token Introspection](https://hl7.org/fhir/smart-app-launch/STU2.2/token-introspection.html)
+      states that "SMART on FHIR EHRs SHOULD support token introspection, which allows a broader ecosystem of resource servers
+      to leverage authorization decisions managed by a single authorization server."
+
+      # Test Methodology
+
+      In these tests, Inferno acts as an authorized resource server that queries the authorization server about an access
+      token, rather than a client to a FHIR resource server as in the previous SMART App Launch tests.
+      Ideally, Inferno should be registered with the authorization server as an authorized resource server
+      capable of accessing the token introspection endpoint through client credentials, per the SMART IG recommendations.
+      However, the SMART IG only formally REQUIRES "some form of authorization" to access
+      the token introspection endpoint and does not specifiy any one specific approach.  As such, the token introspection tests are
+      broken up into three groups that each complete a discrete step in the token introspection process:
+
+      1. **Request Access Token Group** - optional but recommended, repeats a subset of Standalone Launch tests
+        in order to receive a new access token with an authorization code grant.  If skipped, testers will need to
+          obtain an access token out-of-band and manually provide values from the access token response as inputs to
+          the Validate Token Response group.
+      2. **Issue Token Introspection Request Group** - optional but recommended, completes the introspection requests.
+      If skipped, testers will need to complete an introspection request out-of-band and manually provide the introspection
+      responses as inputs to the Validate Token Response group.
+      3. **Validate Token Introspection Response Group** - required, validates the contents of the introspection responses.
+
+      Running all three test groups in order is the simplest and is highly recommended if the environment under test
+      can support it, as outputs from one group will feed the inputs of the next group. However, test groups can be run
+      independently if needed.
+
+      See the individual test groups for more details and guidance.
+    )
+    group from: :smart_token_introspection_access_token_group_stu2_2
+
+    access_token_group_index = children.find_index { |child| child.id.to_s.end_with? 'access_token_group' }
+    children[access_token_group_index] = children.pop
+
+    input_order :url, :standalone_client_id, :standalone_client_secret,
+                :authorization_method, :use_pkce, :pkce_code_challenge_method,
+                :standalone_requested_scopes, :client_auth_encryption_method,
+                :client_auth_type, :custom_authorization_header,
+                :optional_introspection_request_params
+    input_instructions %(
+      Executing tests at this level will run all three Token Introspection groups back-to-back.  If test groups need
+      to be run independently, exit this window and select a specific test group instead.
+
+      These tests are currently designed such that the token introspection URL must be present in the SMART well-known endpoint.
+
+      If the introspection endpoint is protected, testers must enter their own HTTP Authorization header for the introspection request.  See
+      [RFC 7616 The 'Basic' HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617) for the most common
+      approach that uses client credentials.  Testers may also provide any additional parameters needed for their authorization
+      server to complete the introspection request.
+
+      **Note:** For both the Authorization header and request parameters, user-input
+      values will be sent exactly as entered and therefore the tester must
+      URI-encode any appropriate values.
+    )
+  end
+end