saml2 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c776c54f1dc7f9b26b39544abd6bdde6c2f68a1f28339627ad9d8745cdfc4ee7
-  data.tar.gz: 703170dd49abeb43b09070b6000f748737d1ccbe0374b154c274f84065935daa
+  metadata.gz: 7882f9e6593924c18faed398409e973ca227162a990557156d7992a51c4f7cdb
+  data.tar.gz: c862c3fd1c560068e59340ba4f19a3d810807b6c22a4c36c07fb0ef9a6711132
 SHA512:
-  metadata.gz: 74fe75be6913966fd33a9e72535398a2ecc6916f483aeb47b3202afba09fb175b3c2234c8dfb63a0d48b1aa9f3536204635471e0ab73c125b8276d063838e7cb
-  data.tar.gz: dd4f61cc065ebfc647c4306a084b56e5eb5fd57877898f05a67a09c5df87837f34d8c503ca933aa2f50cc770f44e6712bc0ee9192a0f9d07a48d8fb4a974154f
+  metadata.gz: 89aa07641f0625f8f9fd781cb41a169349567531984c1fe2adc278ae0568687c4e4822be1a9c00e0c561116ffbc39d140abde34a1be439bd36b1a3869d34dcf5
+  data.tar.gz: f07d6fbf9dc816d3223ae9cd1728b3232b469b61057ae7e6e14518efd939e3e8e4aff5c1e3b4a3c56584d7e5dbc9abc33dab180452a8b5d9b5ff7e34012c15e3

data/lib/saml2.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'saml2/authn_request'
 require 'saml2/entity'
 require 'saml2/logout_request'

data/lib/saml2/assertion.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'saml2/conditions'
 
 module SAML2
@@ -16,6 +18,7 @@ module SAML2
       @statements = nil
     end
 
+    # @return [Subject, nil]
     def subject
       if xml && !instance_variable_defined?(:@subject)
         @subject = Subject.from_xml(xml.at_xpath('saml:Subject', Namespaces::ALL))
@@ -23,14 +26,17 @@ module SAML2
       @subject
     end
 
+    # @return [Conditions]
     def conditions
       @conditions ||= Conditions.from_xml(xml.at_xpath('saml:Conditions', Namespaces::ALL))
     end
 
+    # @return [Array<AuthnStatement, AttributeStatement>]
     def statements
       @statements ||= load_object_array(xml, 'saml:AuthnStatement|saml:AttributeStatement')
     end
 
