smart_app_launch_test_kit 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60325a0cc4d2866edb260627b289e76676d0847bd2e28523556f39170d424dac
-  data.tar.gz: dd887ba5a645f71f16e9f2269886628ca5911d57c79e3d03699582d6ae810b7f
+  metadata.gz: f66c9b0314200d03d78422dc6412fe30cd0a091cd34d2a4701b9daa9a85d45f6
+  data.tar.gz: 7a34428293bfe281ebeebf83e8ee37597ebdfef2bf158cb8a3893598eca09876
 SHA512:
-  metadata.gz: 16ee6a9963940d5ea882e894b5e1db23646c86a51e1f6dbe58868878c047708a581c0f353ba24d264a4c49cdc8f549f522afc40ee7bbd5127d89b0b9ac7f2e36
-  data.tar.gz: 022f7b43c590f419638e23614a84dc0c5d106b87bbef38dd6d4b2e71650b58bf86db59bd6bb231c04280a0274e105b6486601fb41fa3749485ddfd534a15beb4
+  metadata.gz: d5f432c1b4b43a2c84be8613acb0b31dec557b80b1b76996773c76486db5197265a3dc1f0b9a9015eaa35c17c65d5b6b7eb506d940676e0cdae3b798b1cf8799
+  data.tar.gz: b63b86f90dbfc0ea88b7cc65e2075333b07a2cee7d42f88f21d209f4a51274545532706ed0278efad3cd4a0316be4ae32e948632f4ba66247d5451c68eff9559

data/lib/smart_app_launch/backend_services_authorization_group.rb

