rs_user_policy 0.0.4 → 0.0.5

data/README.rdoc

@@ -1,12 +1,32 @@
 = rs_user_policy
 
-A useful tool for managing many users across many child accounts in a RightScale Enterprise Edition
+A useful tool for managing many users across many RightScale accounts.
 
 While the tests are not exhaustive, the current build status is..
 {<img src="https://travis-ci.org/rgeyer/rs_user_policy.png" />}[https://travis-ci.org/rgeyer/rs_user_policy]
 
 == Usage
 
+You must pass in your RightScale authentication information, and a policy file.  You can also specify one or many RightScale accounts using the --rs-acct-num or -a parameters.  If an account that you specify is an Enterprise Master account, all Enterprise Children accounts will automatically be included.
+
+  Options:
+            --rs-email, -r <s>:   You RightScale User Email Address
+             --rs-pass, -s <s>:   Your RightScale User Password
+         --rs-acct-num, -a <s>:   A RightScale Enterprise Master Account ID
+              --policy, -p <s>:   The path to a JSON file containing the role to permissions policy to enforce
+    --user-assignments, -u <s>:   The path to a JSON file containing email address => role pairs for user assignments
+                 --dry-run, -d:   A flag indicating that no changes should be made, only the user_assignments.json should be evaluated (or created) and
+                                  the audit_log.json produced
+                    --help, -h:   Show this message
+
+Example (One account)
+  rs_user_policy -r "foo@bar.baz" -s "password" -p policy.json -u user_assignments.json -a 12345
+
+Example (Multiple accounts)
+  rs_user_policy -r "foo@bar.baz" -s "password" -p policy.json -u user_assignments.json -a 12345 -a 67891 -a 11121
+
+=== Managing existing user permissions
+
 The binary contained in this gem accepts two files as inputs to determine it's behavior.  The first, is a policy JSON file which specifies the permissions to be applied to users.
 
 Policy JSON should be in the following format
@@ -73,6 +93,24 @@ user2 will be assigned observer and lite_user rights on account 12345, and obser
 
 Got that?  Cool!
 
+=== Creating new users
+
+This tool can also be used to create net-new users who have either never used RightScale, or who have never been associated with one of the accounts targetted by the tool.  For those type of users some additional parameters are necessary in the user_assignments source file.  The minimum set of properties is ["roles", "company", "first_name", "last_name", "phone"]
+
+  {
+    "net@new.user": {
+      "roles": ["team1"],
+      "company": "RightScale",
+      "first_name": "Net",
+      "last_name": "New",
+      "phone": "9999999999"
+    }
+  }
+
+The order of the additional parameters does not matter.  The properties list can also include "identity_provider_href" and "principal_uid" or "password" to specify the users authentication details.  If no authentication details are supplied a random secure password will be generated, and written to the output user_assignments.json file.
+
+If a user with the specified email already exists, but that user does not have any permissions in the account(s) targetted by the tool, these additional properties are still required, but will be ignored.
+
 == Output
 
 When the script is run, it will produce two JSON files as output.
@@ -83,11 +121,11 @@ Second is the user_assignments-<timestamp>.json file.  This will be a combinatio
 
 == TODO
 
-* Allow users to be added who are not already invited to any RS parent or child account
 * In absence of a policy.json, create a new policy.json with base roles for each account discovered (I.E. Admin, Observer, Designer, etc)
 * Perhaps allow a role to inherit from another, or be a concatenation of several?
 * Handle the race condition where permissions have been deleted in the correct order, but API still throws 422 removing "observer" because the changes have not become consistent server side
   * HTTP Code: 422, Response body: A user must have the observer role. (RightApi::Exceptions::ApiException)
+  * 2012/12/18 - This does not appear to be an issue any longer.  Or at least I am not encountering it anymore.  Perhaps this was a transient issue?
 
 == Copyright
 

data/bin/rs_user_policy

@@ -24,6 +24,7 @@
 require 'trollop'
 require 'right_api_client'
 require 'logger'
+require 'digest/md5'
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'rs_user_policy'))
 
 opts = Trollop::options do
@@ -31,7 +32,7 @@ opts = Trollop::options do
 
   opt :rs_email, "You RightScale User Email Address", :type => :string, :required => true
   opt :rs_pass, "Your RightScale User Password", :type => :string, :required => true
