entitlements 0.1.7

data/lib/entitlements/backend/ldap/controller.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class LDAP
+      class Controller < Entitlements::Backend::BaseController
+        register
+
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor. Generic constructor that takes a hash of configuration options.
+        #
+        # group_name - Name of the corresponding group in the entitlements configuration file.
+        # config     - Optionally, a Hash of configuration information (configuration is referenced if empty).
+        Contract String, C::Maybe[C::HashOf[String => C::Any]] => C::Any
+        def initialize(group_name, config = nil)
+          super
+
+          @ldap = Entitlements::Service::LDAP.new_with_cache(
+            addr: @config.fetch("ldap_uri"),
+            binddn: @config.fetch("ldap_binddn"),
+            bindpw: @config.fetch("ldap_bindpw"),
+            ca_file: @config.fetch("ldap_ca_file", ENV["LDAP_CACERT"]),
+            disable_ssl_verification: @config.fetch("ldap_disable_ssl_verification", false),
+            person_dn_format: @config.fetch("person_dn_format")
+          )
+          @provider = Entitlements::Backend::LDAP::Provider.new(ldap: @ldap)
+        end
+
+        # Pre-fetch the existing group membership in each OU.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing. (Populates cache.)
+        Contract C::None => C::Any
+        def prefetch
+          logger.debug "Pre-fetching group membership in #{group_name} (#{config['base']}) from LDAP"
+          provider.read_all(config["base"])
+        end
+
+        # Validation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing.
+        Contract C::None => C::Any
+        def validate
+          return unless config["mirror"]
+          Entitlements::Util::Mirror.validate_mirror!(group_name)
+        end
+
+        # Get count of changes.
+        #
+        # Takes no arguments.
+        #
+        # Returns an Integer.
+        Contract C::None => Integer
+        def change_count
+          actions.size + (ou_needs_to_be_created? ? 1 : 0)
+        end
+
+        # Calculation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing (populates @actions).
+        Contract C::None => C::Any
+        def calculate
+          if ou_needs_to_be_created?
+            logger.info "ADD #{config['base']}"
+          end
+
+          existing = provider.read_all(config["base"])
+          proposed = Entitlements::Data::Groups::Calculated.read_all(group_name, config)
+
+          # Calculate differences.
+          added = (proposed - existing)
+            .map { |i| Entitlements::Models::Action.new(i, nil, Entitlements::Data::Groups::Calculated.read(i), group_name) }
+          removed = (existing - proposed)
+            .map { |i| Entitlements::Models::Action.new(i, provider.read(i), nil, group_name) }
+          changed = (existing & proposed)
+            .reject { |i| provider.read(i).equals?(Entitlements::Data::Groups::Calculated.read(i)) }
+            .map { |i| Entitlements::Models::Action.new(i, provider.read(i), Entitlements::Data::Groups::Calculated.read(i), group_name) }
+
+          # Print the differences.
+          print_differences(key: group_name, added: added, removed: removed, changed: changed)
+
+          # Populate the actions
+          @actions = [added, removed, changed].flatten.compact
+        end
+
+        # Pre-apply routines. For the LDAP provider this creates the OU if it does not exist,
+        # and if "create_if_missing" has been set to true.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing.
+        Contract C::None => C::Any
+        def preapply
+          return unless ou_needs_to_be_created?
+
+          if ldap.upsert(dn: config["base"], attributes: {"objectClass" => "organizationalUnit"})
+            logger.debug "APPLY: Creating #{config['base']}"
+          else
+            logger.warn "DID NOT APPLY: Changes not needed to #{config['base']}"
+          end
+        end
+
+        # Apply changes.
+        #
+        # action - Action array.
+        #
+        # Returns nothing.
+        Contract Entitlements::Models::Action => C::Any
+        def apply(action)
+          if action.updated.nil?
+            logger.debug "APPLY: Deleting #{action.dn}"
+            ldap.delete(action.dn)
+          else
+            override = Entitlements::Util::Override.override_hash_from_plugin(action.config["plugin"], action.updated, ldap) || {}
+            if provider.upsert(action.updated, override)
+              logger.debug "APPLY: Upserting #{action.dn}"
+            else
+              logger.warn "DID NOT APPLY: Changes not needed to #{action.dn}"
+              logger.debug "Old: #{action.existing.inspect}"
+              logger.debug "New: #{action.updated.inspect}"
+            end
+          end
+        end
+
+        # Validate configuration options.
+        #
+        # key  - String with the name of the group.
+        # data - Hash with the configuration data.
+        #
+        # Returns nothing.
+        Contract String, C::HashOf[String => C::Any] => nil
+        def validate_config!(key, data)
+          spec = COMMON_GROUP_CONFIG.merge({
+            "base"               => { required: true, type: String },
+            "create_if_missing"  => { required: false, type: [FalseClass, TrueClass]},
+            "ldap_binddn"        => { required: true, type: String },
+            "ldap_bindpw"        => { required: true, type: String },
+            "ldap_ca_file"       => { required: false, type: String },
+            "disable_ssl_verification" => { required: false, type: [FalseClass, TrueClass] },
+            "ldap_uri"           => { required: true, type: String },
+            "plugin"             => { required: false, type: Hash },
+            "mirror"             => { required: false, type: String },
+            "person_dn_format"   => { required: true, type: String }
+          })
+          text = "Group #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(spec, data, text)
+        end
+
+        # ***********************************************************
+        # Private methods for this backend go below.
+        # ***********************************************************
+
+        # Determine if the OU needs to be created.
+        #
+        # Takes no arguments.
+        #
+        # Returns an Array of Strings (DNs).
+        Contract C::None => C::Bool
+        def ou_needs_to_be_created?
+          return false unless config["create_if_missing"]
+
+          @ou_needs_to_be_created ||= begin
+            if ldap.exists?(config["base"])
+              logger.debug "OU create_if_missing: #{config['base']} already exists"
+              :false
+            else
+              logger.debug "OU create_if_missing: #{config['base']} needs to be created"
+              :true
+            end
+          end
+
+          @ou_needs_to_be_created == :true
+        end
+
+        private
+
+        attr_reader :ldap, :provider
+      end
+    end
+  end
+end