@@ -0,0 +1,88 @@
+require_relative 'backend_services_authorization_request_builder'
+require_relative 'backend_services_invalid_grant_type_test'
+require_relative 'backend_services_invalid_client_assertion_test'
+require_relative 'backend_services_invalid_jwt_test'
+require_relative 'backend_services_authorization_request_success_test'
+require_relative 'backend_services_authorization_response_body_test'
+require_relative 'token_exchange_stu2_test'
+
+module SMARTAppLaunch
+  class BackendServicesAuthorizationGroup < Inferno::TestGroup
+    title 'SMART Backend Services Authorization'
+    short_description 'Demonstrate SMART Backend Services Authorization'
+
+    id :backend_services_authorization
+
+    input :smart_token_url,
+          title: 'Backend Services Token Endpoint',
+          description: <<~DESCRIPTION
+            The OAuth 2.0 Token Endpoint used by the Backend Services specification to provide bearer tokens.
+          DESCRIPTION
+
+    input :backend_services_client_id,
+          title: 'Backend Services Client ID',
+          description: 'Client ID provided at registration to the Inferno application.'
+    input :backend_services_requested_scope,
+          title: 'Backend Services Requested Scopes',
+          description: 'Backend Services Scopes provided at registration to the Inferno application; will be `system/` scopes',
+          default: 'system/*.read'
+
+    input :client_auth_encryption_method,
+      title: 'Encryption Method for Asymmetric Confidential Client Authorization',
+      description: <<~DESCRIPTION,
+        The server is required to suport either ES384 or RS384 encryption methods for JWT signature verification.
+        Select which method to use.
+      DESCRIPTION
+      type: 'radio',
+      default: 'ES384',
+      options: {
+        list_options: [
+          {
+            label: 'ES384',
+            value: 'ES384'
+          },
+          {
+            label: 'RS384',
+            value: 'RS384'
+          }
+        ]
+      }
+    input :backend_services_jwks_kid,
+          title: 'Backend Services JWKS kid',
+          description: <<~DESCRIPTION,
+            The key ID of the JWKS private key to use for signing the client assertion when fetching an auth token.
+            Defaults to the first JWK in the list if no kid is supplied.
+          DESCRIPTION
+          optional: true
+
+    output :bearer_token
+
+    test from: :tls_version_test do
+      title 'Authorization service token endpoint secured by transport layer security'
+      description <<~DESCRIPTION
+        The [SMART App Launch 2.0.0 IG specification for Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#request-1)
+        states "the client SHALL use the Transport Layer Security (TLS) Protocol Version 1.2 (RFC5246) 
+        or a more recent version of TLS to authenticate the identity of the FHIR authorization server and to 
+        establish an encrypted, integrity-protected link for securing all exchanges between the client and the 
+        FHIR authorization server’s token endpoint. All exchanges described herein between the client and the 
+        FHIR server SHALL be secured using TLS V1.2 or a more recent version of TLS."
+      DESCRIPTION
+      id :smart_backend_services_token_tls_version
+
+      config(
+        inputs: { url: { name: :smart_token_url } },
+        options: {  minimum_allowed_version: OpenSSL::SSL::TLS1_2_VERSION }
+      )
+    end
+
+    test from: :smart_backend_services_invalid_grant_type
+
+    test from: :smart_backend_services_invalid_client_assertion
+
+    test from: :smart_backend_services_invalid_jwt
+
+    test from: :smart_backend_services_auth_request_success
+
+    test from: :smart_backend_services_auth_response_body
+  end
+end

data/lib/smart_app_launch/backend_services_authorization_request_builder.rb

@@ -0,0 +1,74 @@
+require 'json/jwt'
+require_relative 'client_assertion_builder'
+
+module SMARTAppLaunch
+  class BackendServicesAuthorizationRequestBuilder
+    def self.build(...)
+      new(...).authorization_request
+    end
+
+    attr_reader :encryption_method, :scope, :iss, :sub, :aud, :content_type, :grant_type, :client_assertion_type, :exp,
+                :jti, :kid
+
+    def initialize(
+      encryption_method:,
+      scope:,
+      iss:,
+      sub:,
+      aud:,
+      content_type: 'application/x-www-form-urlencoded',
+      grant_type: 'client_credentials',
+      client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+      exp: 5.minutes.from_now,
+      jti: SecureRandom.hex(32),
+      kid: nil
+    )
+      @encryption_method = encryption_method
+      @scope = scope
+      @iss = iss
+      @sub = sub
+      @aud = aud
+      @content_type = content_type
+      @grant_type = grant_type
+      @client_assertion_type = client_assertion_type
+      @exp = exp
+      @jti = jti
+      @kid = kid
+    end
+
+    def authorization_request_headers
+      {
+        content_type:,
+        accept: 'application/json'
+      }.compact
+    end
+
+    def authorization_request_query_values
+      {
+        'scope' => scope,
+        'grant_type' => grant_type,
+        'client_assertion_type' => client_assertion_type,
+        'client_assertion' => client_assertion.to_s
+      }.compact
+    end
+
+    def client_assertion
+      @client_assertion ||= ClientAssertionBuilder.build(
+          client_auth_encryption_method: encryption_method, 
+          iss: iss,
+          sub: sub,
+          aud: aud,
+          exp: exp.to_i,
+          jti: jti,
+          kid: kid
+          )
+    end
+
+    def authorization_request
+      uri = Addressable::URI.new
+      uri.query_values = authorization_request_query_values
+
+      { body: uri.query, headers: authorization_request_headers }
+    end
+  end
+end

data/lib/smart_app_launch/backend_services_authorization_request_success_test.rb

@@ -0,0 +1,40 @@
+require_relative 'backend_services_authorization_request_builder'
+require_relative 'backend_services_authorization_group'
+
+module SMARTAppLaunch 
+  class BackendServicesAuthorizationRequestSuccessTest < Inferno::Test 
+    id :smart_backend_services_auth_request_success
+    title 'Authorization request succeeds when supplied correct information'
+    description <<~DESCRIPTION
+      The [SMART App Launch 2.0.0 IG specification for Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#issue-access-token)
+      states "If the access token request is valid and authorized, the authorization server SHALL issue an access token in response."
+    DESCRIPTION
+
+    input :client_auth_encryption_method, 
+          :backend_services_requested_scope, 
+          :backend_services_client_id, 
+          :smart_token_url, 
+          :backend_services_jwks_kid
+
+    output :authentication_response
+
+    http_client :token_endpoint do
+      url :smart_token_url
+    end
+
+    run do
+      post_request_content = BackendServicesAuthorizationRequestBuilder.build(encryption_method: client_auth_encryption_method,
+                                                                scope: backend_services_requested_scope,
+                                                                iss: backend_services_client_id,
+                                                                sub: backend_services_client_id,
+                                                                aud: smart_token_url,
+                                                                kid: backend_services_jwks_kid)
+
+      authentication_response = post(**{ client: :token_endpoint }.merge(post_request_content))
+
+      assert_response_status([200, 201])
+
+      output authentication_response: authentication_response.response_body
+    end
+  end
+end

data/lib/smart_app_launch/backend_services_authorization_response_body_test.rb

@@ -0,0 +1,40 @@
+require_relative 'backend_services_authorization_request_builder'
+
+module SMARTAppLaunch 
+  class BackendServicesAuthorizationResponseBodyTest < Inferno::Test 
+    id :smart_backend_services_auth_response_body
+    title 'Authorization request response body contains required information encoded in JSON'
+    description <<~DESCRIPTION
+      The [SMART App Launch 2.0.0 IG specification for Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#issue-access-token)
+      states The access token response SHALL be a JSON object with the following properties:
+
+      | Token Property | Required? | Description |
+      | --- | --- | --- |
+      | `access_token` | required | The access token issued by the authorization server. |
+      | `token_type` | required | Fixed value: `bearer`. |
+      | `expires_in` | required | The lifetime in seconds of the access token. The recommended value is `300`, for a five-minute token lifetime. |
+      | `scope` | required | Scope of access authorized. Note that this can be different from the scopes requested by the app. |
+    DESCRIPTION
+
+    input :authentication_response
+    output :bearer_token
+
+    run do
+      skip_if authentication_response.blank?, 'No authentication response received.'
+
+      assert_valid_json(authentication_response)
+      response_body = JSON.parse(authentication_response)
+
+      access_token = response_body['access_token']
+      assert access_token.present?, 'Token response did not contain access_token as required'
+
+      output bearer_token: access_token
+
+      required_keys = ['token_type', 'expires_in', 'scope']
+
+      required_keys.each do |key|
+        assert response_body[key].present?, "Token response did not contain #{key} as required"
+      end
+    end
+  end
+end

data/lib/smart_app_launch/backend_services_invalid_client_assertion_test.rb

@@ -0,0 +1,44 @@
+require_relative 'backend_services_authorization_request_builder'
+
+module SMARTAppLaunch 
+  class BackendServicesInvalidClientAssertionTest < Inferno::Test 
+    id :smart_backend_services_invalid_client_assertion
+    title 'Authorization request fails when supplied invalid client_assertion_type'
+    description <<~DESCRIPTION
+      The [SMART App Launch 2.0.0 IG specification for Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#request-1)
+      defines the required fields for the authorization request, made via HTTP POST to authorization 
+      token endpoint.
+      This includes the `client_assertion_type` parameter, where the value must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
+
+      The [OAuth 2.0 Authorization Framework Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3.3) 
+      describes the proper response for an invalid request in the client credentials grant flow:
+
+      "If the request failed client authentication or is invalid, the authorization server returns an
+      error response as described in [Section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2)."
+    DESCRIPTION
+
+    input :client_auth_encryption_method, 
+          :backend_services_requested_scope, 
+          :backend_services_client_id, 
+          :smart_token_url, 
+          :backend_services_jwks_kid
+
+    http_client :token_endpoint do
+      url :smart_token_url
+    end
+
+    run do
+      post_request_content = BackendServicesAuthorizationRequestBuilder.build(encryption_method: client_auth_encryption_method,
+                                                                  scope: backend_services_requested_scope,
+                                                                  iss: backend_services_client_id,
+                                                                  sub: backend_services_client_id,
+                                                                  aud: smart_token_url,
+                                                                  client_assertion_type: 'not_an_assertion_type',
+                                                                  kid: backend_services_jwks_kid)
+
+      post(**{ client: :token_endpoint }.merge(post_request_content))
+
+      assert_response_status(400)
+    end 
+  end
+end

data/lib/smart_app_launch/backend_services_invalid_grant_type_test.rb

@@ -0,0 +1,44 @@
+require_relative 'backend_services_authorization_request_builder'
+
+module SMARTAppLaunch 
+  class BackendServicesInvalidGrantTypeTest < Inferno::Test 
+    id :smart_backend_services_invalid_grant_type
+    title 'Authorization request fails when client supplies invalid grant_type'
+    description <<~DESCRIPTION
+      The [SMART App Launch 2.0.0 IG section on Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#request-1)
+      defines the required fields for the authorization request, made via HTTP POST to authorization 
+      token endpoint.
+      This includes the `grant_type` parameter, where the value must be `client_credentials`.
+
+      The [OAuth 2.0 Authorization Framework Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3.3) 
+      describes the proper response for an invalid request in the client credentials grant flow:
+
+      "If the request failed client authentication or is invalid, the authorization server returns an
+      error response as described in [Section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2)."
+    DESCRIPTION
+
+    input :client_auth_encryption_method, 
+          :backend_services_requested_scope, 
+          :backend_services_client_id, 
+          :smart_token_url, 
+          :backend_services_jwks_kid
+
+    http_client :token_endpoint do
+      url :smart_token_url
+    end
+
+    run do
+      post_request_content = BackendServicesAuthorizationRequestBuilder.build(encryption_method: client_auth_encryption_method,
+                                                              scope: backend_services_requested_scope,
+                                                              iss: backend_services_client_id,
+                                                              sub: backend_services_client_id,
+                                                              aud: smart_token_url,
+                                                              grant_type: 'not_a_grant_type',
+                                                              kid: backend_services_jwks_kid)
+
+      post(**{ client: :token_endpoint }.merge(post_request_content))
+
+      assert_response_status(400)
+    end 
+  end
+end

data/lib/smart_app_launch/backend_services_invalid_jwt_test.rb

@@ -0,0 +1,55 @@
+require_relative 'backend_services_authorization_request_builder'
+
+module SMARTAppLaunch 
+  class BackendServicesInvalidJWTTest < Inferno::Test 
+    id :smart_backend_services_invalid_jwt
+    title 'Authorization request fails when client supplies invalid JWT token'
+    description <<~DESCRIPTION
+      The [SMART App Launch 2.0.0 IG section on Backend Services](https://hl7.org/fhir/smart-app-launch/STU2/backend-services.html#request-1)
+      defines the required fields for the authorization request, made via HTTP POST to authorization 
+      token endpoint.
+      This includes the `client_assertion` parameter, where the value must be
+      a valid JWT as specified in 
+      [Asymmetric (public key) Client Authentication](https://hl7.org/fhir/smart-app-launch/STU2/client-confidential-asymmetric.html#authenticating-to-the-token-endpoint)
+      The JWT SHALL include the following claims, and SHALL be signed with the client’s private key.
+
+      | JWT Claim | Required? | Description |
+      | --- | --- | --- |
+      | `iss` | required | Issuer of the JWT -- the client's `client_id`, as determined during registration with the FHIR authorization server (note that this is the same as the value for the sub claim) |
+      | `sub` | required | The service's `client_id`, as determined during registration with the FHIR authorization server (note that this is the same as the value for the `iss` claim) |
+      | `aud` | required | The FHIR authorization server's "token URL" (the same URL to which this authentication JWT will be posted) |
+      | `exp` | required | Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time SHALL be no more than five minutes in the future. |
+      | `jti` | required | A nonce string value that uniquely identifies this authentication JWT. |
+
+      The [OAuth 2.0 Authorization Framework Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3.3) 
+      describes the proper response for an invalid request in the client credentials grant flow:
+
+      "If the request failed client authentication or is invalid, the authorization server returns an
+      error response as described in [Section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2)."
+    DESCRIPTION
+
+    input :client_auth_encryption_method, 
+          :backend_services_requested_scope, 
+          :backend_services_client_id, 
+          :smart_token_url, 
+          :backend_services_jwks_kid
+
+    http_client :token_endpoint do
+      url :smart_token_url
+    end
+      
+    run do
+      post_request_content = BackendServicesAuthorizationRequestBuilder.build(encryption_method: client_auth_encryption_method,
+                                                                scope: backend_services_requested_scope,
+                                                                iss: backend_services_client_id,
+                                                                sub: backend_services_client_id,
+                                                                aud: smart_token_url,
+                                                                client_assertion_type: 'not_an_assertion_type',
+                                                                kid: backend_services_jwks_kid)
+
+      post(**{ client: :token_endpoint }.merge(post_request_content))
+
+      assert_response_status(400)
+    end 
+  end
+end

data/lib/smart_app_launch/client_assertion_builder.rb

@@ -16,7 +16,8 @@ module SMARTAppLaunch
                 :grant_type,
                 :iss,
                 :jti,
-                :sub
+                :sub,
+                :kid
 
     def initialize(
       client_auth_encryption_method:,
@@ -24,7 +25,8 @@ module SMARTAppLaunch
       sub:,
       aud:,
       exp: 5.minutes.from_now.to_i,
-      jti: SecureRandom.hex(32)
+      jti: SecureRandom.hex(32),
+      kid: nil
     )
       @client_auth_encryption_method = client_auth_encryption_method
       @iss = iss
@@ -35,29 +37,35 @@ module SMARTAppLaunch
       @client_assertion_type = client_assertion_type
       @exp = exp
       @jti = jti
+      @kid = kid
     end
 
     def private_key
-      @private_key ||=
-        JWKS.jwks
-          .find { |key| key[:key_ops]&.include?('sign') && key[:alg] == client_auth_encryption_method }
+      @private_key ||= JWKS.jwks
+        .select { |key| key[:key_ops]&.include?('sign') }
+        .select { |key| key[:alg] == client_auth_encryption_method }
+        .find { |key| !kid || key[:kid] == kid }
     end
 
     def jwt_payload
       { iss:, sub:, aud:, exp:, jti: }.compact
     end
 
-    def kid
-      private_key.kid
+    def signing_key
+      private_key()
+      if @private_key.nil?
+        raise Inferno::Exceptions::AssertionException, "No signing key found for inputs: encryption method = '#{client_auth_encryption_method}' and kid = '#{kid}'"
+      end
+      return @private_key.signing_key
     end
 
-    def signing_key
-      private_key.signing_key
+    def key_id
+      @private_key['kid']
     end
 
     def client_assertion
       @client_assertion ||=
-        JWT.encode jwt_payload, signing_key, client_auth_encryption_method, { alg: client_auth_encryption_method, kid:, typ: 'JWT' }
+        JWT.encode jwt_payload, signing_key, client_auth_encryption_method, { alg: client_auth_encryption_method, kid: key_id, typ: 'JWT' }
     end
   end
 end

data/lib/smart_app_launch/smart_stu2_suite.rb

@@ -8,6 +8,7 @@ require_relative 'ehr_launch_group_stu2'
 require_relative 'openid_connect_group'
 require_relative 'token_introspection_group'
 require_relative 'token_refresh_group'
+require_relative 'backend_services_authorization_group'
 
 module SMARTAppLaunch
   class SMARTSTU2Suite < Inferno::TestSuite
@@ -220,6 +221,23 @@ module SMARTAppLaunch
             }
     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/.well-known/jwks.json`
+      INSTRUCTIONS
+
+      run_as_group
+
+      group from: :smart_discovery_stu2
+      group from: :backend_services_authorization
+    end
+
     group from: :smart_token_introspection
 
   end

data/lib/smart_app_launch/token_exchange_stu2_test.rb

@@ -14,21 +14,21 @@ module SMARTAppLaunch
     id :smart_token_exchange_stu2
 
     input :client_auth_encryption_method,
-          title: 'Encryption Method (Confidential Asymmetric Client Auth Only)',
-          type: 'radio',
-          default: 'ES384',
-          options: {
-            list_options: [
-              {
-                label: 'ES384',
-                value: 'ES384'
-              },
-              {
-                label: 'RS384',
-                value: 'RS384'
-              }
-            ]
+      title: 'Encryption Method (Confidential Asymmetric Client Auth Only)',
+      type: 'radio',
+      default: 'ES384',
+      options: {
+        list_options: [
+          {
+            label: 'ES384',
+            value: 'ES384'
+          },
+          {
+            label: 'RS384',
+            value: 'RS384'
           }
+        ]
+      }
 
     input :client_auth_type,
           title: 'Client Authentication Method',

data/lib/smart_app_launch/version.rb

@@ -1,3 +1,3 @@
 module SMARTAppLaunch
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.4.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smart_app_launch_test_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Stephen MacVicar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-08 00:00:00.000000000 Z
+date: 2024-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inferno_core
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.2
+- !ruby/object:Gem::Dependency
+  name: json-jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.3
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -134,6 +148,13 @@ files:
 - lib/smart_app_launch/app_launch_test.rb
 - lib/smart_app_launch/app_redirect_test.rb
 - lib/smart_app_launch/app_redirect_test_stu2.rb
+- lib/smart_app_launch/backend_services_authorization_group.rb
+- lib/smart_app_launch/backend_services_authorization_request_builder.rb
+- lib/smart_app_launch/backend_services_authorization_request_success_test.rb
+- lib/smart_app_launch/backend_services_authorization_response_body_test.rb
+- lib/smart_app_launch/backend_services_invalid_client_assertion_test.rb
+- lib/smart_app_launch/backend_services_invalid_grant_type_test.rb
+- lib/smart_app_launch/backend_services_invalid_jwt_test.rb
 - lib/smart_app_launch/client_assertion_builder.rb
 - lib/smart_app_launch/code_received_test.rb
 - lib/smart_app_launch/discovery_stu1_group.rb