saml2 2.0.2 → 2.1.0

data/lib/saml2/logout_response.rb

@@ -1,7 +1,14 @@
+# frozen_string_literal: true
+
 require 'saml2/status_response'
 
 module SAML2
   class LogoutResponse < StatusResponse
+    # @param logout_request [LogoutRequest]
+    # @param sso [SSO]
+    # @param issuer [NameID]
+    # @param status_code [String]
+    # @return [LogoutResponse]
     def self.respond_to(logout_request, sso, issuer, status_code = Status::SUCCESS)
       logout_response = new
       logout_response.issuer = issuer
@@ -11,6 +18,8 @@ module SAML2
       logout_response
     end
 
+    private
+
     def build(builder)
       builder['samlp'].LogoutResponse(
                           'xmlns:samlp' => Namespaces::SAMLP,

data/lib/saml2/message.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'securerandom'
 require 'time'
 
@@ -37,18 +39,23 @@ module SAML2
 
   # In the SAML Schema, Request and Response don't technically share a common
   # ancestor, but they have several things in common so it's useful to represent
-  # that here
+  # that in this gem as a common base class.
+  # @abstract
   class Message < Base
     include Signable
 
     attr_writer :issuer, :destination
 
     class << self
-      def inherited(klass)
-        # explicitly keep track of all messages in this base class
-        Message.known_messages[klass.name.sub(/^SAML2::/, '')] = klass
-      end
-
+      # Create an appropriate {Message} subclass instance to represent the
+      # given XML element.
+      #
+      # When called on a subclass, it behaves the same as {Base.from_xml}
+      #
+      # @param node [Nokogiri::XML::Element]
+      # @return [Message]
+      # @raise [UnknownMessage] If the element doesn't correspond to a known
+      #   SAML message type.
       def from_xml(node)
         return super unless self == Message
         klass = Message.known_messages[node.name]
@@ -56,6 +63,13 @@ module SAML2
         klass.from_xml(node)
       end
 
+      # Parses XML, and returns an appropriate {Message} subclass instance.
+      #
+      # @param xml [String, IO] Anything that can be passed to +Nokogiri::XML+.
+      # @return [Message]
+      # @raise [UnexpectedMessage]
+      #   If called on a subclass, will raise if the parsed message does not
+      #   match the class is was called on.
       def parse(xml)
         result = Message.from_xml(Nokogiri::XML(xml) { |config| config.strict }.root)
         raise UnexpectedMessage.new("Expected a #{self.name}, but got a #{result.class.name}") unless self == Message || result.class == self
@@ -69,6 +83,12 @@ module SAML2
       def known_messages
         @known_messages ||= {}
       end
+
+      def inherited(klass)
+        # explicitly keep track of all messages in this base class
+        Message.known_messages[klass.name.sub(/^SAML2::/, '')] = klass
+      end
+
     end
 
     def initialize
@@ -77,23 +97,30 @@ module SAML2
       @issue_instant = Time.now.utc
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @id = nil
       @issue_instant = nil
     end
 
+    # If the XML is valid according to SAML XSDs.
+    # @return [Boolean]
     def valid_schema?
       return false unless Schemas.protocol.valid?(xml.document)
 
       true
     end
 
-    def validate_signature(fingerprint: nil, cert: nil, verification_time: nil)
+    # (see Signable#validate_signature)
+    # @param verification_time
+    #   Ignored. The message's {issue_instant} is always used.
+    def validate_signature(fingerprint: nil, cert: nil, verification_time: issue_instant)
       # verify the signature (certificate's validity) as of the time the message was generated
       super(fingerprint: fingerprint, cert: cert, verification_time: issue_instant)
     end
 
+    # (see Signable#sign)
     def sign(x509_certificate, private_key, algorithm_name = :sha256)
       super
 
@@ -105,14 +132,17 @@ module SAML2
       self
     end
 
+    # @return [String]
     def id
       @id ||= xml['ID']
     end
 
+    # @return [Time]
     def issue_instant
       @issue_instant ||= Time.parse(xml['IssueInstant'])
     end
 
+    # @return [String, nil]
     def destination
       if xml && !instance_variable_defined?(:@destination)
         @destination = xml['Destination']
@@ -120,6 +150,7 @@ module SAML2
       @destination
     end
 
+    # @return [NameID, nil]
     def issuer
       @issuer ||= NameID.from_xml(xml.at_xpath('saml:Issuer', Namespaces::ALL))
     end

data/lib/saml2/name_id.rb

@@ -1,27 +1,36 @@
+# frozen_string_literal: true
+
+require 'saml2/base'
 require 'saml2/namespaces'
 
 module SAML2
-  class NameID
+  class NameID < Base
     module Format
-      EMAIL_ADDRESS                 = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress".freeze
-      ENTITY                        = "urn:oasis:names:tc:SAML:2.0:nameid-format:entity".freeze
-      KERBEROS                      = "urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos".freeze # name[/instance]@REALM
-      PERSISTENT                    = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent".freeze # opaque, pseudo-random, unique per SP-IdP pair
-      TRANSIENT                     = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient".freeze # opaque, will likely change
-      UNSPECIFIED                   = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified".freeze
-      WINDOWS_DOMAIN_QUALIFIED_NAME = "urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName".freeze # [DomainName\]UserName
-      X509_SUBJECT_NAME             = "urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName".freeze
+      EMAIL_ADDRESS                 = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+      ENTITY                        = "urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
+      KERBEROS                      = "urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos" # name[/instance]@REALM
+      PERSISTENT                    = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" # opaque, pseudo-random, unique per SP-IdP pair
+      TRANSIENT                     = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient" # opaque, will likely change
+      UNSPECIFIED                   = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
+      WINDOWS_DOMAIN_QUALIFIED_NAME = "urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName" # [DomainName\]UserName
+      X509_SUBJECT_NAME             = "urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
     end
 
     class Policy < Base
-      attr_writer :allow_create, :format, :sp_name_qualifier
+      # @return [Boolean, nil]
+      attr_writer :allow_create
+      attr_writer :format, :sp_name_qualifier
 
+      # @param allow_create optional [Boolean]
+      # @param format optional [String]
+      # @param sp_name_qualifier optional [String]
       def initialize(allow_create = nil, format = nil, sp_name_qualifier = nil)
         @allow_create = allow_create if allow_create
         @format = format if format
         @sp_name_qualifier = sp_name_qualifier if sp_name_qualifier
       end
 
+      # @return [Boolean, nil]
       def allow_create?
         if xml && !instance_variable_defined?(:@allow_create)
           @allow_create = xml['AllowCreate']&.== 'true'
@@ -29,6 +38,8 @@ module SAML2
         @allow_create
       end
 
+      # @see Format
+      # @return [String, nil]
       def format
         if xml && !instance_variable_defined?(:@format)
           @format = xml['Format']
@@ -36,6 +47,7 @@ module SAML2
         @format
       end
 
+      # @return [String, nil]
       def sp_name_qualifier
         if xml && !instance_variable_defined?(:@sp_name_qualifier)
           @sp_name_qualifier = xml['SPNameQualifier']
@@ -43,12 +55,15 @@ module SAML2
         @sp_name_qualifier
       end
 
+      # @param rhs [Policy]
+      # @return [Boolean]
       def ==(rhs)
         allow_create? == rhs.allow_create? &&
             format == rhs.format &&
             sp_name_qualifier == rhs.sp_name_qualifier
       end
 
+      # (see Base#build)
       def build(builder)
         builder['samlp'].NameIDPolicy do |name_id_policy|
           name_id_policy.parent['Format'] = format if format
@@ -58,20 +73,30 @@ module SAML2
       end
     end
 
-    attr_accessor :id, :format, :name_qualifier, :sp_name_qualifier
+    # @return [String]
+    attr_accessor :id
+    # @return [String, nil]
+    attr_accessor :format, :name_qualifier, :sp_name_qualifier
 
-    def self.from_xml(node)
-      node && new(node.content.strip,
-                  node['Format'],
-                  name_qualifier: node['NameQualifier'],
-                  sp_name_qualifier: node['SPNameQualifier'])
+    # (see Base#from_xml)
+    def from_xml(node)
+      self.id = node.content.strip
+      self.format = node['Format']
+      self.name_qualifier = node['NameQualifier']
+      self.sp_name_qualifier = node['SPNameQualifier']
     end
 
+    # @param id [String]
+    # @param format optional [String]
+    # @param name_qualifier optional [String]
+    # @param sp_name_qualifier optional [String]
     def initialize(id = nil, format = nil, name_qualifier: nil, sp_name_qualifier: nil)
       @id, @format, @name_qualifier, @sp_name_qualifier =
           id, format, name_qualifier, sp_name_qualifier
     end
 
+    # @param rhs [NameID]
+    # @return [Boolean]
     def ==(rhs)
       id == rhs.id &&
           format == rhs.format &&
@@ -79,6 +104,7 @@ module SAML2
           sp_name_qualifier == rhs.sp_name_qualifier
     end
 
+    # (see Base#build)
     def build(builder, element: nil)
       args = {}
       args['Format'] = format if format

data/lib/saml2/namespaces.rb

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 module SAML2
   module Namespaces
-    DSIG     = "http://www.w3.org/2000/09/xmldsig#".freeze
-    METADATA = "urn:oasis:names:tc:SAML:2.0:metadata".freeze
-    SAML     = "urn:oasis:names:tc:SAML:2.0:assertion".freeze
-    SAMLP    = "urn:oasis:names:tc:SAML:2.0:protocol".freeze
-    XENC     = "http://www.w3.org/2001/04/xmlenc#".freeze
-    XS       = "http://www.w3.org/2001/XMLSchema".freeze
-    XSI      = "http://www.w3.org/2001/XMLSchema-instance".freeze
-    X500     = "urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500".freeze
+    DSIG     = "http://www.w3.org/2000/09/xmldsig#"
+    METADATA = "urn:oasis:names:tc:SAML:2.0:metadata"
+    SAML     = "urn:oasis:names:tc:SAML:2.0:assertion"
+    SAMLP    = "urn:oasis:names:tc:SAML:2.0:protocol"
+    XENC     = "http://www.w3.org/2001/04/xmlenc#"
+    XS       = "http://www.w3.org/2001/XMLSchema"
+    XSI      = "http://www.w3.org/2001/XMLSchema-instance"
+    X500     = "urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"
 
     ALL = {
         'xmlns:dsig'  => DSIG,

data/lib/saml2/organization.rb

@@ -1,11 +1,15 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 require 'saml2/localized_name'
 require 'saml2/namespaces'
 
 module SAML2
   class Organization < Base
+    # @return [LocalizedName]
     attr_reader :name, :display_name, :url
 
+    # (see Base#from_xml)
     def from_xml(node)
       name.from_xml(node.xpath('md:OrganizationName', Namespaces::ALL))
       display_name.from_xml(node.xpath('md:OrganizationDisplayName', Namespaces::ALL))
@@ -18,6 +22,7 @@ module SAML2
       @url = LocalizedName.new('OrganizationURL', url)
     end
 
+    # (see Base#build)
     def build(builder)
       builder['md'].Organization do |organization|
         @name.build(organization)

data/lib/saml2/organization_and_contacts.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'saml2/contact'
 require 'saml2/organization'
 
@@ -10,12 +12,14 @@ module SAML2
       @contacts = []
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       remove_instance_variable(:@organization)
       @contacts = nil
       super
     end
 
+    # @return [Organization, nil]
     def organization
       unless instance_variable_defined?(:@organization)
         @organization = Organization.from_xml(xml.at_xpath('md:Organization', Namespaces::ALL))
@@ -23,6 +27,7 @@ module SAML2
       @organization
     end
 
+    # @return [Array<Contact>]
     def contacts
       @contacts ||= load_object_array(xml, 'md:ContactPerson', Contact)
     end

data/lib/saml2/request.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 require 'saml2/message'
 require 'saml2/name_id'
 require 'saml2/namespaces'
 
 module SAML2
+  # @abstract
   class Request < Message
   end
 end

data/lib/saml2/requested_authn_context.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 
 module SAML2
   class RequestedAuthnContext < Base
-    attr_accessor :comparison, :class_ref
+    # @return [String, nil]
+    attr_accessor :comparison
+    # @return [String, Array<String>]
+    attr_accessor :class_ref
 
+    # (see Base#build)
     def build(builder)
       builder['samlp'].RequestedAuthnContext do |requested_authn_context|
         requested_authn_context.parent['Comparison'] = comparison.to_s if comparison

data/lib/saml2/response.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'nokogiri-xmlsec'
 require 'time'
 
@@ -10,6 +12,12 @@ module SAML2
   class Response < StatusResponse
     attr_reader :assertions
 
+    # Respond to an {AuthnRequest}
+    # @param authn_request [AuthnRequest]
+    # @param issuer [NameID]
+    # @param name_id [NameID] The Subject
+    # @param attributes optional [Hash<String => String>, Array<Attribute>]
+    # @return [Response]
     def self.respond_to(authn_request, issuer, name_id, attributes = nil)
       response = initiate(nil, issuer, name_id)
       response.in_response_to = authn_request.id
@@ -26,6 +34,12 @@ module SAML2
       response
     end
 
+    # Begin an IdP Initiated login
+    # @param service_provider [ServiceProvider]
+    # @param issuer [NameID]
+    # @param name_id [NameID] The subject
+    # @param attributes optional [Hash<String => String>, Array<Attribute>]
+    # @return [Response]
     def self.initiate(service_provider, issuer, name_id, attributes = nil)
       response = new
       response.issuer = issuer
@@ -57,11 +71,13 @@ module SAML2
       @assertions = []
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       remove_instance_variable(:@assertions)
     end
 
+    # @return [Array<Assertion>]
     def assertions
       unless instance_variable_defined?(:@assertions)
         @assertions = load_object_array(xml, 'saml:Assertion', Assertion)
@@ -69,8 +85,10 @@ module SAML2
       @assertions
     end
 
-    def sign(*args)
-      assertions.each { |assertion| assertion.sign(*args) }
+    # (see Signable#sign)
+    # Signs each assertion.
+    def sign(x509_certificate, private_key, algorithm_name = :sha256)
+      assertions.each { |assertion| assertion.sign(x509_certificate, private_key, algorithm_name) }
       # make sure we no longer pretty print this object
       @pretty = false
       nil

data/lib/saml2/role.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'set'
 
 require 'saml2/base'
@@ -6,9 +8,10 @@ require 'saml2/organization_and_contacts'
 require 'saml2/signable'
 
 module SAML2
+  # @abstract
   class Role < Base
     module Protocols
-      SAML2 = 'urn:oasis:names:tc:SAML:2.0:protocol'.freeze
+      SAML2 = 'urn:oasis:names:tc:SAML:2.0:protocol'
     end
 
     include OrganizationAndContacts
@@ -23,29 +26,36 @@ module SAML2
       @keys = []
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @supported_protocols = nil
       @keys = nil
     end
 
+    # @see Protocols
+    # @return [Array<String>]
     def supported_protocols
       @supported_protocols ||= xml['protocolSupportEnumeration'].split
     end
 
+    # @return [Array<KeyDescriptor>]
     def keys
-      @keys ||= load_object_array(xml, 'md:KeyDescriptor', Key)
+      @keys ||= load_object_array(xml, 'md:KeyDescriptor', KeyDescriptor)
     end
 
+    # @return [Array<KeyDescriptor>]
     def signing_keys
       keys.select { |key| key.signing? }
     end
 
+    # @return [Array<KeyDescriptor>]
     def encryption_keys
       keys.select { |key| key.encryption? }
     end
 
     protected
+
     # should be called from inside the role element
     def build(builder)
       builder.parent['protocolSupportEnumeration'] = supported_protocols.to_a.join(' ')