data/lib/entitlements/backend/ldap/provider.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class LDAP
+      class Provider
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor.
+        #
+        # ldap       - Entitlements::Service::LDAP object
+        Contract C::KeywordArgs[
+          ldap: Entitlements::Service::LDAP,
+        ] => C::Any
+        def initialize(ldap:)
+          @ldap = ldap
+          @groups_in_ou_cache = {}
+
+          # Keep track of each LDAP group we have read so we do not end up re-reading
+          # certain referenced groups over and over again. This is at a program-wide level. If
+          # multiple backends have the same namespace this will probably break.
+          Entitlements.cache[:ldap_cache] ||= {}
+        end
+
+        # Read in a specific LDAP group and enumerate its members. Results are cached
+        # for future runs.
+        #
+        # dn - A String with the DN of the group to read
+        #
+        # Returns a Entitlements::Models::Group object.
+        Contract String => Entitlements::Models::Group
+        def read(dn)
+          Entitlements.cache[:ldap_cache][dn] ||= begin
+            Entitlements.logger.debug "Loading group #{dn}"
+
+            # Look up the group by its DN.
+            result = ldap.search(base: dn, scope: Net::LDAP::SearchScope_BaseObject)
+
+            # Ensure exactly one result found.
+            unless result.size == 1 && result.key?(dn)
+              raise Entitlements::Data::Groups::GroupNotFoundError, "No response from LDAP for dn=#{dn}"
+            end
+
+            Entitlements::Service::LDAP.entry_to_group(result[dn])
+          end
+        end
+
+        # Read in LDAP groups within the specified OU and enumerate their members.
+        # Results are cached for future runs so the read() method is faster.
+        #
+        # ou - A String with the base OU to search
+        #
+        # Returns a Set of Strings (DNs) of the groups in this OU.
+        Contract String => C::SetOf[String]
+        def read_all(ou)
+          @groups_in_ou_cache[ou] ||= begin
+            Entitlements.logger.debug "Loading all groups for #{ou}"
+
+            # Find all groups in the OU
+            raw = ldap.search(
+              base: ou,
+              filter: Net::LDAP::Filter.eq("cn", "*"),
+              scope: Net::LDAP::SearchScope_SingleLevel
+            )
+
+            # Construct a Set of DNs from the result, and also cache the content of the
+            # group to avoid a future lookup.
+            result = Set.new
+            raw.each do |dn, entry|
+              Entitlements.cache[:ldap_cache][dn] = Entitlements::Service::LDAP.entry_to_group(entry)
+              result.add dn
+            end
+
+            # Return that result
+            result
+          end
+        end
+
+        # Delete an LDAP group.
+        #
+        # dn - A String with the DN of the group to delete.
+        #
+        # Returns nothing.
+        Contract String => nil
+        def delete(dn)
+          return if ldap.delete(dn)
+          raise "Unable to delete LDAP group #{dn.inspect}!"
+        end
+
+        # Commit changes (upsert).
+        #
+        # group    - An Entitlements::Models::Group object.
+        # override - An optional Hash of additional parameters that override defaults.
+        #
+        # Returns true if a change was made, false if no change was made.
+        Contract Entitlements::Models::Group, C::Maybe[C::HashOf[String => C::Any]] => C::Bool
+        def upsert(group, override = {})
+          members = group.member_strings.map { |ms| ldap.person_dn_format.gsub("%KEY%", ms) }
+
+          attributes = {
+            "uniqueMember" => members,
+            "description"  => group.description || "",
+            "owner"        => [ldap.binddn],
+            "objectClass"  => ["groupOfUniqueNames"],
+            "cn"           => group.cn
+          }.merge(override)
+          override.each { |key, val| attributes.delete(key) if val.nil? }
+
+          # LDAP schema does not allow empty groups but does allow a group to be a member of itself.
+          # This gets around having to commit a dummy user in case an LDAP group is empty.
+          if group.member_strings.empty?
+            attributes["uniqueMember"] = [group.dn]
+          end
+
+          result = ldap.upsert(dn: group.dn, attributes: attributes)
+          return result if result == true
+          return false if result.nil?
+          raise "Unable to upsert LDAP group #{group.dn.inspect}!"
+        end
+
+        private
+
+        attr_reader :ldap
+      end
+    end
+  end
+end

