cul-ldap 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f3aec72c508a6c195d0ee5912c1bad2c4623d528
-  data.tar.gz: dbd019c07e1582a28879d0e97fb1e2e4dc5bef86
+SHA256:
+  metadata.gz: b3a6bd5501342e78f88d632e9595c97e1b32e54f1b3e121d9a551b2ebe9980e1
+  data.tar.gz: 47edc79408d68f64230c561b9239d8817361ff2c851070d2d2c5f3b93a2d434d
 SHA512:
-  metadata.gz: 077ae779ae3cc4fe2495bd20df9aee09812fee27e856902a218e975bc4c45517c48ad43da8a51b6bf7d4aed3d4e33374777dbed9f71b7275f5ad900699170bb6
-  data.tar.gz: 41ee7ddaecbcb9b90007a5161fd2baa5852fc06b8eb3d9760c71c5f93525bb072d2939faa7ee0c34527cd1be654a1ac90b8f6d8d4e1e406f7232ec2e249633f2
+  metadata.gz: 81f14fb2b8752653c5d2c986178f890c53e1bab3c8aefa742e7a1b646f7196e4bedc359d74f0eb371cbbfd3c9092007f57e0f22ed4a83df72b9755bbf7bf3c71
+  data.tar.gz: 648ac9a4415823f2d43f991a0f77a8c30fe7046ecf6c123821a4ef60817b02ce3a08c32e42a9c8c3ca300026543f7e2e667e648c6a245d0ff35d1fe1e25437f2

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ '*' ]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.2.9', '3.3.9']
+    env:
+      NOKOGIRI_USE_SYSTEM_LIBRARIES: true
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Add --no-document option to .gemrc file to speed up bundle install
+        run: "echo 'gem: --no-document' > ~/.gemrc"
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run CI task
+        run: bundle exec rspec spec

data/.ruby-version

@@ -0,0 +1 @@
+3.3.8

data/README.md

@@ -20,13 +20,53 @@ Or install it yourself as:
 
 ## Usage
 
+Users must provide a full configuration including the cul LDAP server host, port, and auth credentials. This can be done by passing a hash object to the class initializer, or by including a `cul_ldap.yml` file.
+
+The configuration options here are the same ones supported by the Net::LDAP#initialize method.  Cul::LDAP is built on top of Net::LDAP. [See the Net::LDAP#initialize documentation here](https://www.rubydoc.info/gems/ruby-net-ldap/Net/LDAP#initialize-instance_method).
+
+
+Since this file will contain a username and password, remember to .gitignore this file in your repository.
+
+```
+host: 'servername'                   # Required.
+port: 636                                   # Required. Standard port for simple-tls encrypted ldap connections.
+encryption: simple_tls
+auth:                                       # Required (all fields).
+    method: simple
+    username: "USERNAME"
+    password: "PASSWORD"
+```
+
+**❗You can use the information in [this confluence page](https://columbiauniversitylibraries.atlassian.net/wiki/spaces/USGSERVICES/pages/10947594/LDAP+Lookup+including+affiliations+via+privileged+lookup#Using-a-secure-%E2%80%9Cldaps%3A%2F%2F%E2%80%9D-connection-(recommended)%3A) to fill out the username and password credentials here.❗**
+
+### Standalone Gem Usage
+
 ```
 require 'cul/ldap'
-ldap = Cul::LDAP.new
+ldap = Cul::LDAP.new                        # Assuming you have a proper cul_ldap.yml file
 entry = ldap.find_by_uni("abc123")
 entry = ldap.find_by_name("Doe, Jane")
 ```
 
+### Rails app usage
+
+If you're using cul-ldap in a Rails app, you can create a configuration file at `config/cul_ldap.yml` that looks the one at the top of this section.  It will be read automatically.
+
+## Common Errors Troubleshooting
+Cul::LDAP will raise an error if any of the expected configuration options are missing when an instance is initialized. It only validates that they are present, nothing else; if there is a misconfigured option or a different error, an underlying call to the Net::LDAP gem will likely be the one to raise it.
+
+#### Cul::LDAP errors:
+- **InvalidOptionError**: You are missing a configuration option (in cul_ldap.yml or in the option hash passed to new)
+- **AuthError: Cul::LDAP**: was able to make the request to the LDAP service, but received a response indicating invalid credentials (user/pass). The exact error will be printed.
+    - code 49: bad username
+    - code 50: bad username and password
+    - code 53: bad password
+
+#### Other common error cases:
+- **Net::LDAP:Error: Operation timed out**: The request never received a response. Could be a network error.
+- **Net::LDAP::Error: getaddrinfo**: invalid host url
+- **Errno::ECONNREFUSED: Connection refused**: invalid host url - usually when it is an empty string (in which case Net::LDAP will set host to 0.0.0.0)
+- **Errno::ECONNRESET: Connection reset by peer**: unknown/invalid `encryption` option was given.
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/cul-ldap.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "net-ldap", '~> 0.16'
 
-  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-its", "~> 1.2"

data/lib/cul/ldap/exceptions.rb

@@ -0,0 +1,10 @@
+# lib/cul/ldap/exceptions.rb
+module Cul
+  class LDAP < Net::LDAP
+    module Exceptions
+      class Error < StandardError; end
+      class AuthError < Error; end
+      class InvalidOptionError < Error; end
+    end
+  end
+end

data/lib/cul/ldap.rb

@@ -2,20 +2,24 @@ require "net/ldap"
 require "yaml"
 
 require "cul/ldap/version"
+require "cul/ldap/exceptions"
 require "cul/ldap/entry"
 
 module Cul
   class LDAP < Net::LDAP
     CONFIG_FILENAME = 'cul_ldap.yml'
     CONFIG_DEFAULTS = {
-      host: 'ldap.columbia.edu',
-      port: '636',
       encryption: {
         method: :simple_tls,
         tls_options: OpenSSL::SSL::SSLContext::DEFAULT_PARAMS
-      }
+      },
     }.freeze