-  opt :rs_acct_num, "A RightScale Enterprise Master Account ID", :type => :string, :required => true
+  opt :rs_acct_num, "A RightScale Enterprise Master Account ID", :type => :string, :multi => true, :required => true
   opt :policy, "The path to a JSON file containing the role to permissions policy to enforce", :type => :string, :required => true
   opt :user_assignments, "The path to a JSON file containing email address => role pairs for user assignments", :type => :string
   opt :dry_run, "A flag indicating that no changes should be made, only the user_assignments.json should be evaluated (or created) and the audit_log.json produced"
@@ -39,8 +40,6 @@ end
 
 log = Logger.new(STDOUT)
 timestamp = Time::now.to_i
-deleted_users = []
-accounts = []
 
 if opts[:dry_run]
   log.info("The dry_run option was selected, no action will be taken, but the user_assignments output and audit_log files will be written reflecting the actions which would have been taken")
@@ -66,40 +65,56 @@ end
 
 user_collection = RsUserPolicy::UserCollection.new
 
-client = RightApi::Client.new(:email => opts[:rs_email], :password => opts[:rs_pass], :account_id => opts[:rs_acct_num])
-master_account = client.accounts(:id => opts[:rs_acct_num]).show()
-user_collection.add_users(client.users.index)
-user_collection.add_permissions(master_account.href, client.permissions.index)
+multi_client = RsUserPolicy::RightApi::MultiClient.new(opts[:rs_email], opts[:rs_pass], opts[:rs_acct_num])
 
-accounts << {:client => client, :href => master_account.href, :name => master_account.name}
+# Iterate over all accounts once to discover users and their permissions
+multi_client.each do |account_id, account|
+  child_client = account[:client]
+  child_account = child_client.accounts(:id => account_id).show()
+  account_href = child_account.href
+  users_hash = Hash[child_client.users.index.map{|user| [user.href, user.email] }]
+  user_collection.add_users(users_hash)
+  user_collection.add_permissions(account_href, child_client.permissions.index)
+end
 
-log.info("Operating on the Enterprise Master Account #{master_account.name}")
+# Populate the user_assignments with hrefs
+user_collection.users.each do |user|
+  user_assignments[user.email]["href"] = user.href
+end
 
-begin
-  client.child_accounts.index.each do |child|
-    child_client = RightApi::Client.new(:email => opts[:rs_email], :password => opts[:rs_pass], :account_id => RsUserPolicy::Utilities.id_from_href(child.href))
-    accounts << {:client => child_client, :href => child.href, :name => child.name}
+net_new_users = user_assignments.list - user_collection.users.map{|u| u.email }
 
-    user_collection.add_users(child_client.users.index)
-    user_collection.add_permissions(child.href, child_client.permissions.index)
+net_new_users.each do |net_new_user_email|
+  client = multi_client[opts[:rs_acct_num].first()][:client]
+  user_create_params = user_assignments[net_new_user_email]
+  user_create_params = {:email => net_new_user_email}.merge(user_create_params)
+  unless user_create_params.key?("password") || (user_create_params.key?("identity_provider_href") && user_create_params.key?("principal_uid"))
+    pass = RsUserPolicy::Utilities.generate_compliant_password
+    user_create_params["password"] = pass
+    user_assignments[net_new_user_email]["password"] = pass
   end
-rescue RightApi::Exceptions::ApiException => e
-  if e.message =~ /Permission denied/
-    log.warn("#{master_account.name} is not an Enterprise Master, or you do not have the enterprise_manager permission.  No child accounts will be operated on.")
-  else
-    raise e
+  net_new_user_href = Digest::MD5.hexdigest((Time.now.to_i + rand(256)).to_s)
+  unless opts[:dry_run]
+    net_new_user = client.users.create(:user => user_create_params)
+    net_new_user_href = net_new_user.href
   end
+  user_collection.add_users({net_new_user_href => net_new_user_email})
+  user_assignments[net_new_user_email]["href"] = net_new_user_href
 end
 
+# Now iterate over all accounts to do actual permission assignments.
 begin
-  accounts.each do |account|
+  multi_client.each do |account_id,account|
     child_client = account[:client]
