scim_engine 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84aac5eb3121ba10036412a4c5d8ae959cf8fc99
-  data.tar.gz: f9c50a53333b47f4e6961dfa2a9fe256d2f207c7
+  metadata.gz: 4ed9981951b0782ba7db0326ff758e4dd8c708d2
+  data.tar.gz: 5f0df404b9c2f6c8c0a57bfc852ef250062bc487
 SHA512:
-  metadata.gz: 0bbf31701459d913599fdd83dd90b0120e19fc3c1cbff4133070293d93191044fb82fd2b2df79257544ee24618704d90946ebfea69ea632f243e30af0965584c
-  data.tar.gz: a53d3895e691a9aaa7ae5b4adfd7755d430c129b36b820c91a48568b03548a84e1b4673ab207dfae95b78ea03fd15c731369dda4a2c9bcc95c181e881cde6bdd
+  metadata.gz: b04416ef679a70dcd8f7de73815c00b08ada6ad979c5a3437be430d682744e036a09af46ae61dd77ebbf1361a545b2f9e087a10cdbffca42810ac17ffec3a9cd
+  data.tar.gz: 9c8bceaad662bd5b1b720ac277a63e1935857d3243260435814d7510ba690de64e5c1a8cbf352191ca844e1bad6b7173afb34f87cfcbcc00890a54f61837cea5

data/app/models/scim_engine/complex_types/base.rb

@@ -1,5 +1,20 @@
 module ScimEngine
   module ComplexTypes
+    # This class represents complex types that could be used inside SCIM resources.
+    # Each complex type must inherit from this class. They also need to have their own schema defined.
+    # @example
+    #  module ScimEngine
+    #    module ComplexTypes
+    #      class Email < Base
+    #        set_schema ScimEngine::Schema::Email
+    #
+    #        def as_json(options = {})
+    #          {'type' => 'work', 'primary' => true}.merge(super(options))
+    #        end
+    #      end
+    #    end
+    #  end
+    #
     class Base
       include ActiveModel::Model
       include ScimEngine::Schema::DerivedAttributes
@@ -10,6 +25,9 @@ module ScimEngine
         @errors = ActiveModel::Errors.new(self)
       end
 
+      # Converts the object to its SCIM representation which is always a json representation
+      # @param options [Hash] a hash that could provide default values for some of the attributes of this complex type object
+      #
       def as_json(options={})
         options[:except] ||= ['errors']
         super.except(options)

data/app/models/scim_engine/complex_types/email.rb

@@ -1,8 +1,11 @@
 module ScimEngine
   module ComplexTypes
+    # Represents the complex email type.
+    # @see ScimEngine::Schema::Email
     class Email < Base
       set_schema ScimEngine::Schema::Email
 
+      # Returns the json representation of an email.
       def as_json(options = {})
         {'type' => 'work', 'primary' => true}.merge(super(options))
       end

data/app/models/scim_engine/complex_types/name.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module ComplexTypes
+    # Represents the complex name type.
+    # @see ScimEngine::Schema::Name
     class Name < Base
       set_schema ScimEngine::Schema::Name
     end

data/app/models/scim_engine/complex_types/reference.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module ComplexTypes
+    # Represents the complex reference type.
+    # @see ScimEngine::Schema::Reference
     class Reference < Base
       set_schema ScimEngine::Schema::Reference
     end

data/app/models/scim_engine/resource_type.rb

@@ -1,4 +1,5 @@
 module ScimEngine
+  # Provides info about a resource type. Instances of this class are used to provide info through the /ResourceTypes endpoint of a SCIM service provider.
   class ResourceType
     include ActiveModel::Model
     attr_accessor :meta, :endpoint, :schema, :schemas, :id, :name, :schemaExtensions

data/app/models/scim_engine/resources/base.rb

@@ -1,5 +1,6 @@
 module ScimEngine
   module Resources
+    # The base class for all SCIM resources.
     class Base
       include ActiveModel::Model
       include ScimEngine::Schema::DerivedAttributes
@@ -27,6 +28,34 @@ module ScimEngine
         flattened
       end
 
+      # Can be used to extend an existing resource type's schema
+      # @example
+      #  module Scim
+      #    module Schema
+      #      class MyExtension < ScimEngine::Schema::Base
+      #
+      #        def initialize(options = {})
+      #          super(name: 'ExtendedGroup',
+      #                id: self.class.id,
+      #                description: 'Represents extra info about a group',
+      #                scim_attributes: self.class.scim_attributes)
+      #        end
+      #
+      #        def self.id
+      #          'urn:ietf:params:scim:schemas:extension:extendedgroup:2.0:Group'
+      #        end
+      #
+      #        def self.scim_attributes
+      #          [ScimEngine::Schema::Attribute.new(name: 'someAddedAttribute',
+      #                         type: 'string',
+      #                         required: true,
+      #                         canonicalValues: ['FOO', 'BAR'])]
+      #        end
+      #      end
+      #    end
+      #  end
+      #
+      #  ScimEngine::Resources::Group.extend_schema Scim::Schema::MyExtention
       def self.extend_schema(schema)
         derive_attributes_from_schema(schema)
         extended_schemas << schema

