Class: Safire::ClientConfig

Inherits:
Entity
  • Object
show all
Defined in:
lib/safire/client_config.rb

Overview

Client configuration entity providing necessary attributes to perform different auth flows such as SMART on FHIR puclic, confidential symmetric, confidential asymmetric clients, and backend services. The ClientConfig instance is passed to Safire::Client upon initialization.

=> Optional, will be retrieved from the well-known smart-configuration if not provided => Optional, will be retrieved from the well-known smart-configuration if not provided client = Safire::Client.new(config)

client = Safire::Client.new(config)

Examples:

Initializing a ClientConfig

config = Safire::ClientConfig.new(
  base_url: 'https://fhir.example.com',
  client_id: 'my_client_id',
  redirect_uri: 'https://myapp.example.com/callback',
  scopes: ['openid', 'profile', 'patient/*.read']
)

Initializing a ClientConfig using the Builder

config = Safire::ClientConfig.builder
  .base_url('https://fhir.example.com')
  .client_id('my_client_id')
  .redirect_uri('https://myapp.example.com/callback')
  .scopes(['openid', 'profile', 'patient/*.read'])
  .build

See Also:

Constant Summary collapse

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Entity

#to_hash

Constructor Details

#initialize(config) ⇒ ClientConfig

Returns a new instance of ClientConfig.



66
67
68
69
70
71
 
# File 'lib/safire/client_config.rb', line 66

def initialize(config)
  super(config, ATTRIBUTES)

  @issuer ||= base_url
  validate!
end

Instance Attribute Details

#authorization_endpoint ⇒ String (readonly)

Returns URL of the server’s OAuth2 Authorization Endpoint.

Returns:

  • (String) —

    URL of the server’s OAuth2 Authorization Endpoint.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#base_url ⇒ String (readonly)

Returns the base URL of the FHIR service.

Returns:

  • (String) —

    the base URL of the FHIR service



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#client_id ⇒ String (readonly)

Returns the client identifier issued to the app by the authorization server.

Returns:

  • (String) —

    the client identifier issued to the app by the authorization server



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#issuer ⇒ String (readonly)

Returns the URL of the FHIR service from which the app wishes to retrieve FHIR data. Optionally provided. Will default to base_url if not provided.

Returns:

  • (String) —

    the URL of the FHIR service from which the app wishes to retrieve FHIR data. Optionally provided. Will default to base_url if not provided.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#jwks_uri ⇒ String? (readonly)

Returns URL to the client’s JWKS containing the public key. Optional, included as jku header in JWT assertions when provided.

Returns:

  • (String, nil) —

    URL to the client’s JWKS containing the public key. Optional, included as jku header in JWT assertions when provided.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#jwt_algorithm ⇒ String? (readonly)

Returns the JWT signing algorithm (RS384 or ES384). Optional, auto-detected from key type if not provided.

Returns:

  • (String, nil) —

    the JWT signing algorithm (RS384 or ES384). Optional, auto-detected from key type if not provided.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#kid ⇒ String? (readonly)

Returns the key ID matching the public key registered with the authorization server. Required for confidential asymmetric authentication.

Returns:

  • (String, nil) —

    the key ID matching the public key registered with the authorization server. Required for confidential asymmetric authentication.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#private_key ⇒ OpenSSL::PKey::RSA, ... (readonly)

Returns the private key for signing JWT assertions in confidential asymmetric auth. Can be an OpenSSL key object or PEM string.

Returns:

  • (OpenSSL::PKey::RSA, OpenSSL::PKey::EC, String, nil) —

    the private key for signing JWT assertions in confidential asymmetric auth. Can be an OpenSSL key object or PEM string.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#redirect_uri ⇒ String (readonly)

Returns the redirect URI registered by the app with the authorization server.

Returns:

  • (String) —

    the redirect URI registered by the app with the authorization server



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#scopes ⇒ Array<String> (readonly)

Returns list of OAuth2 scopes describing the app’s desired access. Optionally provided.

Returns:

  • (Array<String>) —

    list of OAuth2 scopes describing the app’s desired access. Optionally provided.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

#token_endpoint ⇒ String (readonly)

Returns URL of the server’s OAuth2 Token Endpoint.

Returns:

  • (String) —

    URL of the server’s OAuth2 Token Endpoint.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/safire/client_config.rb', line 57

class ClientConfig < Entity
  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key kid jwt_algorithm jwks_uri
  ].freeze

  attr_reader(*ATTRIBUTES)

  def initialize(config)
    super(config, ATTRIBUTES)

    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  SENSITIVE_ATTRIBUTES = %i[client_secret private_key].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      value = send(attr)
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def classify_uri(value)
    uri = Addressable::URI.parse(value)
    return :invalid unless uri.scheme && uri.host

    :non_https if uri.scheme != 'https' && !localhost_host?(uri.host)
  rescue Addressable::URI::InvalidURIError
    :invalid
  end

  # Returns true when the host is a local loopback address.
  # HTTP is permitted for localhost to support development environments.
  def localhost_host?(host)
    %w[localhost 127.0.0.1].include?(host)
  end

  def validate!
    required_attrs = %i[base_url client_id]
    nil_vars = required_attrs.select { |attr| send(attr).nil? }

    if nil_vars.empty?
      validate_uris!
      return
    end

    raise Errors::ConfigurationError.new(missing_attributes: nil_vars)
  end
end

Class Method Details

.builder ⇒ Object 



74
75
76
 
# File 'lib/safire/client_config.rb', line 74

def builder
  ClientConfigBuilder.new
end

Instance Method Details

#inspect ⇒ 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. 



85
86
87
88
89
90
91
92
93
94
 
# File 'lib/safire/client_config.rb', line 85

def inspect
  attrs = ATTRIBUTES.map do |attr|
    value = send(attr)
    next if value.nil?

    masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
    "#{attr}: #{masked}"
  end.compact.join(', ')
  "#<#{self.class} #{attrs}>"
end