els_token 1.0.1 → 1.2.0

data/README.rdoc

@@ -4,8 +4,16 @@ A simple library for interfacing with forgeRock OpenAM REST Interface.
 
 Still pretty much in development but kind of workable.
 
+== Usage
+
+include ElsToken into your class or module
+
 change log
 
+1.2.0
+  Removed Rails dependency. 
+  Cleaned up instructions - getting ready to bare all :)
+
 1.0.1
   Removed AOLMemberCA certificate as it was mostly pointless
   SSL without verification is used as default
@@ -15,5 +23,7 @@ change log
   Initial release :)
 
 = TODO
-Refactor to remove explicit Rack based session interrogation (drop rails dependency).
-Refactor and fix tests
+With the correct level of priviledge it's possible to perform granular LDAP searches against the OpenAM REST interface. 
+By Default one can only pull identity details for a provided token but it might be nice to search against other attributes.
+
+Erm some tests might be nice :)

data/lib/els_token.rb

@@ -1,5 +1,5 @@
 require 'els_token/module_inheritable_attributes'
-require 'els_token/els_user'
+require 'els_token/els_identity'
 require 'net/http'
 require 'uri'
 
@@ -14,142 +14,238 @@ module ElsToken
 
   module ClassMethods
     
-    # els_config expects a nice hash telling
-    # it if it will have a fake user (handy for dev)
-    # and the url of the openAM REST API.
-    # { faker => { user => 'username',
-    #             :environments => ['dev','test'] },
-    #   uri => 'https://openam.url' }
+    # els_config expects a hash with environmental
+    # parameters including the els gateway and expected
+    # cookie name (when used in a Rack environment)
+    # An optional fake identity can be supplied which
+    # will override any active authentication. This can
+    # be especially useful during automated testing.
+    # The fake ID can take any of the ElsIdentity properties
+    #
+    # A typical setup would initialize a options hash to
+    # include the following
+    #
+    #  faker:
+    #    name: neilcuk
+    #    employee_number: 09095
+    #    roles:
+    #      - App Admins
+    #      - Domain Users
+    #  uri: https://els-admin.corp.aol.com:443/opensso/identity
+    #  cookie: iPlanetDirectoryPro
+    #  cert: /path/to/certs
+    #
+    # Do not include the faker object in your production
+    # configuration :)
+    #
+    # only the uri option is required if you are not worried
+    # about cookies and do not plan on using them. If you want
+    # to include a certificate for interacting with the ELS
+    # server then you can specify a file or directory to find
+    # the cert. By default Certificate validiation is off!
     #
-    #   class MyController
-    #     include ElsToken
-    #     els_config options_hash
-    #   end
     def els_config(options = {})
-      @els_options = options
+      unless options["uri"]
+        raise "I need a uri to authenticate against" unless options["faker"]
+      end
+      els_options.merge!(options)
     end
-  
-  end
+    
+    def els_uri(uri = nil)
+      return els_options["uri"] unless uri
+      els_options["uri"] = uri
+    end
+    
+    def els_cookie_name(cookie_name = nil)
+      return els_options["cookie"] unless cookie_name
+      els_options["cookie_name"] = uri
+    end
+    
+    def els_faker(faker = {})
+      els_options["faker"] = faker
+    end
+    
+    def els_options
+      @els_options
+    end
+    
+    # authenticates against ELS and returns the user token
+    def authenticate(username,password,options={})
 
-  # authenticates against ELS and returns the user token
-  def authenticate(username,password)
+      begin
+        response = els_http_request("/authenticate",
+          "uri=realm=aolcorporate&username=#{username}&password=#{password}",
+          options)
+        if response.code.eql? "200"
+          # return the token
+          response.body.chomp.sub(/token\.id=/,"")
+        else
+          raise response.error! 
+        end
+      rescue Net::HTTPExceptions => e1
+        raise e1, "token retrieval failed for #{username}"
+      rescue Exception => e
+        # Do not expect these. Wrapping the exception so
+        # as to not reveal the passed in password
+        puts e.backtrace
+        raise e, "unable to fetch token for #{username}"
+      end
+    end
 