data/lib/entitlements/backend/ldap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "ldap/controller"
+require_relative "ldap/provider"

data/lib/entitlements/backend/member_of/controller.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class MemberOf
+      class Controller < Entitlements::Backend::BaseController
+        # Controller priority and registration
+        def self.priority
+          20
+        end
+
+        register
+
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor. Generic constructor that takes a hash of configuration options.
+        #
+        # group_name - Name of the corresponding group in the entitlements configuration file.
+        # config     - Optionally, a Hash of configuration information (configuration is referenced if empty).
+        Contract String, C::Maybe[C::HashOf[String => C::Any]] => C::Any
+        def initialize(group_name, config = nil)
+          super
+
+          @ldap = Entitlements::Service::LDAP.new_with_cache(
+            addr: @config.fetch("ldap_uri"),
+            binddn: @config.fetch("ldap_binddn"),
+            bindpw: @config.fetch("ldap_bindpw"),
+            ca_file: @config.fetch("ldap_ca_file", ENV["LDAP_CACERT"]),
+            disable_ssl_verification: @config.fetch("ldap_disable_ssl_verification", false),
+            person_dn_format: @config.fetch("person_dn_format")
+          )
+        end
+
+        # Calculation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing (populates @actions).
+        Contract C::None => C::Any
+        def calculate
+          logger.debug "Calculating memberOf attributes for configured groups"
+
+          # We need to update people attributes for each group that is calculated and tagged with an
+          # attribute that needs to be updated.
+          cleared = Set.new
+
+          relevant_groups = Entitlements::Data::Groups::Calculated.all_groups.select do |ou_key, _|
+            config["ou"].include?(ou_key)
+          end
+
+          unless relevant_groups.any?
+            raise "memberOf emulator found no OUs matching: #{config['ou'].join(', ')}"
+          end
+
+          attribute = config["memberof_attribute"]
+
+          relevant_groups.each do |ou_key, data|
+            if cleared.add?(attribute)
+              Entitlements.cache[:people_obj].read.each do |uid, _person|
+                Entitlements.cache[:people_obj].read(uid)[attribute] = []
+              end
+            end
+
+            data[:groups].each do |group_dn, group_data|
+              group_data.member_strings.each do |member|
+                Entitlements.cache[:people_obj].read(member).add(attribute, group_dn)
+              end
+            end
+          end
+
+          # Now to populate the actions we have to see which persons have changed attributes.
+          @actions = Entitlements.cache[:people_obj].read
+            .reject { |_uid, person| person.attribute_changes.empty? }
+            .map do |person_uid, person|
+              print_differences(person)
+
+              Entitlements::Models::Action.new(
+                person_uid,
+                :none, # Convention, since entitlements doesn't (yet) create people
+                person,
+                group_name
+              )
+            end
+        end
+
+        # Apply changes.
+        #
+        # action - Action array.
+        #
+        # Returns nothing.
+        Contract Entitlements::Models::Action => C::Any
+        def apply(action)
+          person = action.updated
+          changes = person.attribute_changes
+          changes.each do |attrib, val|
+            if val.nil?
+              logger.debug "APPLY: Delete #{attrib} from #{person.uid}"
+            else
+              logger.debug "APPLY: Upsert #{attrib} to #{person.uid}"
+            end
+          end
+
+          person_dn = ldap.person_dn_format.gsub("%KEY%", person.uid)
+          unless ldap.modify(person_dn, changes)
+            logger.warn "DID NOT APPLY: Changes to #{person.uid} failed!"
+            raise "LDAP modify error on #{person_dn}!"
+          end
+        end
+
+        # Print difference array. The difference printer is a bit different for people rather than
+        # groups, since groups really only had a couple attributes of interest but were spread across
+        # multiple OUs, whereas people exist in one OU but have multiple attributes of interest.
+        #
+        # person - An Entitlements::Models::Person object.
+        #
+        # Returns nothing (this just prints to logger).
+        Contract Entitlements::Models::Person => C::Any
+        def print_differences(person)
+          changes = person.attribute_changes
+          return if changes.empty?
+
+          plural = changes.size == 1 ? "" : "s"
+          logger.info "Person #{person.uid} attribute change#{plural}:"
+
+          changes.sort.to_h.each do |attrib, val|
+            orig = person.original(attrib)
+            if orig.nil?
+              # Added attribute
+              if val.is_a?(Array)
+                logger.info ". ADD attribute #{attrib}:"
+                val.each { |item| logger.info ".   + #{item}" }
+              else
+                logger.info ". ADD attribute #{attrib}: #{val.inspect}"
+              end
+            elsif val.nil?
+              # Removed attribute
+              if orig.is_a?(Array)
+                word = orig.size == 1 ? "entry" : "entries"
+                logger.info ". REMOVE attribute #{attrib}: #{orig.size} #{word}"
+              else
+                logger.info ". REMOVE attribute #{attrib}: #{orig.inspect}"
+              end
+            else
+              # Modified attribute
+              logger.info ". MODIFY attribute #{attrib}:"
+              if val.is_a?(String) && orig.is_a?(String)
+                # Simple string change
+                logger.info ".  - #{orig.inspect}"
+                logger.info ".  + #{val.inspect}"
+              elsif val.is_a?(Array) && orig.is_a?(Array)
+                # Array difference
+                added = Set.new(val - orig)
+                removed = Set.new(orig - val)
+                combined = (added.to_a + removed.to_a)
+                combined.sort.each do |item|
+                  sign = added.member?(item) ? "+" : "-"
+                  logger.info ".  #{sign} #{item.inspect}"
+                end
+              else
+                # Data type mismatch is unexpected, so don't try to handle every possible case.
+                # This should only happen if LDAP schema changes. Just dump out the data structures.
+                logger.info ".  - (#{orig.class})"
+                logger.info ".  + #{val.inspect}"
+              end
+            end
+          end
+
+          # Return nil to satisfy contract
+          nil
+        end
+
+        private
+
+        attr_reader :ldap
+
+        # Validate configuration options.
+        #
+        # key  - String with the name of the group.
+        # data - Hash with the configuration data.
+        #
+        # Returns nothing.
+        # :nocov:
+        Contract String, C::HashOf[String => C::Any] => nil
+        def validate_config!(key, data)
+          spec = COMMON_GROUP_CONFIG.merge({
+            "ldap_binddn"        => { required: true, type: String },
+            "ldap_bindpw"        => { required: true, type: String },
+            "ldap_ca_file"       => { required: false, type: String },
+            "ldap_uri"           => { required: true, type: String },
+            "disable_ssl_verification" => { required: false, type: [FalseClass, TrueClass] },
+            "memberof_attribute" => { required: true, type: String },
+            "person_dn_format"   => { required: true, type: String },
+            "ou"                 => { required: true, type: Array }
+          })
+          text = "Group #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(spec, data, text)
+        end
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/entitlements/backend/member_of.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "member_of/controller"

