Class: Safire::Protocols::Smart Private

Inherits:
Object
  • Object
show all
Includes:
Behaviours, OAuthResponseHandling, URIValidation
Defined in:
lib/safire/protocols/smart.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Note:

For internal use by Client only.

SMART OAuth2 implementation for app launch (authorization code, token exchange, refresh) and backend services (client credentials) flows.

This is an internal class used exclusively by Client. Do not instantiate it directly — use Client instead.

Accepts a ClientConfig and a client_type symbol. Reads all configuration attributes directly from the ClientConfig object. Discovery of authorization and token endpoints from the FHIR server's /.well-known/smart-configuration metadata is performed automatically when those endpoints are not present in the config.

Constant Summary collapse

ATTRIBUTES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

%i[
  base_url client_id client_secret redirect_uri scopes issuer
  authorization_endpoint token_endpoint
  private_key kid jwt_algorithm jwks_uri allow_insecure_localhost
].freeze
OPTIONAL_ATTRIBUTES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Attributes that are not required during initialization; validated per-flow when needed

%i[
  client_id redirect_uri authorization_endpoint scopes client_secret private_key kid jwt_algorithm jwks_uri
].freeze
WELL_KNOWN_PATH =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

'/.well-known/smart-configuration'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Behaviours

#cancel_registration

Constructor Details

#initialize(config, client_type: :public) ⇒ Smart

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Smart.



44
45
46
47
48
49
50
 
# File 'lib/safire/protocols/smart.rb', line 44

def initialize(config, client_type: :public)
  ATTRIBUTES.each { |attr| instance_variable_set("@#{attr}", config.public_send(attr)) }

  @client_type = client_type.to_sym
  @http_client = Safire::HTTPClient.new(allow_insecure_localhost:)
  @issuer ||= base_url
end

Instance Attribute Details

#client_type ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



41
42
43
 
# File 'lib/safire/protocols/smart.rb', line 41

def client_type
  @client_type
end

Instance Method Details

#authorization_endpoint ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



52
53
54
 
# File 'lib/safire/protocols/smart.rb', line 52

def authorization_endpoint
  @authorization_endpoint ||= discovered_authorization_endpoint
end

#authorization_url(launch: nil, custom_scopes: nil, method: :get) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds the authorization request data for the authorization code flow.

Parameters:

  • launch (String, nil) (defaults to: nil) —

    optional launch parameter

  • custom_scopes (Array<String>, nil) (defaults to: nil) —

    optional custom scopes to override the configured ones

  • method (Symbol, String) (defaults to: :get) —

    authorization request method; :get (default) or :post. Both symbol and string forms are accepted (e.g. method: :post or method: 'post').

    • :get — builds a redirect URL with all parameters in the query string (standard flow)
    • :post — returns the endpoint and parameters separately for POST-based authorization (SMART App Launch 2.2.0 authorize-post capability)

Returns:

  • (Hash) —

    containing:

    • :auth_url [String] authorization URL (GET) or bare endpoint URL (POST)
    • :state [String] state parameter for CSRF protection; store and verify on callback
    • :code_verifier [String] PKCE code verifier for the token exchange
    • :params [Hash] (POST only) authorization parameters to submit as the request body

Raises:

  • (Errors::ConfigurationError) —

    if method is invalid, +client_id+/scopes are missing, or redirect_uri / authorization_endpoint are not configured or resolvable via discovery

  • (Errors::DiscoveryError) —

    if a discovered authorization_endpoint is not a usable HTTPS URI; HTTP loopback endpoints require the explicit development policy



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/safire/protocols/smart.rb', line 103

def authorization_url(launch: nil, custom_scopes: nil, method: :get)
  method = method.to_sym if method.is_a?(String)
  custom_scopes ||= scopes
  validate_authorization_method(method)
  validate_client_id!
  validate_presence_of_scopes(custom_scopes)
  validate_app_launch_attrs!

  Safire.logger.info("Generating authorization URL for SMART #{client_type} (method: #{method})...")

  code_verifier = PKCE.generate_code_verifier
  params = authorization_params(launch:, custom_scopes:, code_verifier:)

  build_authorization_response(method, params, code_verifier)
end

#refresh_token(refresh_token:, scopes: nil, client_secret: self.client_secret, private_key: self.private_key, kid: self.kid) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Exchanges a refresh token for a new access token.

Parameters:

  • refresh_token (String) —

    the refresh token issued by the authorization server (required)

  • scopes (Array<String>, nil) (defaults to: nil) —

    optional reduced scope list; if omitted, the same scopes as the original token are requested

  • client_secret (String, nil) (defaults to: self.client_secret) —

    optional; used for confidential symmetric clients when not already configured

  • private_key (OpenSSL::PKey, String, nil) (defaults to: self.private_key) —

    optional; private key for asymmetric auth (overrides configured)

  • kid (String, nil) (defaults to: self.kid) —

    optional; key ID for asymmetric auth (overrides configured)