-    begin
-      response = els_http_request("/authenticate","uri=realm=aolcorporate&username=#{username}&password=#{password}")
+    # passes a token to els to see if it is still valid
+    def is_token_valid?(token, options={})
+      response = els_http_request("/isTokenValid","tokenid=#{token}",options)
       if response.code.eql? "200"
-        # return the token
-        response.body.chomp.sub(/token\.id=/,"")
+        true
       else
-        raise response.error! 
+        false
       end
-    rescue Net::HTTPExceptions => e1
-      raise e1, "token retrieval failed for #{username}"
-    rescue Exception => e
-      # Do not expect these. Wrapping the exception so
-      # as to not reveal the passed in password
-      raise e, "unable to fetch token for #{username}"
     end
-  end
-  
-  def is_token_valid?(token)
-    response = els_http_request("/isTokenValid","tokenid=#{token}")
-    if response.code.eql? "200"
-      true
-    else
-      false
+
+
+    # obtain a friendly ElsIdentity object by passing
+    # in a token
+    def get_token_identity(token,options={})
+      ElsIdentity.new(get_raw_token_identity(token,options))
     end
-  end
 
-  #extract the token from the rack cookie
-  def is_cookie_token_valid?
-    return true if fake_it?
-    token = cookies[self.class.els_options['cookie']]
-    if token.nil? || !is_token_valid?(token)
-      false
-    else
-      true
+    # get_token_identity wraps the ELS identity response
+    # in a nice, friendly, object. If you don't like that object
+    # or need the raw data, then use this.
+    def get_raw_token_identity(token,options={})
+      response = els_http_request("/attributes","subjectid=#{token}",options)
+      if response.code.eql? "200"
+        response.body
+      else
+        response.error!
+      end
+    end
+
+    # When used inside a rack environment
+    # will attempt to retrieve the user token
+    # from the session cookie and return a full
+    # identity. This is pretty much a convenience
+    # method that chains is_cookie_token_valid?
+    # then get_token_identity
+    def get_identity(token, options ={})
+      return fake_id if fake_it?
+      begin
+        if is_token_valid?(token, options)
+          get_token_identity(token, options)
+        else
+          raise "token is invalid"
+        end
+      rescue Exception => e
+        raise e
+      end
+    end 
+
+    private
+
+    def els_http_request(url_base_extension, query_string, options)
+      options = els_options.dup.merge(options)
+      uri = URI.parse(options['uri'] + url_base_extension)
+      uri.query=query_string
+      http = Net::HTTP.new(uri.host,uri.port)
+      http.use_ssl = true
+
+      # Use a known certificate if supplied
+      if rootca = options[:cert]
+        if File.exist? rootca
+          http.ca_file = rootca
+        elsif Dir.exist? rootca
+          http.ca.path = rootca
+        else
+          raise "${rootca} cannot be found"
+        end
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.verify_depth = 5
+      else
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+
+      http.request(request)
+    end
+
+    def fake_it?
+      els_options.has_key? 'faker'
     end
+
+    def fake_id
+      unless @fake_id
+        id = ElsIdentity.new
+        id.instance_variable_set("@roles",els_options['faker']['roles'])
+        id.instance_variable_set("@mail",els_options['faker']['mail'])
+        id.instance_variable_set("@last_name",els_options['faker']['last_name'])
+        id.instance_variable_set("@first_name",els_options['faker']['first_name'])
+        id.instance_variable_set("@uac",els_options['faker']['uac'])
+        id.instance_variable_set("@dn",els_options['faker']['dn'])
+        id.instance_variable_set("@common_name",els_options['faker']['common_name'])
+        id.instance_variable_set("@employee_number",els_options['faker']['employee_number'])
+        id.instance_variable_set("@display_name",els_options['faker']['display_name'])
+        id.instance_variable_set("@token_id",els_options['faker']['token_id'])
+        id.instance_variable_set("@user_status",els_options['faker']['user_status'])
+        @fake_id = id
+      end
+      @fake_id
+    end  
   end
 
