Class: Saml::Kit::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/saml/kit/configuration.rb

Overview

This class represents the main configuration that is use for generating SAML documents.

Saml::Kit::Configuration.new do |config|
config.entity_id = "com:saml:kit"
config.signature_method = :SHA256
config.digest_method = :SHA256
config.registry = Saml::Kit::DefaultRegistry.new
config.session_timeout = 30.minutes
config.logger = Rails.logger
end

To specify global configuration it is best to do this in an initializer
that runs at the start of the program.

Saml::Kit.configure do |configuration|
configuration.entity_id = "https://www.example.com/saml/metadata"
configuration.generate_key_pair_for(use: :signing)
configuration.add_key_pair(
  ENV["X509_CERTIFICATE"],
    ENV["PRIVATE_KEY"],
    passphrase: ENV['PRIVATE_KEY_PASSPHRASE'],
    use: :encryption
)
end

Constant Summary collapse

USES = 
%i[signing encryption].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize {|_self| ... } ⇒ Configuration

Returns a new instance of Configuration.

Yields:

  • (_self)

Yield Parameters:



57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/saml/kit/configuration.rb', line 57

def initialize
  @clock_drift = 30.seconds
  @digest_method = :SHA256
  @key_pairs = []
  @logger = Logger.new(STDOUT)
  @registry = DefaultRegistry.new
  @session_timeout = 3.hours
  @signature_method = :SHA256
  @signature_required = true
  yield self if block_given?
end

Instance Attribute Details

#clock_drift ⇒ Object

The total allowable clock drift for session timeout validation.



48
49
50
 
# File 'lib/saml/kit/configuration.rb', line 48

def clock_drift
  @clock_drift
end

#digest_method ⇒ Object

The digest method to use when generating signatures (See Builders::XmlSignature::DIGEST_METHODS)



39
40
41
 
# File 'lib/saml/kit/configuration.rb', line 39

def digest_method
  @digest_method
end

#entity_id ⇒ Object

The issuer to use in requests or responses from this entity to use.



33
34
35
 
# File 'lib/saml/kit/configuration.rb', line 33

def entity_id
  @entity_id
end

#logger ⇒ Object

The logger to write log messages to.



46
47
48
 
# File 'lib/saml/kit/configuration.rb', line 46

def logger
  @logger
end

#registry ⇒ Object

The metadata registry to use for searching for metadata associated with an issuer.



42
43
44
 
# File 'lib/saml/kit/configuration.rb', line 42

def registry
  @registry
end

#session_timeout ⇒ Object

The session timeout to use when generating an Assertion.



44
45
46
 
# File 'lib/saml/kit/configuration.rb', line 44

def session_timeout
  @session_timeout
end

#signature_method ⇒ Object

The signature method to use when generating signatures (See Builders::XmlSignature::SIGNATURE_METHODS)



36
37
38
 
# File 'lib/saml/kit/configuration.rb', line 36

def signature_method
  @signature_method
end

#signature_required ⇒ Object

Whether a document that asserts an identity must carry a signature.

An unsigned Response or Assertion proves nothing about who issued it, so this defaults to true and should stay that way. Set it to false only to keep an identity provider that signs nothing working while it is being fixed, and understand that doing so accepts forged assertions.



55
56
57
 
# File 'lib/saml/kit/configuration.rb', line 55

def signature_required
  @signature_required
end

Instance Method Details

#add_key_pair(certificate, private_key, passphrase: nil, use: :signing) ⇒ Object

Add a key pair that can be used for either signing or encryption.

Parameters:

  • certificate (String) —

    the x509 certificate with public key.

  • private_key (String) —

    the plain text private key.

  • passphrase (String) (defaults to: nil) —

    the password to decrypt the private key.

  • use (Symbol) (defaults to: :signing) —

    the type of key pair, :signing or :encryption



75
76
77
78
79
80
81
82
 
# File 'lib/saml/kit/configuration.rb', line 75

def add_key_pair(certificate, private_key, passphrase: nil, use: :signing)
  ensure_proper_use(use)
  @key_pairs.push(
    ::Xml::Kit::KeyPair.new(
      certificate, private_key, passphrase, use.to_sym
    )
  )
end

#certificates(use: nil) ⇒ Object

Return each certificate for a specific use.

nil, :signing or :encryption

Parameters:

  • use (Symbol) (defaults to: nil) —

    the type of key pair to return



108
109
110
 
# File 'lib/saml/kit/configuration.rb', line 108

def certificates(use: nil)
  key_pairs(use: use).flat_map(&:certificate)
end

#generate_key_pair_for(use:, passphrase: SecureRandom.uuid) ⇒ Object

Generates a unique key pair that can be used for signing or encryption.

Parameters:

  • use (Symbol) —

    the type of key pair, :signing or :encryption

  • passphrase (String) (defaults to: SecureRandom.uuid) —

    the private key passphrase to use.



88
89
90
91
92
93
94
 
# File 'lib/saml/kit/configuration.rb', line 88

def generate_key_pair_for(use:, passphrase: SecureRandom.uuid)
  ensure_proper_use(use)
  certificate, private_key = ::Xml::Kit::SelfSignedCertificate.new.create(
    passphrase: passphrase
  )
  add_key_pair(certificate, private_key, passphrase: passphrase, use: use)
end

#key_pairs(use: nil) ⇒ Object

Return each key pair for a specific use.

nil, :signing or :encryption

Parameters:

  • use (Symbol) (defaults to: nil) —

    the type of key pair to return



100
101
102
 
# File 'lib/saml/kit/configuration.rb', line 100

def key_pairs(use: nil)
  use.present? ? active_key_pairs.find_all { |xxx| xxx.for?(use) } : active_key_pairs
end

#private_keys(use: nil) ⇒ Object

Return each private for a specific use.

nil, :signing or :encryption

Parameters:

  • use (Symbol) (defaults to: nil) —

    the type of key pair to return



116
117
118
 
# File 'lib/saml/kit/configuration.rb', line 116

def private_keys(use: nil)
  key_pairs(use: use).flat_map(&:private_key)
end

#sign? ⇒ Boolean

Returns true if there is at least one signing certificate registered.

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/saml/kit/configuration.rb', line 121

def sign?
  @sign ||= certificates(use: :signing).any?
end