+    child_account = child_client.accounts(:id => account_id).show()
+    account_name = child_account.name
+    account_href = child_account.href
 
-    log.info("#{account[:name]} - #{account[:href]}")
+    log.info("#{account_name} - #{account_href}")
     user_collection.users.each do |user|
       email = user.email
       user_role = user_assignments.get_roles(email)
-      existing_permissions = user.get_api_permissions(account[:href])
+      existing_permissions = user.get_api_permissions(account_href)
 
       # Allow some different options about possibly prompting the user etc
       if user_role.include?('delete')
@@ -107,16 +122,15 @@ begin
         # a user can also be effectively deleted if they have an empty list of
         # permissions for a particular account
         unless opts[:dry_run]
-          log.debug("Deleting #{user.email} from #{account[:name]} by removing these permissions #{JSON.pretty_generate(existing_permissions)}")
-          user.clear_permissions(account[:href], child_client)
-          user_assignments.delete(user.email)
+          log.debug("Deleting #{user.email} from #{account_name} by removing these permissions #{JSON.pretty_generate(existing_permissions)}")
+          user.clear_permissions(account_href, child_client)
         end
-        audit_log.add_entry(email, account[:name], 'deleted', 'deleted')
+        audit_log.add_entry(email, account_name, 'deleted', 'deleted')
       elsif !user_role.include?("immutable")
-        user_policy = policy.get_permissions(user_role, account[:href])
-        removed,added = user.set_api_permissions(user_policy, account[:href], child_client, opts)
+        user_policy = policy.get_permissions(user_role, account_href)
+        removed,added = user.set_api_permissions(user_policy, account_href, child_client, :dry_run => opts[:dry_run])
         changes = "-#{removed.values} +#{added.values}"
-        audit_log.add_entry(email, account[:name], 'update_permissions', changes) unless removed.length + added.length == 0
+        audit_log.add_entry(email, account_name, 'update_permissions', changes) unless removed.length + added.length == 0
       end
     end
   end
@@ -124,5 +138,11 @@ rescue RightApi::Exceptions::ApiException => e
   log.fatal("A RightScale API exception occurred - #{e}")
 end
 
+user_collection.users.each do |user|
+  if user_assignments.get_roles(user.email).include?("delete") && user.permissions == {}
+    user_assignments.delete(user.email)
+  end
+end unless opts[:dry_run]
+
 user_assignments.serialize(:filename => user_assignments_output)
 audit_log.write_file

data/lib/rs_user_policy/right_api/multi_client.rb

@@ -0,0 +1,91 @@
+# Copyright (c) 2012 Ryan J. Geyer
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module RsUserPolicy
+  module RightApi
+    class MultiClient
+
+      attr_accessor :accounts
+
+      # Creates RightApi::Client instances for each account ID supplied.
+      # If any supplied account ID is an enterprise master account, the
+      # child accounts are found and added to this MultiClient as well.
+      #
+      # @param [String] email Email address of a RightScale user with permissions to access the API
+      # @param [String] password Password of a RightScale user with permissions to access the API
+      # @param [Array<Integer>] accounts List of accounts for which to create RightApi::Client objects
+      def initialize(email, password, accounts)
+        @accounts ||= {}
+        accounts.each do |account_id|
+          client = ::RightApi::Client.new(
+            :email => email,
+            :password => password,
+            :account_id => account_id
+          )
+          this_account = {
+            :client => client,
+            :has_children => false
+          }
+          begin
+            child_accounts = client.child_accounts.index
+            this_account[:has_children] = true
+            # NOTE: Assuming that children can not have grand children
+            child_accounts.each do |child_account_res|
+              # TODO: Looser coupling to the Utilities class here?
+              child_account_id = RsUserPolicy::Utilities.id_from_href(child_account_res.href).to_i
+              child_account = ::RightApi::Client.new(
+                :email => email,
+                :password => password,
+                :account_id => child_account_id
+              )
+              @accounts[child_account_id] = {
+                :client => child_account,
+                :has_children => false,
+                :parent => account_id
+              }
+            end
+          rescue ::RightApi::Exceptions::ApiException => e
+            raise e unless e.message =~ /Permission denied/
+          end
+          @accounts[account_id] = this_account
+        end
+      end
+
+      def length
+        @accounts.length
+      end
+
+      def size
+        length
+      end
+
+      def [](account_id)
+        @accounts[account_id]
+      end
+
+      def each(&block)
+        @accounts.each do |account_id,account|
+          yield account_id, account
+        end
+      end
+    end
+  end
+end