-  # obtain a full ElsIdentity object
+  # Instance methods
+  
+  class Runner
+    include ElsToken
+  end
+  
+  def authenticate(username,password)
+    Runner.authenticate(username,password,self.class.els_options)
+  end
+  
+  def is_token_valid?(token)
+    Runner.is_token_valid?(token,self.class.els_options)
+  end
+  
   def get_token_identity(token)
-    response = els_http_request("/attributes","subjectid=#{token}")
-    if response.code.eql? "200"
-      ElsIdentity.new(response.body)
-    else
-      response.error!
-    end
+    Runner.get_token_identity(token,self.class.els_options)
+  end
+  
+  def get_raw_token_identity(token)
+    Runner.get_raw_token_identity(token,self.class.els_options)
   end
   
-  # When used inside a rack environment
-  # will attempt to retrieve the user token
-  # from the session cookie and return a full
-  # identity
   def get_identity
-    return fake_id if fake_it?
-    begin
-      if is_cookie_token_valid?
-        get_token_identity cookies[self.class.els_options['cookie']]
-      else
-        raise "token is invalid"
-      end
-    rescue Exception => e
-      raise e
-    end
-  end 
-      
-  def method_missing(m, *args, &block)
-    puts "Drop the crack pipe - There is no method called #{m}"
+    token = cookies[self.class.els_options['cookie']]
+    Runner.get_identity(token,self.class.els_options)
   end
-
-  private
   
-  def els_http_request(url_base_extension, query_string)
-    uri = URI.parse(self.class.els_options['uri'] + url_base_extension)
-    uri.query=query_string
-    http = Net::HTTP.new(uri.host,uri.port)
-    http.use_ssl = true
-    
-    # Use a known certificate if supplied
-    if rootca = self.class.els_options[:cert]
-      if File.exist? rootca
-        http.ca_file = rootca
-      elsif Dir.exist? rootca
-        http.ca.path = rootca
-      else
-        raise "${rootca} cannot be found"
-      end
-      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-      http.verify_depth = 5
+  # extract the token from a cookie
+  # This method expects a hash called cookies
+  # to be present. It will look for a cookie with
+  # the key of the cookie value in the config hash
+  def is_cookie_token_valid?
+    return true if self.class.els_options.has_key? 'faker'
+    raise "No cookies instance found" if cookies.nil?
+    token = cookies[self.class.els_options['cookie']]
+    if token.nil? || !Runner.is_token_valid?(token,self.class.els_options)
+      false
     else
-      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      true
     end
-    
-    request = Net::HTTP::Get.new(uri.request_uri)
-
-    http.request(request)
   end
   
-  def fake_it?
-    self.class.els_options.has_key? 'faker'
+  # How about a few class methods of our own?
+  
+  def self.authenticate(username,password,options)
+    Runner.authenticate(username,password,options)
   end
-
-  def fake_id
-    unless @fake_id
-      id = ElsIdentity.new
-      id.instance_variable_set("@roles",self.class.els_options['faker']['roles'])
-      id.instance_variable_set("@mail",self.class.els_options['faker']['mail'])
-      id.instance_variable_set("@last_name",self.class.els_options['faker']['last_name'])
-      id.instance_variable_set("@first_name",self.class.els_options['faker']['first_name'])
-      id.instance_variable_set("@uac",self.class.els_options['faker']['uac'])
-      id.instance_variable_set("@dn",self.class.els_options['faker']['dn'])
-      id.instance_variable_set("@common_name",self.class.els_options['faker']['common_name'])
-      id.instance_variable_set("@employee_number",self.class.els_options['faker']['employee_number'])
-      id.instance_variable_set("@display_name",self.class.els_options['faker']['display_name'])
-      id.instance_variable_set("@token_id",self.class.els_options['faker']['token_id'])
-      @fake_id = id
-    end
-    @fake_id
+  
+  def self.is_token_valid?(token, options)
+    Runner.is_token_valid?(token,options)
+  end
+  
+  def self.get_identity(token, options)
+    Runner.get_identity(token,options)
   end
