Module: OmniauthOpenidFederation::Instrumentation

Defined in:
lib/omniauth_openid_federation/instrumentation.rb

Constant Summary collapse

EVENT_CSRF_DETECTED =

Security event types

"csrf_detected"
EVENT_SIGNATURE_VERIFICATION_FAILED = 
"signature_verification_failed"
EVENT_DECRYPTION_FAILED = 
"decryption_failed"
EVENT_TOKEN_VALIDATION_FAILED = 
"token_validation_failed"
EVENT_KEY_ROTATION_DETECTED = 
"key_rotation_detected"
EVENT_KID_NOT_FOUND = 
"kid_not_found"
EVENT_ENTITY_STATEMENT_VALIDATION_FAILED = 
"entity_statement_validation_failed"
EVENT_FINGERPRINT_MISMATCH = 
"fingerprint_mismatch"
EVENT_TRUST_CHAIN_VALIDATION_FAILED = 
"trust_chain_validation_failed"
EVENT_ENDPOINT_MISMATCH = 
"endpoint_mismatch"
EVENT_UNEXPECTED_AUTHENTICATION_BREAK = 
"unexpected_authentication_break"
EVENT_STATE_MISMATCH = 
"state_mismatch"
EVENT_MISSING_REQUIRED_CLAIMS = 
"missing_required_claims"
EVENT_AUDIENCE_MISMATCH = 
"audience_mismatch"
EVENT_ISSUER_MISMATCH = 
"issuer_mismatch"
EVENT_EXPIRED_TOKEN = 
"expired_token"
EVENT_INVALID_NONCE = 
"invalid_nonce"
EVENT_AUTHENTICITY_ERROR = 
"authenticity_error"

Class Method Summary collapse

Class Method Details

.notify(event, data: {}, severity: :warning) ⇒ void

This method returns an undefined value.

Notify about a security event

Parameters:

  • event (String) —

    Event type (use constants from this module)

  • data (Hash) (defaults to: {}) —

    Event data (will be sanitized to remove sensitive information)

  • severity (Symbol) (defaults to: :warning) —

    Event severity (:info, :warning, :error)



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
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 58

def notify(event, data: {}, severity: :warning)
  config = Configuration.config
  return unless config.instrumentation

  # Sanitize data to remove sensitive information
  sanitized_data = sanitize_data(data)

  # Build notification payload
  payload = {
    event: event,
    severity: severity,
    timestamp: Time.now.utc.iso8601,
    data: sanitized_data
  }

  # Call the configured instrumentation callback
  begin
    if config.instrumentation.respond_to?(:call)
      config.instrumentation.call(event, payload)
    elsif config.instrumentation.respond_to?(:notify)
      config.instrumentation.notify(event, payload)
    else
      # Assume it's a logger-like object
      log_message = "[OpenID Federation Security] #{event}: #{sanitized_data.inspect}"
      case severity
      when :error
        config.instrumentation.error(log_message)
      when :warning
        config.instrumentation.warn(log_message)
      else
        config.instrumentation.info(log_message)
      end
    end
  rescue => e
    # Don't let instrumentation failures break the authentication flow
    Logger.warn("[Instrumentation] Failed to notify about #{event}: #{e.message}")
  end
end

.notify_audience_mismatch(data = {}) ⇒ void

This method returns an undefined value.

Notify about audience mismatch

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (expected_audience, actual_audience, token_type)



296
297
298
299
300
301
302
303
304
305
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 296

def notify_audience_mismatch(data = {})
  notify(
    EVENT_AUDIENCE_MISMATCH,
    data: {
      reason: "Token audience mismatch - possible MITM attack or configuration issue",
      **data
    },
    severity: :error
  )
end

.notify_authenticity_error(data = {}) ⇒ void

This method returns an undefined value.

Notify about authenticity token error (OmniAuth CSRF protection)

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (error_type, error_message, phase, request_info)