Returns:

  • (Hash) —

    token response parsed from the authorization server. See #request_access_token for token response format.

Raises:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/safire/protocols/smart.rb', line 170

def refresh_token(refresh_token:, scopes: nil, client_secret: self.client_secret,
                  private_key: self.private_key, kid: self.kid)
  validate_client_id!
  Safire.logger.info('Refreshing access token...')

  response = @http_client.post(
    token_endpoint,
    body: refresh_token_params(refresh_token:, scopes:, private_key:, kid:),
    headers: oauth2_headers(client_secret)
  )

  parse_token_response(response.body)
rescue Faraday::Error => e
  raise token_error_from(e)
end

#register_client(metadata, registration_endpoint: nil, authorization: nil) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Dynamically registers this client with the authorization server (RFC 7591).

Sends a POST request containing the client metadata as JSON to the registration endpoint. The endpoint is taken from the registration_endpoint: argument when provided; otherwise it is resolved from SMART discovery.

On success, returns the raw registration response as a Hash containing at minimum a client_id assigned by the server. Store these credentials durably and use them to build a new Client for subsequent authorization flows.

Parameters:

  • metadata (Hash) —

    client metadata per RFC 7591 §2. Keys may be symbols or strings. Common fields: :client_name, :redirect_uris, :grant_types, :token_endpoint_auth_method, :jwks_uri, :scope.

  • registration_endpoint (String, nil) (defaults to: nil) —

    URL of the registration endpoint. Falls back to the registration_endpoint field in SMART discovery when nil. Pass this explicitly to skip discovery.

  • authorization (String, nil) (defaults to: nil) —

    full value for the HTTP Authorization header; required by some servers for initial access token protection (RFC 7591 §3.1), e.g. "Bearer <initial-access-token>".

Returns:

  • (Hash) —

    registration response from the server, including:

    • "client_id" [String] assigned client identifier (required)
    • "client_secret" [String] client secret, if issued (confidential clients)
    • all echoed metadata fields the server chooses to return

Raises:



263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/safire/protocols/smart.rb', line 263

def register_client(metadata, registration_endpoint: nil, authorization: nil)
  endpoint = registration_endpoint.presence || discovered_registration_endpoint
  validate_registration_endpoint_https!(endpoint)
  headers = { content_type: 'application/json' }
  headers['Authorization'] = authorization if authorization.present?

  Safire.logger.info('Registering client via Dynamic Client Registration (RFC 7591)...')

  response = @http_client.post(endpoint, body: metadata.to_json, headers:)
  parse_registration_response(response.body)
rescue Faraday::Error => e
  raise registration_error_from(e)
end

#request_access_token(code:, code_verifier:, client_secret: self.client_secret, private_key: self.private_key, kid: self.kid) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Exchanges the authorization code for an access token.

Parameters:

  • code (String) —

    authorization code from the authorization server

  • code_verifier (String) —

    PKCE code verifier from the authorization step

  • client_secret (String, nil) (defaults to: self.client_secret) —

    optional; used for confidential symmetric clients when not already configured

  • private_key (OpenSSL::PKey, String, nil) (defaults to: self.private_key) —

    optional; private key for asymmetric auth (overrides configured)

  • kid (String, nil) (defaults to: self.kid) —

    optional; key ID for asymmetric auth (overrides configured)

Returns:

  • (Hash) —

    token response parsed from the authorization server, including:

    • "access_token" [String] new access token issued by the authorization server (required)
    • "token_type" [String] token type, exactly "Bearer" (required, case-sensitive per SMART spec)
    • "expires_in" [Integer] lifetime of the access token in seconds (RECOMMENDED)
    • "scope" [String] authorized scopes for this token (required)
    • "refresh_token" [String] refresh token, if issued (optional)
    • "authorization_details" [Hash] additional authorization details, if provided (optional)
    • Context parameters such as "patient" or "encounter" MAY be present, depending on server behavior.

Raises:



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/safire/protocols/smart.rb', line 139

def request_access_token(code:, code_verifier:, client_secret: self.client_secret,
                         private_key: self.private_key, kid: self.kid)
  validate_client_id!
  Safire.logger.info('Requesting access token using authorization code...')

  response = @http_client.post(
    token_endpoint,
    body: access_token_params(code, code_verifier, private_key:, kid:),
    headers: oauth2_headers(client_secret)
  )

  parse_token_response(response.body)
rescue Faraday::Error => e
  raise token_error_from(e)
