Class: Safire::Protocols::Smart Private

Inherits:
Object
  • Object
show all
Includes:
Behaviours, 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
].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

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.



37
38
39
40
41
42
43
 
# File 'lib/safire/protocols/smart.rb', line 37

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
  @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. 



34
35
36
 
# File 'lib/safire/protocols/smart.rb', line 34

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. 



45
46
47
 
# File 'lib/safire/protocols/smart.rb', line 45

def authorization_endpoint
  @authorization_endpoint ||= server_metadata.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



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/safire/protocols/smart.rb', line 94

def authorization_url(launch: nil, custom_scopes: nil, method: :get)
  method = method.to_sym
  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:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/safire/protocols/smart.rb', line 159

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:



244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/safire/protocols/smart.rb', line 244

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:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/safire/protocols/smart.rb', line 129

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 hl7.org/fhir/smart-app-launch/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; uses configured scopes if nil, falling back to [“system/*.rs”] when neither is provided

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

    private key for JWT assertion; uses 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:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/safire/protocols/smart.rb', line 197

def request_backend_token(scopes: nil, private_key: self.private_key, kid: self.kid)
  scopes ||= self.scopes.presence || ['system/*.rs']
  validate_client_id!

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

  response = @http_client.post(
    token_endpoint,
    body: backend_services_token_params(scopes:, private_key:, kid:),
    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:



67
68
69
70
71
72
73
74
75
76
 
# File 'lib/safire/protocols/smart.rb', line 67

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. 



49
50
51
 
# File 'lib/safire/protocols/smart.rb', line 49

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



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/safire/protocols/smart.rb', line 272

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