356
357
358
359
360
361
362
363
364
365
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 356

def notify_authenticity_error(data = {})
  notify(
    EVENT_AUTHENTICITY_ERROR,
    data: {
      reason: "OmniAuth authenticity token validation failed - CSRF protection blocked request",
      **data
    },
    severity: :error
  )
end

.notify_csrf_detected(data = {}) ⇒ void

This method returns an undefined value.

Notify about CSRF detection

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (state_param, state_session, request_info)



101
102
103
104
105
106
107
108
109
110
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 101

def notify_csrf_detected(data = {})
  notify(
    EVENT_CSRF_DETECTED,
    data: {
      reason: "State parameter mismatch - possible CSRF attack",
      **data
    },
    severity: :error
  )
end

.notify_decryption_failed(data = {}) ⇒ void

This method returns an undefined value.

Notify about decryption failure

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (token_type, error_message)



131
132
133
134
135
136
137
138
139
140
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 131

def notify_decryption_failed(data = {})
  notify(
    EVENT_DECRYPTION_FAILED,
    data: {
      reason: "Token decryption failed - possible MITM attack or key mismatch",
      **data
    },
    severity: :error
  )
end

.notify_endpoint_mismatch(data = {}) ⇒ void

This method returns an undefined value.

Notify about endpoint mismatch

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (endpoint_type, expected, actual, source)



236
237
238
239
240
241
242
243
244
245
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 236

def notify_endpoint_mismatch(data = {})
  notify(
    EVENT_ENDPOINT_MISMATCH,
    data: {
      reason: "Endpoint mismatch detected - possible MITM attack or configuration issue",
      **data
    },
    severity: :warning
  )
end

.notify_entity_statement_validation_failed(data = {}) ⇒ void

This method returns an undefined value.

Notify about entity statement validation failure

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (entity_id, validation_step, error_message)



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 191

def notify_entity_statement_validation_failed(data = {})
  notify(
    EVENT_ENTITY_STATEMENT_VALIDATION_FAILED,
    data: {
      reason: "Entity statement validation failed - possible tampering or MITM attack",
      **data
    },
    severity: :error
  )
end

.notify_expired_token(data = {}) ⇒ void

This method returns an undefined value.

Notify about expired token

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (exp, current_time, token_type)



326
327
328
329
330
331
332
333
334
335
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 326

def notify_expired_token(data = {})
  notify(
    EVENT_EXPIRED_TOKEN,
    data: {
      reason: "Token expired - possible clock skew or replay attack",
      **data
    },
    severity: :warning
  )
end

.notify_fingerprint_mismatch(data = {}) ⇒ void

This method returns an undefined value.

Notify about fingerprint mismatch

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (expected_fingerprint, calculated_fingerprint, entity_statement_url)



206
207
208
209
210
211
212
213
214
215
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 206

def notify_fingerprint_mismatch(data = {})
  notify(
    EVENT_FINGERPRINT_MISMATCH,
    data: {
      reason: "Entity statement fingerprint mismatch - possible MITM attack or tampering",
      **data
    },
    severity: :error
  )
end

.notify_invalid_nonce(data = {}) ⇒ void

This method returns an undefined value.

Notify about invalid nonce

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (expected_nonce, actual_nonce)



341
342
343
344
345
346
347
348
349
350
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 341

def notify_invalid_nonce(data = {})
  notify(
    EVENT_INVALID_NONCE,
    data: {
      reason: "Nonce mismatch - possible replay attack",
      **data
    },
    severity: :error
  )
end

.notify_issuer_mismatch(data = {}) ⇒ void

This method returns an undefined value.

Notify about issuer mismatch

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (expected_issuer, actual_issuer, token_type)



311
312
313
314
315
316
317
318
319
320
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 311

def notify_issuer_mismatch(data = {})
  notify(
    EVENT_ISSUER_MISMATCH,
    data: {
      reason: "Token issuer mismatch - possible MITM attack or configuration issue",
      **data
    },
    severity: :error
  )