data/lib/rs_user_policy/user.rb

@@ -21,7 +21,7 @@
 
 module RsUserPolicy
   class User
-    attr_reader :email, :href
+    attr_reader :email, :href, :permissions
 
     # Initializes read only attributes for an RsUserPolicy::User
     #
@@ -67,10 +67,12 @@ module RsUserPolicy
       if options[:dry_run]
         Hash[current_permissions.map{|p| [p.href, p.role_title]}]
       else
-        RsUserPolicy::RightApi::PermissionUtilities.destroy_permissions(
+        retval = RsUserPolicy::RightApi::PermissionUtilities.destroy_permissions(
           current_permissions,
           client
         )
+        @permissions.delete(account_href)
+        retval
       end
     end
 
@@ -91,7 +93,9 @@ module RsUserPolicy
       existing_api_permissions_response = get_api_permissions(account_href)
       existing_api_permissions = Hash[existing_api_permissions_response.map{|p| [p.role_title, p] }]
       if permissions.length == 0
-        return clear_permissions(account_href, client, options), {}
+        removed = clear_permissions(account_href, client, options)
+        @permissions.delete(account_href)
+        return removed, {}
       else
         permissions_to_remove = (existing_api_permissions.keys - permissions).map{|p| existing_api_permissions[p]}
         remove_response = Hash[permissions_to_remove.map{|p| [p.href, p.role_title]}]
@@ -112,6 +116,8 @@ module RsUserPolicy
           add_response = RsUserPolicy::RightApi::PermissionUtilities.create_permissions(permissions_to_add, client)
         end
 
+        @permissions[account_href] = client.permissions.index(:filter => ["user_href==#{@href}"]) unless options[:dry_run]
+
         return remove_response, Hash[add_response[@href].keys.map{|p| [add_response[@href][p],p]}]
       end
     end

data/lib/rs_user_policy/user_assignments/json_user_assignments.rb

@@ -75,9 +75,7 @@ module RsUserPolicy
       # @return [Array<String>] The roles assigned to the user
       def get_roles(email)
         # TODO: This seems expensive to do in an accessor?
-        unless @user_assignments.key?(email)
-          @user_assignments[email] = {'roles' => ['immutable']}
-        end
+        add_user(email)
         @user_assignments[email]['roles']
       end
 
@@ -101,6 +99,37 @@ module RsUserPolicy
         File.open(options[:filename], 'w') {|f| f.write(JSON.pretty_generate(@user_assignments))}
       end
 
+      # Returns a list of all user emails which have a user assignment in the source
+      #
+      # @return [Array<String>] An array of email addresses for users with a user assignment
+      def list
+        @user_assignments.keys
+      end
+
+      # Returns a hash which represents the user specified by the email address specified
+      # If the user does not exist the (see #add_user) method will be called and the
+      # user will be created.
+      #
+      # @param [String] email The email address of the user to fetch
+      #
+      # @return [Hash] A hash of key/value pairs to be passed to the RightScale API for Users#create.  This will also include a "roles" key, and may also include any other keys returned by the source
+      def [](email)
+        add_user(email)
+      end
+
+      # Adds a user to user_assignments.  If the user already exists the existing record
+      # will be returned.  Otherwise the user will be created with a single role of "immutable"
+      #
+      # @param [String] email The email address of the user to create or return
+      # @param [Hash] options Hash of property key/value pairs for the user.  The following options are known, but there can be any key in thi hash
+      # @option options [Array<String>] "roles" An array of role names for the user
+      #
+      # @return [Hash] The added or existing user where they key is the users email, and the value is a hash of key/value pairs of user properties.
+      def add_user(email, options={})
+        options = {"roles" => ["immutable"]}.merge(options)
+        @user_assignments[email] || @user_assignments[email] = options
+      end
+
       private
 
       def validate()

data/lib/rs_user_policy/user_assignments/user_assignments.rb

@@ -22,6 +22,13 @@
 module RsUserPolicy
   module UserAssignments
     module UserAssignments
+      # Returns a list of all user emails which have a user assignment in the source
+      #
+      # @return [Array<String>] An array of email addresses for users with a user assignment
+      def list
+        raise NotImplementedError, "Please implement this in your concrete class"
+      end
+
       # @return [Int] The number of users in the user assignments object
       def length
         raise NotImplementedError, "Please implement this in your concrete class"
@@ -57,6 +64,29 @@ module RsUserPolicy
       def serialize(options={})
         raise NotImplementedError, "Please implement this in your concrete class"
       end
+
+      # Returns a hash which represents the user specified by the email address specified
+      # If the user does not exist the (see #add_user) method will be called and the
+      # user will be created.
+      #
+      # @param [String] email The email address of the user to fetch
+      #
+      # @return [Hash] A hash of key/value pairs to be passed to the RightScale API for Users#create.  This will also include a "roles" key, and may also include any other keys returned by the source
+      def [](email)
+        raise NotImplementedError, "Please implement this in your concrete class"
+      end
+
+      # Adds a user to user_assignments.  If the user already exists the existing record
+      # will be returned.  Otherwise the user will be created with a single role of "immutable"
+      #
+      # @param [String] email The email address of the user to create or return
+      # @param [Hash] options Hash of property key/value pairs for the user.  The following options are known, but there can be any key in thi hash
+      # @option options [Array<String>] "roles" An array of role names for the user
+      #
+      # @return [Hash] The added or existing user where they key is the users email, and the value is a hash of key/value pairs of user properties.
+      def add_user(email, options={})
+        raise NotImplementedError, "Please implement this in your concrete class"
+      end
     end
   end
 end

data/lib/rs_user_policy/user_collection.rb

@@ -37,23 +37,26 @@ module RsUserPolicy
     # include the specified users.  The users RightScale API href is used
     # as the unique identifier for deduplication
     #
-    # @param [Array<RightApi::ResourceDetail>] An array of ResourceDetail from the Right API Client for users.  Returned by client.users.index
+    # @param [Hash] users A hash where the key is a users href, and the value is the users email
     def add_users(users)
-      users.each do |user|
-        unless @users_by_href.has_key?(user.href)
-          @users_by_href[user.href] = RsUserPolicy::User.new(user.email, user.href)
+      users.each do |href, email|
+        unless @users_by_href.has_key?(href)
+          @users_by_href[href] = RsUserPolicy::User.new(email, href)
         end
       end
     end
 
-    def [](idx)
-      @users_by_href[idx]
+    def [](href)
+      @users_by_href[href]
     end
 
     def add_permissions(account_href, permissions)
       permissions.each do |permission|
         user_href = permission.user.href
-        add_users([permission.user])
+        unless @users_by_href.has_key?(user_href)
+          user = permission.user.show()
+          @users_by_href[user.href] = RsUserPolicy::User.new(user.email, user.href)
+        end
         @users_by_href[user_href].add_permission(account_href, permission)
       end
     end

data/lib/rs_user_policy/utilities.rb

@@ -56,5 +56,15 @@ module RsUserPolicy
       hash.select{|k,v| !order.include?(v) }.each{|k,v| yield k,v }
     end
 
+    def self.generate_compliant_password(size=12)
+      chars = (
+        ('a'..'z').to_a +
+        ('A'..'Z').to_a +
+        ('0'..'9').to_a +
+        ["!","@","#","$","%","^","&","*","(",")","-","_","=","+"]
+      ) - %w(i o 0 1 l 0)
+      (1..size).collect{|a| chars[rand(chars.size)] }.join
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rs_user_policy
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-15 00:00:00.000000000 Z
+date: 2012-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: right_api_client
@@ -54,6 +54,7 @@ files:
 - lib/rs_user_policy/audit_log.rb
 - lib/rs_user_policy/policy/json_policy.rb
 - lib/rs_user_policy/policy/policy.rb
+- lib/rs_user_policy/right_api/multi_client.rb
 - lib/rs_user_policy/right_api/permission_utilities.rb
 - lib/rs_user_policy/user.rb
 - lib/rs_user_policy/user_assignments/json_user_assignments.rb
@@ -79,7 +80,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4206610464842566721
+      hash: 3250796022551410117
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -88,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4206610464842566721
+      hash: 3250796022551410117
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24