smart_app_launch_test_kit 0.0.1

data/lib/smart_app_launch/launch_received_test.rb

@@ -0,0 +1,19 @@
+module SMARTAppLaunch
+  class LaunchReceivedTest < Inferno::Test
+    title 'EHR server sends launch parameter'
+    description %(
+      Code is a required querystring parameter on the redirect.
+    )
+    id :smart_launch_received
+
+    output :launch
+    uses_request :launch
+
+    run do
+      launch = request.query_parameters['launch']
+      output launch: launch
+
+      assert launch.present?, 'No `launch` paramater received'
+    end
+  end
+end

data/lib/smart_app_launch/openid_connect_group.rb

@@ -0,0 +1,83 @@
+require 'jwt'
+require_relative 'openid_decode_id_token_test'
+require_relative 'openid_retrieve_configuration_test'
+require_relative 'openid_required_configuration_fields_test'
+require_relative 'openid_retrieve_jwks_test'
+require_relative 'openid_token_header_test'
+require_relative 'openid_token_payload_test'
+require_relative 'openid_fhir_user_claim_test'
+
+module SMARTAppLaunch
+  class OpenIDConnectGroup < Inferno::TestGroup
+    id :smart_openid_connect
+    title 'OpenID Connect'
+
+    description %(
+      # Background
+
+      OpenID Connect (OIDC) provides the ability to verify the identity of the
+      authorizing user. Within the [SMART App Launch
+      Framework](http://hl7.org/fhir/smart-app-launch/), Applications can
+      request an `id_token` be provided with by including the `openid fhirUser`
+      scopes when requesting authorization.
+
+      # Test Methodology
+
+      This sequence validates the id token returned as part of the OAuth 2.0
+      token response. Once the token is decoded, the server's OIDC configuration
+      is retrieved from its well-known configuration endpoint. This
+      configuration is checked to ensure that all required fields are present.
+      Next the keys used to cryptographically sign the id token are retrieved
+      from the url contained in the OIDC configuration. Then the header,
+      payload, and signature of the id token are validated. Finally, the FHIR
+      resource from the `fhirUser` claim in the id token is fetched from the
+      FHIR server.
+
+      For more information see:
+
+      * [SMART App Launch Framework](http://hl7.org/fhir/smart-app-launch/)
+      * [Scopes for requesting identity data](http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html#scopes-for-requesting-identity-data)
+      * [Apps Requesting Authorization](http://hl7.org/fhir/smart-app-launch/#step-1-app-asks-for-authorization)
+      * [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
+    )
+
+    test from: :smart_openid_decode_id_token
+
+    test from: :smart_openid_retrieve_configuration
+
+    test from: :smart_openid_required_configuration_fields
+
+    test from: :smart_openid_retrieve_jwks
+
+    test from: :smart_openid_token_header
+
+    test from: :smart_openid_token_payload
+
+    test from: :smart_openid_fhir_user_claim
+
+    # test do
+    #   id :smart_openid_fhir_user_retrieval
+    #   title 'fhirUser can be retrieved'
+    #   description %(
+    #     Verify that the FHIR resource referred to in the `fhirUser` claim can be
+    #     retrieved.
+    #   )
+
+    #   input :id_token_fhir_user, :openid_issuer, :standalone_access_token
+    #   makes_request :id_token_fhir_user
+
+    #   run do
+    #     skip_if id_token_fhir_user.blank?
+
+    #     split_fhir_user = id_token_fhir_user.split('/')
+    #     resource_type = split_fhir_user[-2]
+    #     resource_id = split_fhir_user[-1]
+    #     fhir_read(resource_type, resource_id)
+
+    #     assert_response_status(200)
+    #     assert_valid_json(response[:body])
+    #     assert_resource_type(resource_type)
+    #   end
+    # end
+  end
+end

data/lib/smart_app_launch/openid_decode_id_token_test.rb

@@ -0,0 +1,30 @@
+module SMARTAppLaunch
+  class OpenIDDecodeIDTokenTest < Inferno::Test
+    id :smart_openid_decode_id_token
+    title 'ID token can be decoded'
+    description %(
+        Verify that the ID token is a properly constructed JWT.
+      )
+
+    input :id_token
+    output :id_token_payload_json, :id_token_header_json
+
+    run do
+      skip_if id_token.blank?
+
+      begin
+        payload, header =
+          JWT.decode(
+            id_token,
+            nil,
+            false
+          )
+
+        output id_token_payload_json: payload.to_json,
+               id_token_header_json: header.to_json
+      rescue StandardError => e
+        assert false, "ID token is not a properly constructed JWT: #{e.message}"
+      end
+    end
+  end
+end

data/lib/smart_app_launch/openid_fhir_user_claim_test.rb

@@ -0,0 +1,30 @@
+module SMARTAppLaunch
+  class OpenIDFHIRUserClaimTest < Inferno::Test
+    id :smart_openid_fhir_user_claim
+    title 'ID token contains a valid fhirUser claim'
+    description %(
+        Verify that the `fhirUser` claim is present in the ID token. The
+        `fhirUser` claim must be the url for a Patient, Practitioner,
+        RelatedPerson, or Person resource.
+      )
+
+    input :id_token_payload_json, :requested_scopes
+    output :id_token_fhir_user
+
+    run do
+      skip_if id_token_payload_json.blank?
+      skip_if !requested_scopes&.include?('fhirUser'), '`fhirUser` scope not requested'
+
+      payload = JSON.parse(id_token_payload_json)
+      fhir_user = payload['fhirUser']
+
+      valid_fhir_user_resource_types = ['Patient', 'Practitioner', 'RelatedPerson', 'Person']
+
+      assert fhir_user.present?, 'ID token does not contain `fhirUser` claim'
+      assert valid_fhir_user_resource_types.any? { |type| fhir_user.include? type },
+             "ID token `fhirUser` claim does not refer to a valid resource type: #{fhir_user}"
+
+      output id_token_fhir_user: fhir_user
+    end
+  end
+end

data/lib/smart_app_launch/openid_required_configuration_fields_test.rb

@@ -0,0 +1,50 @@
+module SMARTAppLaunch
+  class OpenIDRequiredConfigurationFieldsTest < Inferno::Test
+    id :smart_openid_required_configuration_fields
+    title 'OpenID Connect well-known configuration contains all required fields'
+    description %(
+      Verify that the OpenId Connect configuration contains the following
+      required fields: `issuer`, `authorization_endpoint`, `token_endpoint`,
+      `jwks_uri`, `response_types_supported`, `subject_types_supported`, and
+      `id_token_signing_alg_values_supported`.
+
+      Additionally, the [SMART App Launch
+      Framework](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html#scopes-for-requesting-identity-data)
+      requires that the RSA SHA-256 signing algorithm be supported.
+    )
+
+    input :openid_configuration_json
+    output :openid_jwks_uri
+
+    REQUIRED_FIELDS =
+      [
+        'issuer',
+        'authorization_endpoint',
+        'token_endpoint',
+        'jwks_uri',
+        'response_types_supported',
+        'subject_types_supported',
+        'id_token_signing_alg_values_supported'
+      ].freeze
+
+    def required_fields
+      REQUIRED_FIELDS.dup
+    end
+
+    run do
+      skip_if openid_configuration_json.blank?
+
+      configuration = JSON.parse(openid_configuration_json)
+      output openid_jwks_uri: configuration['jwks_uri']
+
+      missing_fields = required_fields - configuration.keys
+      missing_fields_string = missing_fields.map { |field| "`#{field}`" }.join(', ')
+
+      assert missing_fields.empty?,
+             "OpenID Connect well-known configuration missing required fields: #{missing_fields_string}"
+
+      assert configuration['id_token_signing_alg_values_supported'].include?('RS256'),
+             'Signing tokens with RSA SHA-256 not supported'
+    end
+  end
+end

data/lib/smart_app_launch/openid_retrieve_configuration_test.rb

@@ -0,0 +1,31 @@
+module SMARTAppLaunch
+  class OpenIDRetrieveConfigurationTest < Inferno::Test
+    id :smart_openid_retrieve_configuration
+    title 'OpenID Connect well-known configuration can be retrieved'
+    description %(
+        Verify that the OpenId Connect configuration can be retrieved as
+        described in the OpenID Connect Discovery 1.0 documentation.
+      )
+
+    input :id_token_payload_json
+    output :openid_configuration_json, :openid_issuer
+    makes_request :openid_configuration
+
+    run do
+      skip_if id_token_payload_json.blank?
+
+      payload = JSON.parse(id_token_payload_json)
+      issuer = payload['iss']
+
+      configuration_url = "#{issuer.chomp('/')}/.well-known/openid-configuration"
+      get(configuration_url, name: :openid_configuration)
+
+      assert_response_status(200)
+      assert_response_content_type('application/json')
+      assert_valid_json(response[:body])
+
+      output openid_configuration_json: response[:body],
+             openid_issuer: issuer
+    end
+  end
+end

data/lib/smart_app_launch/openid_retrieve_jwks_test.rb

@@ -0,0 +1,43 @@
+module SMARTAppLaunch
+  class OpenIDRetrieveJWKSTest < Inferno::Test
+    id :smart_openid_retrieve_jwks
+    title 'JWKS can be retrieved'
+    description %(
+        Verify that the JWKS can be retrieved from the `jwks_uri` from the
+        OpenID Connect well-known configuration.
+      )
+
+    input :openid_jwks_uri
+    output :openid_jwks_json, :openid_rsa_keys_json
+    makes_request :openid_jwks
+
+    run do
+      skip_if openid_jwks_uri.blank?
+
+      get(openid_jwks_uri, name: :openid_jwks)
+
+      assert_response_status(200)
+      assert_valid_json(response[:body])
+      output openid_jwks_json: response[:body]
+
+      raw_jwks = JSON.parse(response[:body])
+      assert raw_jwks['keys'].is_a?(Array), 'JWKS `keys` field must be an array'
+
+      # https://tools.ietf.org/html/rfc7517#section-5
+      # Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
+      # (key type) values that are not understood by them.
+      # SMART only requires support of RSA SHA-256 keys
+      rsa_keys = raw_jwks['keys'].select { |jwk| jwk['kty'] == 'RSA' }
+
+      assert rsa_keys.present?, 'JWKS contains no RSA keys'
+
+      rsa_keys.each do |jwk|
+        JWT::JWK.import(jwk.deep_symbolize_keys)
+      rescue StandardError
+        assert false, "Invalid JWK: #{jwk.to_json}"
+      end
+
+      output openid_rsa_keys_json: rsa_keys.to_json
+    end
+  end
+end

data/lib/smart_app_launch/openid_token_header_test.rb

@@ -0,0 +1,39 @@
+module SMARTAppLaunch
+  class OpenIDTokenHeaderTest < Inferno::Test
+    id :smart_openid_token_header
+    title 'ID token header contains required information'
+    description %(
+      Verify that the id token header indicates that the tokenis signed using
+      RSA SHA-256 [as required by the SMART app launch
+      framework](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html#scopes-for-requesting-identity-data)
+      and that the key used to sign the token can be identified in the JWKS.
+    )
+
+    input :id_token_header_json, :openid_rsa_keys_json
+    output :id_token_jwk_json
+
+    run do
+      skip_if id_token_header_json.blank?
+      skip_if openid_rsa_keys_json.blank?
+
+      header = JSON.parse(id_token_header_json)
+      algorithm = header['alg']
+
+      assert algorithm == 'RS256', "ID Token signed with `#{algorithm}` rather than RS256"
+
+      kid = header['kid']
+      rsa_keys = JSON.parse(openid_rsa_keys_json)
+
+      if rsa_keys.length > 1
+        assert kid.present?, '`kid` field must be present if JWKS contains multiple keys'
+        jwk = rsa_keys.find { |key| key['kid'] == kid }
+        assert jwk.present?, "JWKS did not contain an RS256 key with an id of `#{kid}`"
+      else
+        jwk = rsa_keys.first
+        assert kid.blank? || jwk['kid'] == kid, "JWKS did not contain an RS256 key with an id of `#{kid}`"
+      end
+
+      output id_token_jwk_json: jwk.to_json
+    end
+  end
+end

data/lib/smart_app_launch/openid_token_payload_test.rb

@@ -0,0 +1,64 @@
+require_relative 'token_payload_validation'
+
+module SMARTAppLaunch
+  class OpenIDTokenPayloadTest < Inferno::Test
+    include TokenPayloadValidation
+    id :smart_openid_token_payload
+    title 'ID token payload has required claims and a valid signature'
+    description %(
+      The `iss`, `sub`, `aud`, `exp`, and `iat` claims are required.
+      Additionally:
+
+      - `iss` must match the `issuer` from the OpenID Connect well-known
+        configuration
+      - `aud` must match the client ID
+      - `exp` must represent a time in the future
+    )
+
+    REQUIRED_CLAIMS = ['iss', 'sub', 'aud', 'exp', 'iat'].freeze
+
+    def required_claims
+      REQUIRED_CLAIMS.dup
+    end
+
+    input :id_token,
+          :openid_configuration_json,
+          :id_token_jwk_json,
+          :client_id
+
+    run do
+      skip_if id_token.blank?, 'No ID Token'
+      skip_if openid_configuration_json.blank?, 'No OpenID Configuration found'
+      skip_if id_token_jwk_json.blank?, 'No ID Token jwk found'
+      skip_if client_id.blank?, 'No Client ID'
+
+      begin
+        configuration = JSON.parse(openid_configuration_json)
+        jwk = JSON.parse(id_token_jwk_json).deep_symbolize_keys
+        payload, =
+          JWT.decode(
+            id_token,
+            JWT::JWK.import(jwk).public_key,
+            true,
+            algorithms: ['RS256'],
+            exp_leeway: 60,
+            iss: configuration['issuer'],
+            aud: client_id,
+            verify_not_before: false,
+            verify_iat: false,
+            verify_jti: false,
+            verify_sub: false,
+            verify_iss: true,
+            verify_aud: true
+          )
+      rescue StandardError => e
+        assert false, "Token validation error: #{e.message}"
+      end
+
+      missing_claims = required_claims - payload.keys
+      missing_claims_string = missing_claims.map { |claim| "`#{claim}`" }.join(', ')
+
+      assert missing_claims.empty?, "ID token missing required claims: #{missing_claims_string}"
+    end
+  end
+end

data/lib/smart_app_launch/standalone_launch_group.rb

@@ -0,0 +1,104 @@
+require_relative 'app_redirect_test'
+require_relative 'code_received_test'
+require_relative 'token_exchange_test'
+require_relative 'token_response_body_test'
+require_relative 'token_response_headers_test'
+
+module SMARTAppLaunch
+  class StandaloneLaunchGroup < Inferno::TestGroup
+    id :smart_standalone_launch
+    title 'SMART Standalone Launch'
+
+    description %(
+      # Background
+
+      The [Standalone
+      Launch](http://hl7.org/fhir/smart-app-launch/#standalone-launch-sequence)
+      Sequence 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/#standalone-launch-sequence)
+    )
+
+    config(
+      inputs: {
+        client_id: {
+          name: :standalone_client_id,
+          title: 'Standalone Client ID',
+          description: 'Client ID provided during registration of Inferno as a standalone application',
+          default: 'SAMPLE_PUBLIC_CLIENT_ID'
+        },
+        client_secret: {
+          name: :standalone_client_secret,
+          title: 'Standalone Client Secret',
+          description: 'Client Secret provided during registration of Inferno as a standalone application'
+        },
+        requested_scopes: {
+          name: :standalone_requested_scopes,
+          title: 'Standalone Scope',
+          description: 'OAuth 2.0 scope provided by system to enable all required functionality',
+          type: 'textarea',
+          default: %(
+            launch/patient openid fhirUser offline_access
+            patient/Medication.read patient/AllergyIntolerance.read
+            patient/CarePlan.read patient/CareTeam.read patient/Condition.read
+            patient/Device.read patient/DiagnosticReport.read
+            patient/DocumentReference.read patient/Encounter.read
+            patient/Goal.read patient/Immunization.read patient/Location.read
+            patient/MedicationRequest.read patient/Observation.read
+            patient/Organization.read patient/Patient.read
+            patient/Practitioner.read patient/Procedure.read
+            patient/Provenance.read patient/PractitionerRole.read
+          ).gsub(/\s{2,}/, ' ').strip
+        },
+        url: {
+          title: 'Standalone FHIR Endpoint',
+          description: 'URL of the FHIR endpoint used by standalone applications',
+          default: 'https://inferno.healthit.gov/reference-server/r4'
+        },
+        code: {
+          name: :standalone_code
+        },
+        state: {
+          name: :standalone_state
+        }
+      },
+      outputs: {
+        code: { name: :standalone_code },
+        token_retrieval_time: { name: :standalone_token_retrieval_time },
+        state: { name: :standalone_state },
+        id_token: { name: :standalone_id_token },
+        refresh_token: { name: :standalone_refresh_token },
+        access_token: { name: :standalone_access_token },
+        expires_in: { name: :standalone_expires_in },
+        patient_id: { name: :standalone_patient_id },
+        encounter_id: { name: :standalone_encounter_id },
+        received_scopes: { name: :standalone_received_scopes },
+        intent: { name: :standalone_intent }
+      },
+      requests: {
+        redirect: { name: :standalone_redirect },
+        token: { name: :standalone_token }
+      }
+    )
+
+    test from: :smart_app_redirect
+    test from: :smart_code_received
+    test from: :smart_token_exchange
+    test from: :smart_token_response_body
+    test from: :smart_token_response_headers
+  end
+end

data/lib/smart_app_launch/token_exchange_test.rb

@@ -0,0 +1,47 @@
+module SMARTAppLaunch
+  class TokenExchangeTest < Inferno::Test
+    title 'OAuth token exchange request succeeds when supplied correct information'
+    description %(
+      After obtaining an authorization code, the app trades the code for an
+      access token via HTTP POST to the EHR authorization server's token
+      endpoint URL, using content-type application/x-www-form-urlencoded, as
+      described in section [4.1.3 of
+      RFC6749](https://tools.ietf.org/html/rfc6749#section-4.1.3).
+    )
+    id :smart_token_exchange
+
+    input :code,
+          :smart_token_url,
+          :client_id
+    input :client_secret, optional: true
+    output :token_retrieval_time
+    uses_request :redirect
+    makes_request :token
+
+    config options: { redirect_uri: "#{Inferno::Application['inferno_host']}/custom/smart/redirect" }
+
+    run do
+      skip_if request.query_parameters['error'].present?, 'Error during authorization request'
+
+      oauth2_params = {
+        grant_type: 'authorization_code',
+        code: code,
+        redirect_uri: config.options[:redirect_uri]
+      }
+      oauth2_headers = { 'Content-Type' => 'application/x-www-form-urlencoded' }
+
+      if client_secret.present?
+        client_credentials = "#{client_id}:#{client_secret}"
+        oauth2_headers['Authorization'] = "Basic #{Base64.strict_encode64(client_credentials)}"
+      else
+        oauth2_params[:client_id] = client_id
+      end
+
+      post(smart_token_url, body: oauth2_params, name: :token, headers: oauth2_headers)
+
+      output token_retrieval_time: Time.now.iso8601
+
+      assert_response_status(200)
+    end
+  end
+end

data/lib/smart_app_launch/token_payload_validation.rb

@@ -0,0 +1,47 @@
+module SMARTAppLaunch
+  module TokenPayloadValidation
+    STRING_FIELDS = ['access_token', 'token_type', 'scope', 'refresh_token'].freeze
+    NUMERIC_FIELDS = ['expires_in'].freeze
+
+    def validate_required_fields_present(body, required_fields)
+      missing_fields = required_fields.select { |field| body[field].blank? }
+      missing_fields_string = missing_fields.map { |field| "`#{field}`" }.join(', ')
+      assert missing_fields.empty?,
+             "Token exchange response did not include all required fields: #{missing_fields_string}."
+    end
+
+    def validate_token_type(body)
+      assert body['token_type'].casecmp('bearer').zero?, '`token_type` must be `bearer`'
+    end
+
+    def check_for_missing_scopes(requested_scopes, body)
+      expected_scopes = requested_scopes.split
+      new_scopes = body['scope'].split
+      missing_scopes = expected_scopes - new_scopes
+
+      warning do
+        missing_scopes_string = missing_scopes.map { |scope| "`#{scope}`" }.join(', ')
+        assert missing_scopes.empty?, %(
+          Token exchange response did not include all requested scopes.
+          These may have been denied by user: #{missing_scopes_string}.
+        )
+      end
+    end
+
+    def validate_token_field_types(body)
+      STRING_FIELDS
+        .select { |field| body[field].present? }
+        .each do |field|
+        assert body[field].is_a?(String),
+               "Expected `#{field}` to be a String, but found #{body[field].class.name}"
+      end
+
+      NUMERIC_FIELDS
+        .select { |field| body[field].present? }
+        .each do |field|
+          assert body[field].is_a?(Numeric),
+                 "Expected `#{field}` to be a Numeric, but found #{body[field].class.name}"
+        end
+    end
+  end
+end

data/lib/smart_app_launch/token_refresh_body_test.rb

@@ -0,0 +1,52 @@
+require_relative 'token_payload_validation'
+
+module SMARTAppLaunch
+  class TokenRefreshBodyTest < Inferno::Test
+    include TokenPayloadValidation
+
+    id :smart_token_refresh_body
+    title 'Server successfully refreshes the access token when optional scope parameter omitted'
+    description %(
+      Server successfully exchanges refresh token at OAuth token endpoint
+      without providing scope in the body of the request.
+
+      The EHR authorization server SHALL return a JSON structure that includes
+      an access token or a message indicating that the authorization request
+      has been denied. `access_token`, `expires_in`, `token_type`, and `scope` are
+      required. `access_token` must be `Bearer`.
+
+      Although not required in the token refresh portion of the SMART App
+      Launch Guide, the token refresh response should include the HTTP
+      Cache-Control response header field with a value of no-store, as well as
+      the Pragma response header field with a value of no-cache to be
+      consistent with the requirements of the inital access token exchange.
+    )
+    input :received_scopes
+    output :refresh_token, :access_token, :token_retrieval_time, :expires_in, :received_scopes
+    uses_request :token_refresh
+
+    run do
+      skip_if request.status != 200, 'Token exchange was unsuccessful'
+
+      assert_valid_json(response[:body])
+
+      body = JSON.parse(response[:body])
+      output refresh_token: body['refresh_token'] if body.key? 'refresh_token'
+
+      required_fields = ['access_token', 'token_type', 'expires_in', 'scope']
+      validate_required_fields_present(body, required_fields)
+
+      old_received_scopes = received_scopes
+      output access_token: body['access_token'],
+             token_retrieval_time: Time.now.iso8601,
+             expires_in: body['expires_in'],
+             received_scopes: body['scope']
+
+      validate_token_field_types(body)
+      validate_token_type(body)
+
+      assert received_scopes.split.sort == old_received_scopes.split.sort,
+             'Received scopes not equal to originally granted scopes'
+    end
+  end
+end