data/lib/entitlements/cli.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "optimist"
+
+module Entitlements
+  class Cli
+    include ::Contracts::Core
+    C = ::Contracts
+
+    # This is the entrypoint to the CLI.
+    #
+    # argv - An Array with arguments, defaults to ARGV
+    #
+    # Returns an Integer with the exit status.
+    # :nocov:
+    Contract C::ArrayOf[C::Or[String, C::Bool, C::Num]] => Integer
+    def self.run
+      # Establish the logger object. Debugging is enabled or disabled based on options.
+      logger = Logger.new(STDERR)
+      logger.level = options[:debug] ? Logger::DEBUG : Logger::INFO
+      Entitlements.set_logger(logger)
+
+      # Set up configuration file.
+      Entitlements.config_file = options[:"config-file"]
+      Entitlements.validate_configuration_file!
+
+      # Support predictive updates based on the environment, but allow the --full option to
+      # suppress setting and using it.
+      if ENV["ENTITLEMENTS_PREDICTIVE_STATE_DIR"] && !@options[:full]
+        Entitlements::Data::Groups::Cached.load_caches(ENV["ENTITLEMENTS_PREDICTIVE_STATE_DIR"])
+      end
+
+      # Calculate differences.
+      actions = Entitlements.calculate
+
+      # No-op mode exits here.
+      if @options[:noop]
+        logger.info "No-op mode is set. Would make #{Entitlements.cache[:change_count]} change(s)."
+        return 0
+      end
+
+      # No changes?
+      if actions.empty?
+        logger.info "No changes to be made. You're all set, friend! :sparkles:"
+        return 0
+      end
+
+      # Execute the changes. This raises if it fails to apply a change or if auditors fail.
+      Entitlements.execute(actions: actions)
+
+      # Done.
+      logger.info "Successfully applied #{Entitlements.cache[:change_count]} change(s)!"
+      0
+    end
+    # :nocov:
+
+    # Method access to options. `attr_reader` doesn't work here since it's a class variable.
+    #
+    # Takes no arguments.
+    #
+    # Returns a Hash.
+    # :nocov:
+    Contract C::None => C::HashOf[Symbol => C::Any]
+    def self.options
+      @options ||= begin
+        o = initialize_options
+        validate_options!(o)
+        o
+      end
+    end
+    # :nocov:
+
+    # Parse the options given by ARGV and return a hash.
+    #
+    # Takes no arguments.
+    #
+    # Returns a Hash.
+    # :nocov:
+    Contract C::None => C::HashOf[Symbol => C::Any]
+    def self.initialize_options
+      Optimist.options do
+        banner <<-EOS
+        Configure authentication providers to look like the configuration declared in the files.
+
+        Usage:
+
+        $ deploy-entitlements --dir /path/to/configurations
+        .
+      EOS
+        opt :"config-file",
+            "Configuration file for application",
+            type: :string,
+            default: File.expand_path("../../config/entitlements/config.yaml", File.dirname(__FILE__))
+        opt :noop,
+            "no-op mode (do not actually apply configurations)",
+            type: :boolean, default: false
+        opt :full,
+            "full deployment (skip predictive updates, if configured)",
+            type: :boolean, default: false
+        opt :debug,
+            "debug messages enabled",
+            type: :boolean, default: false
+      end
+    end
+    # :nocov:
+
+    # Validate command line options.
+    #
+    # options - Hash of options.
+    #
+    # Returns nothing.
+    # :nocov:
+    Contract C::HashOf[Symbol => C::Any] => nil
+    def self.validate_options!(options)
+      unless options[:"config-file"].is_a?(String) && File.file?(options[:"config-file"])
+        raise ArgumentError, "Expected --config-file to be a valid file!"
+      end
+    end
+    # :nocov:
+  end
+end