-
 end

data/lib/els_token/{els_user.rb → els_identity.rb}

@@ -4,12 +4,19 @@ module ElsToken
   
   class ElsIdentity
     attr_reader :roles, :mail, :last_name, :first_name, :uac, :dn, :common_name
-    attr_reader :employee_number, :display_name, :name, :token_id
-
-    def cdid
-      @name
+    attr_reader :employee_number, :display_name, :name, :token_id, :user_status
+
+    alias :cdid :name
+    
+    # The Active Directory User Account Control contains lots of
+    # interesting info about the user account state. This method
+    # does a very simple check to see if the account is enabled
+    # and return either "enabled" or "disabled". There are many
+    # other states but I don't use them
+    def friendly_uac
+      @friendly_uac ||= (@uac.to_i & 2 == 0) ? "enabled" : "disabled"
     end
-
+    
     def has_role?(role)
       @roles.include? role
     end
@@ -43,7 +50,6 @@ module ElsToken
 
               when line =~ /name=useraccountcontrol/
                 self_set :uac
-                @uac = (uac.to_i & 2 == 0) ? "enabled" : "disabled"
 
               when line =~ /name=givenname/
                 self_set :first_name
@@ -62,6 +68,9 @@ module ElsToken
 
               when line =~ /name=displayname/
                 self_set :display_name
+                
+              when line =~ /name=inetUserStatus/
+                self_set :user_status
             end
           end
         rescue 

data/lib/els_token/version.rb

@@ -1,3 +1,3 @@
 module ElsToken
-  VERSION = "1.0.1"
+  VERSION = "1.2.0"
 end

data/test/dummy/Gemfile

@@ -1,3 +1,12 @@
 source "http://rubygems.org"
 
 gem 'rails', '~> 3.2.0'
+
+group :development do
+  gem 'sqlite3'
+end
+
+gem 'coffee-rails', '~> 3.2.1'
+gem 'jquery-rails'
+# See https://github.com/sstephenson/execjs#readme for more supported runtimes
+#gem 'therubyracer'

data/test/dummy/Gemfile.lock

@@ -30,10 +30,22 @@ GEM
       multi_json (~> 1.0)
     arel (3.0.2)
     builder (3.0.3)
+    coffee-rails (3.2.2)
+      coffee-script (>= 2.2.0)
+      railties (~> 3.2.0)
+    coffee-script (2.2.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.3.3)
     erubis (2.7.0)
+    execjs (1.4.0)
+      multi_json (~> 1.0)
     hike (1.2.1)
     i18n (0.6.1)
     journey (1.0.4)
+    jquery-rails (2.1.3)
+      railties (>= 3.1.0, < 5.0)
+      thor (~> 0.14)
     json (1.7.5)
     mail (2.4.4)
       i18n (>= 0.4.0)
@@ -47,7 +59,7 @@ GEM
       rack (>= 0.4)
     rack-ssl (1.3.2)
       rack
-    rack-test (0.6.1)
+    rack-test (0.6.2)
       rack (>= 1.0)
     rails (3.2.8)
       actionmailer (= 3.2.8)
@@ -71,6 +83,7 @@ GEM
       hike (~> 1.2)
       rack (~> 1.0)
       tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
     thor (0.16.0)
     tilt (1.3.3)
     treetop (1.4.10)
@@ -82,4 +95,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  coffee-rails (~> 3.2.1)
+  jquery-rails
   rails (~> 3.2.0)
+  sqlite3