data/app/models/scim_engine/schema/attribute.rb

@@ -1,10 +1,16 @@
 module ScimEngine
   module Schema
+    # Represents an attribute of a SCIM resource that is declared in its schema.
+    # Attributes can be simple or complex. A complex attribute needs to have its own schema that is passed to the initilize method when the attribute is instantiated.
+    # @example
+    #  Attribute.new(name: 'userName', type: 'string', uniqueness: 'server')
+    #  Attribute.new(name: 'name', complexType: ScimEngine::ComplexTypes::Name)
     class Attribute
       include ActiveModel::Model
       include ScimEngine::Errors
       attr_accessor :name, :type, :multiValued, :required, :caseExact, :mutability, :returned, :uniqueness, :subAttributes, :complexType, :canonicalValues
 
+      # @param options [Hash] a hash of values to be used for instantiating the attribute object. Some of the instance variables of the objects will have default values if this hash does not contain anything for them.
       def initialize(options = {})
         defaults = {
           multiValued: false,
@@ -23,6 +29,9 @@ module ScimEngine
         super(defaults.merge(options || {}))
       end
 
+      # Validates a value against this attribute object. For simple attributes, it checks if blank is valid or not and if the type matches. For complex attributes, it delegates it to the valid? method of the complex type schema.
+      # If the value is not valid, validation message(s) are added to the errors attribute of this object.
+      # @return [Boolean] whether or not the value is valid for this attribute
       def valid?(value)
         return valid_blank? if value.blank? && !value.is_a?(FalseClass)
 

data/app/models/scim_engine/schema/base.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # The base class that each schema class must inherit from.
+    # These classes represent the schema of a SCIM resource or a complex type that could be used in a resource.
     class Base
       include ActiveModel::Model
       attr_accessor :id, :name, :description, :scim_attributes, :meta
@@ -9,12 +11,15 @@ module ScimEngine
         @meta = Meta.new(resourceType: "Schema")
       end
 
+      # Converts the schema to its json representation that will be returned by /SCHEMAS end-point of a SCIM service provider.
       def as_json(options = {})
         @meta.location = ScimEngine::Engine.routes.url_helpers.scim_schemas_path(name: id)
         original = super
         original.merge('attributes' => original.delete('scim_attributes'))
       end
 
+      # Validates the resource against specific validations of each attribute,for example if the type of the attribute matches the one defined in the schema.
+      # @param resource [Object] a resource object that uses this schema
       def self.valid?(resource)
         cloned_scim_attributes.each do |scim_attribute|
           resource.add_errors_from_hash(scim_attribute.errors.to_hash) unless scim_attribute.valid?(resource.send(scim_attribute.name))

data/app/models/scim_engine/schema/email.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # Represnts the schema for the Email complex type
+    # @see ScimEngine::ComplexTypes::Email
     class Email < Base
       def self.scim_attributes
         @scim_attributes ||= [

data/app/models/scim_engine/schema/group.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # Represnts the schema for the Group resource
+    # @see ScimEngine::Resources::Group
     class Group < Base
 
       def initialize(options = {})

data/app/models/scim_engine/schema/name.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # Represnts the schema for the Name complex type
+    # @see ScimEngine::ComplexTypes::Name
     class Name < Base
 
       def self.scim_attributes

data/app/models/scim_engine/schema/reference.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # Represnts the schema for the Reference complex type
+    # @see ScimEngine::ComplexTypes::Reference
     class Reference < Base
       def self.scim_attributes
         @scim_attributes ||= [

data/app/models/scim_engine/schema/user.rb

@@ -1,5 +1,7 @@
 module ScimEngine
   module Schema
+    # Represnts the schema for the User resource
+    # @see ScimEngine::Resources::User
     class User < Base
 
       def initialize(options = {})

data/app/models/scim_engine/service_provider_configuration.rb

@@ -1,4 +1,5 @@
 module ScimEngine
+  # Represnts the service provider info. Used by the /ServiceProviderConfig endpoint to privide specification compliance, authentication schemes, data models.
   class ServiceProviderConfiguration
     include ActiveModel::Model
 

data/lib/scim_engine/engine.rb

@@ -15,14 +15,30 @@ module ScimEngine
       default_resources + custom_resources
     end
 
+    # Can be used to add a new resource type which is not provided by the gem.
+    # @example
+    #  module Scim
+    #    module Resources
+    #      class ShinyResource < ScimEngine::Resources::Base
+    #        set_schema Scim::Schema::Shiny
+    #
+    #        def self.endpoint
+    #          "/Shinies"
+    #        end
+    #      end
+    #    end
+    #  end
+    #  ScimEngine::Engine.add_custom_resource Scim::Resources::ShinyResource
     def self.add_custom_resource(resource)
       custom_resources << resource
     end
 
+    # Returns the list of custom resources, if any.
     def self.custom_resources
       @custom_resources ||= []
     end
 
+    # Returns the default resources added in this gem: User and Group.
     def self.default_resources
       [ Resources::User, Resources::Group ]
     end

data/lib/scim_engine/version.rb

@@ -1,3 +1,3 @@
 module ScimEngine
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scim_engine
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - ''