aws-sdk 1.0.4 → 1.1.0

data/lib/aws/iam/user.rb

@@ -0,0 +1,196 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/resource'
+require 'aws/iam/mfa_device_collection'
+require 'aws/iam/user_policy_collection'
+require 'aws/iam/signing_certificate_collection'
+require 'aws/iam/login_profile'
+require 'aws/iam/user_group_collection'
+
+module AWS
+  class IAM
+
+    
+    # Represents an IAM User.  Each AWS account can have many users.  Users
+    # can be organized (optionally) into groups.  Users (and groups) can be
+    # given policies that affect that they can do.
+    #
+    # == Creating A User
+    #
+    #   iam = AWS::IAM.new
+    #
+    #   user = iam.users.create('johndoe')
+    # 
+    #
+    # == Renaming a User
+    #
+    # You can only edit a user's name and path (both of which will modify
+    # the user's ARN).
+    #
+    #   user = iam.users['johndoe']
+    #   user.name = 'newname'
+    #
+    # == User Path
+    # 
+    # When you create a user you can assign a path.  Paths must begin and
+    # end with a forward slash (/).  
+    #
+    #   user = iam.users.create('newuser', :path => '/developers/ruby/')
+    #
+    # Paths are a useful tool for organizing/tagging users.  You can later
+    # enumerate users by their path prefixes:
+    #
+    #   iam.users.each(:path_prefix => '/developers').each do |developer|
+    #     puts developer.name
+    #   end
+    #
+    # == Login Profile
+    #
+    # A login profile is required for an IAM user to use the AWS Management
+    # console (web interface).  See {LoginProfile} for more information.
+    #
+    # == Deleting Users
+    #
+    # In order to delete a user you must first remove it from all of its
+    # groups and delete all of its signing certificates.  Once this is done:
+    #
+    class User < Resource
+
+      prefix_update_attributes
+
+      # @param [String] name The IAM user name for this user.
+      # @param [Hash] options
+      def initialize name, options = {}
+        options[:name] = name
+        super(options)
+      end
+
+      # @attr [String] The IAM user name.
+      mutable_attribute :name, :static => true, :as => :user_name
+
+      # @attr_reader [String] The user's unique ID.
+      attribute :id, :static => true, :as => :user_id
+
+      # @attr_reader [Time] When the user was created.
+      attribute :create_date, :static => true
+
+      # @attr_reader [String] The user's ARN (Amazon Resource Name).
+      attribute :arn
+
+      # @attr [String] The path for this user.  Paths are used to 
+      #   identify which division or part of an organization the user 
+      #   belongs to.
+      mutable_attribute :path
+
+      populates_from(:create_user, :get_user) do |resp|
+        resp.user if resp.user.user_name == name
+      end
+
+      populates_from(:list_users, :get_group) do |resp|
+        resp.users.find{|u| u.user_name == name }
+      end
+
+      # Deletes this user.
+      # @return [nil]
+      def delete
+        client.delete_user(resource_options)
+        nil
+      end
+
+      def delete!
+        groups.clear
+        access_keys.clear
+        policies.clear
+        mfa_devices.clear
+        signing_certificates.clear
+        login_profile.delete if login_profile.exists?
+        delete
+      end
+
+      # Returns a collection that represents all policies for this user.
+      #
+      #   user.policies.each do |policy|
+      #     puts policy.name
+      #   end
+      #
+      # @return [PolicyCollection] Returns a collection that represents
+      #   all policies for this user.
+      def policies
+        UserPolicyCollection.new(self)  
+      end
+
+      # Returns a collection that represents the signing certificates
+      # belonging to this user.
+      #
+      #   user.signing_certificates.each do |cert|
+      #     # ...
+      #   end
+      #
+      # If you need to access the signing certificates of this AWS account,
+      # see {IAM#signing_certificates}.
+      # 
+      # @return [SigningCertificateCollection] Returns a collection that
+      #   represents signing certificates for this user.
+      def signing_certificates
+        SigningCertificateCollection.new(:user => self, :config => config)
+      end
+
+      # @return [MFADeviceCollection] Returns a collection that represents 
+      #   all MFA devices assigned to this user.
+      def mfa_devices
+        MFADeviceCollection.new(self)
+      end
+
+      # A login profile is a user name and password that enables a
+      # user to log in to the {http://aws.amazon.com/console AWS
+      # Management Console}.  The object returned by this method
+      # allows you to set or delete the password.  For example:
+      #
+      #   user.login_profile.password = "TheNewPassword"
+      #
+      # @return [LoginProfile] Returns the login profile for this
+      #   user.
+      def login_profile
+        LoginProfile.new(self)
+      end
+
+      # Returns a collection that represents the access keys for this user.
+      #
+      #   user.access_keys.each do |access_key|
+      #     puts access_key.id
+      #   end
+      #
+      # @return [AccessKeyCollection] Returns a collection that represents all
+      #   access keys for this user.
+      def access_keys
+        AccessKeyCollection.new(:user => self)
+      end
+
+      # Returns a collection that includes all of the groups the user
+      # is in.
+      #
+      # @return [UserGroupCollection]
+      def groups
+        UserGroupCollection.new(self)
+      end
+
+      # @private
+      protected
+      def resource_identifiers
+        [[:user_name, name]]
+      end
+
+    end
+  end
+end

data/lib/aws/iam/user_collection.rb

@@ -0,0 +1,136 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/collection'
+require 'aws/iam/user'
+
+module AWS
+  class IAM
+
+    # A collection that provides access to IAM users belonging to this 
+    # account.
+    #
+    #   iam = AWS::IAM.new
+    #   users = iam.users
+    #
+    # == Creating A User
+    #
+    # To create an IAM user you need only provide a user name.
+    #
+    #   user = users.create('username')
+    #
+    # You can also provide an optional +:path+ that can be used to organize
+    # users.
+    #
+    #   user = users.create('johndoe', :path => '/staff/customer_support/')
+    #
+    # == Getting a User by Name
+    #
+    # You can get a referene to a user by using array notation:
+    #
+    #   user = users['username']
+    #
+    # == Enumerating Users
+    #
+    # A user collection can also be used to enumerate users:
+    #
+    #   users.each do |user|
+    #     puts user.name
+    #   end
+    #
+    # == Path Prefixes
+    #
+    # You can also find/enumerate users who's path begins with a given prefix:
+    #
+    #   users.each(:path_prefix => '/staff/developers/ruby').each do |ruby_dev|
+    #     puts "#{ruby_dev.name} is awesome!"
+    #   end
+    #
+    class UserCollection
+
+      include Collection::WithPrefix
+
+      # @param [String] name Name of the user to create.
+      # @option options [String] :path ('/') The path for the user name. 
+      #   For more information about paths, see 
+      #   {Identifiers for IAM Entities}[http://docs.amazonwebservices.com/IAM/latest/UserGuide/index.html?Using_Identifiers.html]
+      # @return [User] Returns the newly created user.
+      def create name, options = {}
+        create_opts = {}
+        create_opts[:user_name] = name
+        create_opts[:path] = options[:path] if options[:path]
+        resp = client.create_user(create_opts)
+        User.new_from(:create_user, resp.user, 
+          resp.user.user_name, :config => config)
+      end
+
+      # Returns a reference to the user with the given name:
+      #
+      #   user = iam.users['username']
+      #
+      # @param [String] name Name of the user to return a reference for.
+      # @return [User] Returns a reference to the named user.
+      def [] name
+        User.new(name.to_s, :config => config)
+      end
+
+      # Yields once for each user.
+      #
+      # You can limit the number of users yielded using +:limit+ and
+      # +:path_prefix+.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :path_prefix ('/') A path prefix that
+      #   filters according to the path of the user.
+      #
+      # @option options [Integer] :limit The maximum number of users to yield.
+      #
+      # @option options [Integer] :batch_size The maximum number of users
+      #   to retrieve with each service request.
+      #
+      # @yieldparam [User] user
+      # @return [nil]
+      def each options = {}, &block
+        super(options, &block)
+      end
+
+      # Returns an enumerable object for this collection.  This can be
+      # useful if you want to call an enumerable method that does
+      # not accept options (e.g. +collect+, +first+, etc).
+      #
+      #   users.enumerator(:path_prefix => '/admin').collect(&:name)
+      #
+      # @param (see #each)
+      # @option (see #each)
+      # @return [Enumerator]
+      def enumerator options = {}
+        super(options)
+      end
+
+      # @private
+      protected
+      def each_item response, &block
+        response.users.each do |item|
+
+          user = User.new_from(:list_users, item, 
+            item.user_name, :config => config)
+
+          yield(user)
+
+        end
+      end
+
+    end
+  end
+end