end

.notify_key_rotation_detected(data = {}) ⇒ void

This method returns an undefined value.

Notify about key rotation detection

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (jwks_uri, kid, available_kids)



161
162
163
164
165
166
167
168
169
170
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 161

def notify_key_rotation_detected(data = {})
  notify(
    EVENT_KEY_ROTATION_DETECTED,
    data: {
      reason: "Key rotation detected - kid not found in current JWKS",
      **data
    },
    severity: :warning
  )
end

.notify_kid_not_found(data = {}) ⇒ void

This method returns an undefined value.

Notify about kid not found

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (kid, jwks_uri, available_kids)



176
177
178
179
180
181
182
183
184
185
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 176

def notify_kid_not_found(data = {})
  notify(
    EVENT_KID_NOT_FOUND,
    data: {
      reason: "Key ID not found in JWKS - possible key rotation or MITM attack",
      **data
    },
    severity: :error
  )
end

.notify_missing_required_claims(data = {}) ⇒ void

This method returns an undefined value.

Notify about missing required claims

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (missing_claims, available_claims, token_type)



281
282
283
284
285
286
287
288
289
290
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 281

def notify_missing_required_claims(data = {})
  notify(
    EVENT_MISSING_REQUIRED_CLAIMS,
    data: {
      reason: "Token missing required claims - possible tampering or provider issue",
      **data
    },
    severity: :error
  )
end

.notify_signature_verification_failed(data = {}) ⇒ void

This method returns an undefined value.

Notify about signature verification failure

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (token_type, kid, jwks_uri, error_message)



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 116

def notify_signature_verification_failed(data = {})
  notify(
    EVENT_SIGNATURE_VERIFICATION_FAILED,
    data: {
      reason: "JWT signature verification failed - possible MITM attack or key rotation",
      **data
    },
    severity: :error
  )
end

.notify_state_mismatch(data = {}) ⇒ void

This method returns an undefined value.

Notify about state mismatch

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (state_param, state_session)



266
267
268
269
270
271
272
273
274
275
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 266

def notify_state_mismatch(data = {})
  notify(
    EVENT_STATE_MISMATCH,
    data: {
      reason: "State parameter mismatch - possible CSRF attack or session issue",
      **data
    },
    severity: :error
  )
end

.notify_token_validation_failed(data = {}) ⇒ void

This method returns an undefined value.

Notify about token validation failure

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (validation_type, missing_claims, error_message)



146
147
148
149
150
151
152
153
154
155
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 146

def notify_token_validation_failed(data = {})
  notify(
    EVENT_TOKEN_VALIDATION_FAILED,
    data: {
      reason: "Token validation failed - possible tampering or configuration mismatch",
      **data
    },
    severity: :error
  )
end

.notify_trust_chain_validation_failed(data = {}) ⇒ void

This method returns an undefined value.

Notify about trust chain validation failure

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (entity_id, trust_anchor, validation_step, error_message)



221
222
223
224
225
226
227
228
229
230
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 221

def notify_trust_chain_validation_failed(data = {})
  notify(
    EVENT_TRUST_CHAIN_VALIDATION_FAILED,
    data: {
      reason: "Trust chain validation failed - possible MITM attack or configuration issue",
      **data
    },
    severity: :error
  )
end

.notify_unexpected_authentication_break(data = {}) ⇒ void

This method returns an undefined value.

Notify about unexpected authentication break

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional context (stage, error_message, error_class)



251
252
253
254
255
256
257
258
259
260
 
# File 'lib/omniauth_openid_federation/instrumentation.rb', line 251

def notify_unexpected_authentication_break(data = {})
  notify(
    EVENT_UNEXPECTED_AUTHENTICATION_BREAK,
    data: {
      reason: "Unexpected authentication break - something that should not fail has failed",
      **data
    },
    severity: :error
  )
end