+    # (see Base#build)
     def build(builder)
       builder['saml'].Assertion(
           'xmlns:saml' => Namespaces::SAML

data/lib/saml2/attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'date'
 
 require 'active_support/core_ext/array/wrap'
@@ -8,20 +10,13 @@ require 'saml2/namespaces'
 module SAML2
   class Attribute < Base
     module NameFormats
-      BASIC       = "urn:oasis:names:tc:SAML:2.0:attrname-format:basic".freeze
-      UNSPECIFIED = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified".freeze
-      URI         = "urn:oasis:names:tc:SAML:2.0:attrname-format:uri".freeze
+      BASIC       = "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
+      UNSPECIFIED = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
+      URI         = "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
     end
 
     class << self
-      def subclasses
-        @subclasses ||= []
-      end
-
-      def inherited(klass)
-        subclasses << klass
-      end
-
+      # (see Base.from_xml)
       def from_xml(node)
         # pass through for subclasses
         return super unless self == Attribute
@@ -31,20 +26,43 @@ module SAML2
         klass ? klass.from_xml(node) : super
       end
 
+      # Create an appropriate object to represent an attribute.
+      #
+      # This will create the most appropriate object (i.e. an
+      # {Attribute::X500} if possible) to represent this attribute,
+      # based on its name.
+      # @param name [String]
+      #   The attribute name. This can be a friendly name, or a URI.
+      # @param value optional
+      #   The attribute value.
+      # @return [Attribute]
       def create(name, value = nil)
         (class_for(name) || self).new(name, value)
       end
 
+      # The XML namespace that this attribute class serializes as.
+      # @return ['saml']
       def namespace
         'saml'
       end
 
+      # The XML element that this attribute class serializes as.
+      # @return ['Attribute']
       def element
         'Attribute'
       end
 
       protected
 
+      def subclasses
+        @subclasses ||= []
+      end
+
+      def inherited(klass)
+        subclasses << klass
+      end
+
+
       def class_for(name_or_node)
         subclasses.find do |klass|
           klass.respond_to?(:recognizes?) && klass.recognizes?(name_or_node)
@@ -52,12 +70,24 @@ module SAML2
       end
     end
 
-    attr_accessor :name, :friendly_name, :name_format, :value
-
+    # @return [String]
+    attr_accessor :name
+    # @return [String, nil]
+    attr_accessor :friendly_name, :name_format
+    # @return [Object, nil]
+    attr_accessor :value
+
+    # Create a new generic Attribute
+    #
+    # @param name [String]
+    # @param value optional [Object, nil]
+    # @param friendly_name optional [String, nil]
+    # @param name_format optional [String, nil]
     def initialize(name = nil, value = nil, friendly_name = nil, name_format = nil)
       @name, @value, @friendly_name, @name_format = name, value, friendly_name, name_format
     end
 
+    # (see Base#build)
     def build(builder)
       builder[self.class.namespace].__send__(self.class.element, 'Name' => name) do |attribute|
         attribute.parent['FriendlyName'] = friendly_name if friendly_name
@@ -71,6 +101,7 @@ module SAML2
       end
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @name = node['Name']
@@ -87,6 +118,7 @@ module SAML2
     end
 
     private
+
     XS_TYPES = {
       lookup_qname('xs:boolean', Namespaces::ALL) =>
         [[TrueClass, FalseClass], nil, ->(v) { %w{true 1}.include?(v) ? true : false }],

data/lib/saml2/attribute/x500.rb

@@ -1,34 +1,38 @@
+# frozen_string_literal: true
+
 module SAML2
   class Attribute
     class X500 < Attribute
-      GIVEN_NAME             = 'urn:oid:2.5.4.42'.freeze
-      SN = SURNAME           = 'urn:oid:2.5.4.4'.freeze
+      GIVEN_NAME             = 'urn:oid:2.5.4.42'
+      SN = SURNAME           = 'urn:oid:2.5.4.4'
       # https://www.ietf.org/rfc/rfc2798.txt
       module InetOrgPerson
-        DISPLAY_NAME         = 'urn:oid:2.16.840.1.113730.3.1.241'.freeze
-        EMPLOYEE_NUMBER      = 'urn:oid:2.16.840.1.113730.3.1.3'.freeze
-        EMPLOYEE_TYPE        = 'urn:oid:2.16.840.1.113730.3.1.4'.freeze
-        PREFERRED_LANGUAGE   = 'urn:oid:2.16.840.1.113730.3.1.39'.freeze
+        DISPLAY_NAME         = 'urn:oid:2.16.840.1.113730.3.1.241'
+        EMPLOYEE_NUMBER      = 'urn:oid:2.16.840.1.113730.3.1.3'
+        EMPLOYEE_TYPE        = 'urn:oid:2.16.840.1.113730.3.1.4'
+        PREFERRED_LANGUAGE   = 'urn:oid:2.16.840.1.113730.3.1.39'
       end
       # https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html
       module EduPerson
-        AFFILIATION          = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.1'.freeze
-        ASSURANCE            = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.11'.freeze
-        ENTITLEMENT          = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7'.freeze
-        NICKNAME             = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.2'.freeze
-        ORG_D_N              = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.3'.freeze
-        PRIMARY_AFFILIATION  = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.5'.freeze
-        PRIMARY_ORG_UNIT_D_N = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.8'.freeze
-        PRINCIPAL_NAME       = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6'.freeze
-        SCOPED_AFFILIATION   = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.9'.freeze
-        TARGETED_I_D         = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.10'.freeze
-        UNIT_D_N             = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.4'.freeze
+        AFFILIATION          = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.1'
+        ASSURANCE            = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.11'
+        ENTITLEMENT          = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7'
+        NICKNAME             = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.2'
+        ORG_D_N              = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.3'
+        PRIMARY_AFFILIATION  = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.5'
+        PRIMARY_ORG_UNIT_D_N = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.8'
+        PRINCIPAL_NAME       = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6'
+        SCOPED_AFFILIATION   = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.9'
+        TARGETED_I_D         = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.10'
+        UNIT_D_N             = 'urn:oid:1.3.6.1.4.1.5923.1.1.1.4'
       end
       # http://www.ietf.org/rfc/rfc4519.txt
-      UID = USERID           = 'urn:oid:0.9.2342.19200300.100.1.1'.freeze
+      UID = USERID           = 'urn:oid:0.9.2342.19200300.100.1.1'
       # http://www.ietf.org/rfc/rfc4524.txt
-      MAIL                   = 'urn:oid:0.9.2342.19200300.100.1.3'.freeze
+      MAIL                   = 'urn:oid:0.9.2342.19200300.100.1.3'
 
+      # Returns true if the param should be an {X500} Attribute.
+      # @param name_or_node [String, Nokogiri::XML::Element]
       def self.recognizes?(name_or_node)
         if name_or_node.is_a?(Nokogiri::XML::Element)
           !!name_or_node.at_xpath("@x500:Encoding", Namespaces::ALL)
@@ -37,6 +41,14 @@ module SAML2
         end
       end
 
+      # Create a new X.500 attribute.
+      #
+      # The name format will always be set to URI.
+      #
+      # @param name [String]
+      #   Either an OID or a known friendly name. The opposite value will be
+      #   inferred automatically.
+      # @param value optional [Object, nil]
       def initialize(name = nil, value = nil)
         # if they pass an OID, infer the friendly name
         friendly_name = OIDS[name]
@@ -51,6 +63,7 @@ module SAML2
         super(name, value, friendly_name, NameFormats::URI)
       end
 
+      # (see Base#build)
       def build(builder)
         super
         attr = builder.parent.last_element_child

data/lib/saml2/attribute_consuming_service.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/array/wrap'
 
 require 'saml2/attribute'
@@ -8,40 +10,61 @@ require 'saml2/namespaces'
 module SAML2
   class RequestedAttribute < Attribute
     class << self
+      # The XML namespace that this attribute class serializes as.
+      # @return ['md']
       def namespace
         'md'
       end
 
+      # The XML element that this attribute class serializes as.
+      # @return ['RequestedAttribute']
       def element
         'RequestedAttribute'
       end
 
+      # Create a RequestAttribute object to represent an attribute.
+      #
+      # {Attribute.create} will be used to create a temporary object, so that
+      # attribute-class specific inferences (i.e. {Attribute::X500} friendly
+      # names) will be done, but always returns a {RequestedAttribute}.
+      # @param name [String]
+      #   The attribute name. This can be a friendly name, or a URI.
+      # @param is_required optional [true, false, nil]
+      # @return [RequestedAttribute]
       def create(name, is_required = nil)
-        # use Attribute.create to get other subclasses to automatically fill out friendly_name
-        # and name_format, but still return a RequestedAttribute object
         attribute = Attribute.create(name)
         new(attribute.name, is_required, attribute.friendly_name, attribute.name_format)
       end
     end
 
+    # Create a new {RequestedAttribute}.
+    #
+    # @param name [String]
+    # @param is_required optional [true, false, nil]
+    # @param friendly_name optional [String, nil]
+    # @param name_format optional [String, nil]
     def initialize(name = nil, is_required = nil, friendly_name = nil, name_format = nil)
       super(name, nil, friendly_name, name_format)
       @is_required = is_required
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @is_required = node['isRequired'] && node['isRequired'] == 'true'
     end
 
+    # @return [true, false, nil]
     def required?
       @is_required
     end
   end
 
   class RequiredAttributeMissing < RuntimeError
+    # @return [RequestedAttribute]
     attr_reader :requested_attribute
 
+    # @param requested_attribute [RequestedAttribute]
     def initialize(requested_attribute)
       super("Required attribute #{requested_attribute.name} not provided")
       @requested_attribute = requested_attribute
@@ -49,8 +72,11 @@ module SAML2
   end
 
   class InvalidAttributeValue < RuntimeError
-    attr_reader :requested_attribute, :provided_value
+    # @return [RequestedAttribute]
+    attr_reader :requested_attribute
+    attr_reader :provided_value
 
+    # @param requested_attribute [RequestedAttribute]
     def initialize(requested_attribute, provided_value)
       super("Attribute #{requested_attribute.name} is provided value " \
         "#{provided_value.inspect}, but only allows "                  \
@@ -62,8 +88,13 @@ module SAML2
   class AttributeConsumingService < Base
     include IndexedObject
 
-    attr_reader :name, :description, :requested_attributes
+    # @return [LocalizedName]
+    attr_reader :name, :description
+    # @return [Array<RequestedAttribute>]
+    attr_reader :requested_attributes
 
+    # @param name [String]
+    # @param requested_attributes [::Array<RequestedAttributes>]
     def initialize(name = nil, requested_attributes = [])
       super()
       @name = LocalizedName.new('ServiceName', name)
@@ -71,6 +102,7 @@ module SAML2
       @requested_attributes = requested_attributes
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       name.from_xml(node.xpath('md:ServiceName', Namespaces::ALL))
@@ -78,6 +110,21 @@ module SAML2
       @requested_attributes = load_object_array(node, "md:RequestedAttribute", RequestedAttribute)
     end
 
+    # Create an {AttributeStatement} from the given attributes hash.
+    #
+    # Given a set of attributes, create and return an {AttributeStatement}
+    # with only the attributes that this {AttributeConsumingService} requests.
+    #
+    # @param attributes [Hash<String => Object>, Array<Attribute>]
+    #   If it's a hash, the elements are run through {Attribute.create} first
+    #   in order to create proper {Attribute} objects.
+    # @return [AttributeStatement]
+    # @raise [InvalidAttributeValue]
+    #   If a {RequestedAttribute} specifies that only specific values are
+    #   permissible, and the provided attribute does not match that value.
+    # @raise [RequiredAttributeMissing]
+    #   If a {RequestedAttribute} is tagged as required, but it has not been
+    #   supplied.
     def create_statement(attributes)
       if attributes.is_a?(Hash)
         attributes = attributes.map { |k, v| Attribute.create(k, v) }
@@ -119,6 +166,7 @@ module SAML2
       AttributeStatement.new(attributes)
     end
 
+    # (see Base#build)
     def build(builder)
       builder['md'].AttributeConsumingService do |attribute_consuming_service|
         name.build(attribute_consuming_service)

data/lib/saml2/authn_request.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 require 'zlib'
 
@@ -16,12 +18,22 @@ module SAML2
     attr_writer :assertion_consumer_service_index,
                 :assertion_consumer_service_url,
                 :attribute_consuming_service_index,
-                :force_authn,
                 :name_id_policy,
-                :passive,
                 :protocol_binding
+    # @return [Boolean, nil]
+    attr_writer :force_authn, :passive
+    # @return [RequestedAuthnContext, nil]
     attr_accessor :requested_authn_context
 
+    # Initiate a SAML SSO flow, from a service provider to an identity
+    # provider.
+    # @todo go over these params, and use kwargs. Maybe pass Entity instead
+    #   of ServiceProvider.
+    # @param issuer [NameID]
+    # @param identity_provider [IdentityProvider]
+    # @param assertion_consumer_service [Endpoint::Indexed]
+    # @param service_provider [ServiceProvider]
+    # @return [AuthnRequest]
     def self.initiate(issuer, identity_provider = nil,
         assertion_consumer_service: nil,
         service_provider: nil)
@@ -37,6 +49,7 @@ module SAML2
       authn_request
     end
 
+    # @see https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf section 4.1
     def valid_web_browser_sso_profile?
       return false unless issuer
       return false if issuer.format && issuer.format != NameID::Format::ENTITY
@@ -44,6 +57,7 @@ module SAML2
       true
     end
 
+    # @see https://saml2int.org/profile/current/#section82
     def valid_interoperable_profile?
       # It's a subset of Web Browser SSO profile
       return false unless valid_web_browser_sso_profile?
@@ -55,6 +69,14 @@ module SAML2
       true
     end
 
+    # Populate {#assertion_consumer_service} and {#attribute_consuming_service}
+    # attributes.
+    #
+    # Given {ServiceProvider} metadata, resolve the index/urls in this object to actual
+    # objects.
+    #
+    # @param service_provider [ServiceProvider]
+    # @return [Boolean]
     def resolve(service_provider)
       # TODO: check signature if present
 
@@ -71,6 +93,7 @@ module SAML2
       true
     end
 
+    # @return [NameID::Policy, nil]
     def name_id_policy
       if xml && !instance_variable_defined?(:@name_id_policy)
         @name_id_policy = NameID::Policy.from_xml(xml.at_xpath('samlp:NameIDPolicy', Namespaces::ALL))
@@ -78,8 +101,14 @@ module SAML2
       @name_id_policy
     end
 
-    attr_reader :assertion_consumer_service, :attribute_consuming_service
+    # Must call {#resolve} before accessing.
+    # @return [AssertionConsumerService, nil]
+    attr_reader :assertion_consumer_service
+    # Must call {#resolve} before accessing.
+    # @return [AttributeConsumingService, nil]
+    attr_reader :attribute_consuming_service
 
+    # @return [Integer, nil]
     def assertion_consumer_service_index
       if xml && !instance_variable_defined?(:@assertion_consumer_service_index)
         @assertion_consumer_service_index = xml['AssertionConsumerServiceIndex']&.to_i
@@ -87,6 +116,7 @@ module SAML2
       @assertion_consumer_service_index
     end
 
+    # @return [String, nil]
     def assertion_consumer_service_url
       if xml && !instance_variable_defined?(:@assertion_consumer_service_url)
         @assertion_consumer_service_url = xml['AssertionConsumerServiceURL']
@@ -94,6 +124,7 @@ module SAML2
       @assertion_consumer_service_url
     end
 
+    # @return [Integer, nil]
     def attribute_consuming_service_index
       if xml && !instance_variable_defined?(:@attribute_consuming_service_index)
         @attribute_consuming_service_index = xml['AttributeConsumingServiceIndex']&.to_i
@@ -101,6 +132,7 @@ module SAML2
       @attribute_consuming_service_index
     end
 
+    # @return [true, false, nil]
     def force_authn?
       if xml && !instance_variable_defined?(:@force_authn)
         @force_authn = xml['ForceAuthn']&.== 'true'
@@ -108,6 +140,7 @@ module SAML2
       @force_authn
     end
 
+    # @return [true, false, nil]
     def passive?
       if xml && !instance_variable_defined?(:@passive)
         @passive = xml['IsPassive']&.== 'true'
@@ -115,6 +148,7 @@ module SAML2
       @passive
     end
 
+    # @return [String, nil]
     def protocol_binding
       if xml && !instance_variable_defined?(:@protocol_binding)
         @protocol_binding = xml['ProtocolBinding']
@@ -122,6 +156,7 @@ module SAML2
       @protocol_binding
     end
 
+    # @return [Subject, nil]
     def subject
       if xml && !instance_variable_defined?(:@subject)
         @subject = Subject.from_xml(xml.at_xpath('saml:Subject', Namespaces::ALL))
@@ -129,6 +164,7 @@ module SAML2
       @subject
     end
 
+    # (see Base#build)
     def build(builder)
       builder['samlp'].AuthnRequest(
           'xmlns:samlp' => Namespaces::SAMLP,