+    REQUIRED_OPTS = [ :host, :port, :auth ].freeze
+    REQUIRED_AUTH_OPTS = [ :method, :username, :password ].freeze
 
+    # Create a new Cul::LDAP object
+    # @param options [Hash] A set of Net::LDAP constructor options.  See Net::LDAP#initialize for
+    #                       the full set of supported options.
     def initialize(options = {})
       super(build_config(options)) # All keys have to be symbols.
     end
@@ -27,7 +31,7 @@ module Cul
     # @return [nil] if record for uni could not be found, or more than one record was found
     def find_by_uni(uni)
       entries = search(base: "ou=People,o=Columbia University, c=US", filter: Net::LDAP::Filter.eq("uid", uni))
-      (entries.count == 1) ? entries.first : nil
+      (entries && entries.count == 1) ? entries.first : nil
     end
 
     # LDAP lookup based on name.
@@ -46,47 +50,73 @@ module Cul
     # Wrapper around Net::LDAP#search, converts Net::LDAP::Entry objects to
     # Cul::LDAP::Entry objects.
     def search(args = {})
-      super(args).tap do |result|
+      search_res = super(args).tap do |result|
         if result.is_a?(Array)
           result.map!{ |e| Cul::LDAP::Entry.new(e) }
         end
       end
+
+      # If a username and password were provided, the query will return a result no matter what. Check if auth failed:
+      check_operation_result
+
+      search_res
+    end
+
+    # Checks for some common error cases that the user can easily remidy (all auth errors)
+    # For all LDAP operation result codes and their meanings: https://ldap.com/ldap-result-code-reference/
+    def check_operation_result
+      operation_result = get_operation_result
+      if [49, 50, 53].include? operation_result.code
+        raise Exceptions::AuthError, "LDAP Error: (code #{operation_result.code}) '#{operation_result.error_message}' Make sure you provide a proper username and password for authentication."
+      end
     end
 
     private
 
     def build_config(options)
-      config = CONFIG_DEFAULTS.merge(options)
-      credentials = config.fetch(:auth, nil)
-      credentials = nil if !credentials.nil? && credentials.empty?
-
-      # If rails app fetch credentials using rails code, otherwise read from
-      # cul_ldap.yml if credentials are nil.
-      if credentials.nil?
-        credentials = rails_credentials || credentials_from_file
-        credentials = nil if !credentials.nil? && credentials.empty?
-      end
+      config = CONFIG_DEFAULTS.dup
 
-      unless credentials.nil?
-        credentials = credentials.map { |k, v| [k.to_sym, v] }.to_h
-        credentials[:method] = :simple unless credentials.key?(:method)
-      end
+      # If a cul_ldap.yml config file is found, merge in those settings first
+      options_from_config_file = options_from_rails_config || options_from_file_config
+
+      config = config.merge(options_from_config_file) if options_from_config_file
+
+      # Then merge in any settings supplies by options
+      config = config.merge(options) if options
+
+      # If auth method has been supplied as a string, convert it to a symbol
+      config[:auth][:method] = :simple if config[:auth] && config.dig(:auth, :method) == 'simple'
+      
+      # If any required information is missing from the options, raise an error
+      validate_config(config)
 
-      config[:auth] = credentials
       config
     end
 
-    def credentials_from_file
+    def options_from_file_config
       (File.exist?(CONFIG_FILENAME)) ? YAML.load_file(CONFIG_FILENAME) : nil
     end
 
-    def rails_credentials
+    def options_from_rails_config
       if defined?(Rails.application.config_for) && File.exist?(File.join(Rails.root, 'config', CONFIG_FILENAME))
-        raise "Missing cul-ldap credentials in config/#{CONFIG_FILENAME}" if Rails.application.config_for(:cul_ldap).empty?
+        if Rails.application.config_for(CONFIG_FILENAME.gsub(/.yml$/, '').to_sym).empty?
+          raise "Missing cul-ldap configuration in config/#{CONFIG_FILENAME}"
+        end
         Rails.application.config_for(:cul_ldap)
       else
         nil
       end
     end
+
+    def validate_config(config)
+      REQUIRED_OPTS.each do |opt|
+        raise Exceptions::InvalidOptionError, "Missing required cul-ldap configuration option: #{opt}" unless config.has_key? opt
+      end
+      
+      # Validate nested auth options
+      REQUIRED_AUTH_OPTS.each do |auth_opt|
+        raise Exceptions::InvalidOptionError, "Missing required cul-ldap configuration option: :auth=> { #{auth_opt} }" unless config[:auth].has_key? auth_opt
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cul-ldap
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Carla Galarza
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2017-11-16 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ldap
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -80,16 +80,17 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-description: 
+description:
 email:
 - cmg2228@columbia.edu
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
+- ".ruby-version"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -100,12 +101,13 @@ files:
 - cul-ldap.gemspec
 - lib/cul/ldap.rb
 - lib/cul/ldap/entry.rb
+- lib/cul/ldap/exceptions.rb
 - lib/cul/ldap/version.rb
 homepage: https://github.com/cul/cul-ldap
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,9 +122,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Common queries of CU's LDAP server
 test_files: []

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.3
-before_install: gem install bundler -v 1.13.7