end

#request_backend_token(scopes: nil, private_key: self.private_key, kid: self.kid) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Requests an access token using the client credentials grant (SMART Backend Services).

Implements the SMART Backend Services Authorization flow per https://hl7.org/fhir/smart-app-launch/STU2.2/backend-services.html

No user interaction, redirect, or PKCE is involved. The client authenticates exclusively via a signed JWT assertion (RS384 or ES384).

Parameters:

  • scopes (Array<String>, nil) (defaults to: nil) —

    scope override; blank overrides fall back to configured scopes. For v0.4.x compatibility, a request without usable per-call or configured scopes emits a deprecation warning and falls back to ["system/*.rs"]. This fallback will be removed in v0.6.0, when missing scopes will raise Errors::ConfigurationError. Explicit non-+system/+ scopes are submitted unchanged because SMART permits them when the caller establishes the required context out of band.

  • private_key (OpenSSL::PKey::RSA, OpenSSL::PKey::EC, String) (defaults to: self.private_key) —

    private key or PEM string for the JWT assertion; uses the configured key if not provided. Required — must be present either in configuration or passed here.

  • kid (String) (defaults to: self.kid) —

    key ID for JWT assertion header; uses configured kid if not provided. Required — must be present either in configuration or passed here.

Returns:

  • (Hash) —

    token response from the authorization server, including:

    • "access_token" [String] access token (required)
    • "token_type" [String] token type, value "Bearer" (required)
    • "expires_in" [Integer] lifetime of the access token in seconds (required per Backend Services spec)
    • "scope" [String] authorized scopes (required)

Raises:



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/safire/protocols/smart.rb', line 214

def request_backend_token(scopes: nil, private_key: self.private_key, kid: self.kid)
  validate_client_id!
  assertion_params = jwt_assertion_params(private_key:, kid:)
  scopes = resolve_backend_scopes(scopes)

  Safire.logger.info('Requesting backend services access token (client_credentials grant)...')

  response = @http_client.post(
    token_endpoint,
    body: backend_services_token_params(scopes:, assertion_params:),
    headers: { content_type: 'application/x-www-form-urlencoded' }
  )

  parse_token_response(response.body)
rescue Faraday::Error => e
  raise token_error_from(e)
end

#server_metadata ⇒ Safire::Protocols::SmartMetadata

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Retrieves and parses SMART configuration metadata from the FHIR server.

This method sends a GET request to the server's /.well-known/smart-configuration endpoint, validates the response format, and builds a Safire::Protocols::SmartMetadata object containing the authorization and token endpoints, among other SMART metadata fields.

The result is cached after the first successful discovery and reused on subsequent calls within the same instance.

Returns:

Raises:



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/safire/protocols/smart.rb', line 74

def server_metadata
  return @server_metadata if @server_metadata

  response = @http_client.get(well_known_endpoint)
  @server_metadata = SmartMetadata.new(parse_discovery_body(response.body))
rescue Faraday::Error => e
  status = e.response&.dig(:status)
  Safire.logger.error("SMART discovery failed for `#{well_known_endpoint}`: HTTP #{status}")
  raise Errors::DiscoveryError.new(endpoint: well_known_endpoint, status: status)
end

#token_endpoint ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



56
57
58
 
# File 'lib/safire/protocols/smart.rb', line 56

def token_endpoint
  @token_endpoint ||= discovered_token_endpoint
end

#token_response_valid?(response, flow: :app_launch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Validates a token response for SMART compliance.

Checks all required token response fields based on the authorization flow:

  • access_token must be present (all flows, SHALL)
  • token_type must be present and "Bearer" or "bearer" (all flows, SHALL)
  • scope must be present (all flows, SHALL)
  • expires_in must be present when flow: :backend_services (required per Backend Services spec)

Logs a warning via Safire.logger for each violation found and returns false. Never raises an exception.

Parameters:

  • response (Hash) —

    the token response returned by the server

  • flow (Symbol) (defaults to: :app_launch) —

    the authorization flow; :app_launch (default) or :backend_services

Returns:

  • (Boolean) —

    true if the response is compliant, false otherwise



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/safire/protocols/smart.rb', line 291

def token_response_valid?(response, flow: :app_launch)
  unless response.is_a?(Hash)
    Safire.logger.warn('SMART token response non-compliance: response is not a JSON object')
    return false
  end

  valid = true

  required_fields = %w[access_token scope]
  required_fields << 'expires_in' if flow == :backend_services

  required_fields.each do |field|
    next if response[field].present?

    Safire.logger.warn(
      "SMART token response non-compliance: required field '#{field}' is missing"
    )
    valid = false
  end

  token_type_valid?(response, flow:) && valid
end