data/lib/aws/iam/user_group_collection.rb

@@ -0,0 +1,101 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/collection'
+require 'aws/iam/group'
+
+module AWS
+  class IAM
+
+    # A collection that provides access to IAM groups to which a
+    # particular user belongs.
+    #
+    #   user = AWS::IAM.new.users.first
+    #   groups = user.groups
+    #   groups.each { |g| puts g.name }
+    #
+    class UserGroupCollection
+
+      include Collection
+
+      # @attr_reader [User] The user.
+      attr_reader :user
+
+      # @private
+      def initialize(user, opts = {})
+        @user = user
+        super
+      end
+
+      # Adds the user to a group.
+      #
+      # @param [Group] group The group to which the user should be added.
+      def add(group)
+        client.add_user_to_group(:group_name => group.name,
+                                 :user_name => user.name)
+        nil
+      end
+
+      # Removes the user from a group.
+      #
+      # @param [Group] group The group from which the user should be removed
+      def remove(group)
+        client.remove_user_from_group(:group_name => group.name,
+                                      :user_name => user.name)
+        nil
+      end
+
+      # Removes this user from all groups.
+      # @return [nil]
+      def clear
+        each do |group|
+          remove(group)
+        end
+      end
+
+      # Yields once for each group that the user is in.
+      #
+      # @param [Hash] options
+      #
+      # @option options [Integer] :limit Limits the number of groups
+      #   that are returned.
+      #
+      # @option options [Integer] :batch_size Controls how many groups
+      #   are requested from the service at once.
+      #
+      # @yieldparam [Group] group
+      #
+      # @return [nil]
+      def each(options = {}, &block)
+        super(options.merge(:user_name => user.name), &block)
+      end
+
+      # @private
+      protected
+      def request_method
+        :list_groups_for_user
+      end
+
+      # @private
+      protected
+      def each_item response
+        response.groups.each do |g|
+          group = Group.new_from(:list_groups_for_user, g, g.group_name, :config => config)
+          yield(group)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/aws/iam/user_policy.rb

@@ -0,0 +1,90 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/resource'
+require 'aws/iam/policy'
+require 'uri'
+
+module AWS
+  class IAM
+
+    class UserPolicy < Resource
+
+      # @param [User] The user this user policy belongs to.
+      # @param [String] The name of this user policy.
+      def initialize user, name, options = {}
+        @user = user
+        @name = name
+        super
+      end
+
+      # @return [User] Returns the user this user policy belongs to.
+      attr_reader :user
+
+      # @return [String] Returns the name of this user policy.
+      attr_reader :name
+
+      # @private
+      module PolicyProxy
+
+        attr_accessor :user_policy
+
+        def change
+          yield(self)
+          user_policy.policy = self
+        end
+
+      end
+
+      # @return [Policy] Returns the actual policy document for this
+      #   user policy.
+      def policy
+
+        response = client.get_user_policy(
+          :user_name => user.name,
+          :policy_name => name)
+
+        policy = Policy.from_json(URI.decode(response.policy_document))
+        policy.extend(PolicyProxy)
+        policy.user_policy = self
+        policy
+
+      end
+
+      # Replaces or updates the user policy with the given policy document.
+      # @param [Policy] policy
+      # @return [nil]
+      def policy= policy
+
+        policy_document = policy.is_a?(String) ? policy : policy.to_json
+
+        options = {}
+        options[:user_name] = user.name
+        options[:policy_name] = name
+        options[:policy_document] = policy_document
+
+        client.put_user_policy(options)
+
+        nil
+      end
+
+      # Deletes this user policy.
+      # @return [nil]
+      def delete
+        client.delete_user_policy(:user_name => user.name, :policy_name => name)
+        nil
+      end
+
+    end
+
+  end
+end