You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::IAM

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/iam.rb,
lib/aws/iam/user.rb,
lib/aws/iam/group.rb,
lib/aws/iam/policy.rb,
lib/aws/iam/errors.rb,
lib/aws/iam/client.rb,
lib/aws/iam/resource.rb,
lib/aws/iam/access_key.rb,
lib/aws/iam/collection.rb,
lib/aws/iam/mfa_device.rb,
lib/aws/iam/user_policy.rb,
lib/aws/iam/login_profile.rb,
lib/aws/iam/user_collection.rb,
lib/aws/iam/group_collection.rb,
lib/aws/iam/policy_collection.rb,
lib/aws/iam/server_certificate.rb,
lib/aws/iam/virtual_mfa_device.rb,
lib/aws/iam/signing_certificate.rb,
lib/aws/iam/user_group_collection.rb,
lib/aws/iam/mfa_device_collection.rb,
lib/aws/iam/group_user_collection.rb,
lib/aws/iam/access_key_collection.rb,
lib/aws/iam/user_policy_collection.rb,
lib/aws/iam/group_policy_collection.rb,
lib/aws/iam/account_alias_collection.rb,
lib/aws/iam/server_certificate_collection.rb,
lib/aws/iam/virtual_mfa_device_collection.rb,
lib/aws/iam/signing_certificate_collection.rb

Overview

This class is the starting point for working with AWS Identity and Access Management (IAM).

For more information about IAM:

Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the IAM interface:

iam = AWS::IAM.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Account Summary

You can get account level information about entity usage and IAM quotas directly from an IAM interface object.

summary = iam.

puts "Num users: #{summary[:users]}"
puts "Num user quota: #{summary[:users_quota]}"

For a complete list of summary attributes see the #account_summary method.

Account Aliases

Currently IAM only supports a single account alias for each AWS account. You can set the account alias on the IAM interface.

iam. = 'myaccountalias'
iam.
#=> 'myaccountalias'

You can also remove your account alias:

iam.
iam.
#=> nil

Access Keys

You can create up to 2 access for your account and 2 for each user. This makes it easy to rotate keys if you need to. You can also deactivate/activate access keys.

# get your current access key
old_access_key = iam.access_keys.first

# create a new access key
new_access_key = iam.access_keys.create
new_access_key.credentials
#=> { :access_key_id => 'ID', :secret_access_key => 'SECRET' }

# go rotate your keys/credentials ...

# now disable the old access key
old_access_key.deactivate!

# go make sure everything still works ...

# all done, lets clean up
old_access_key.delete

Users can also have access keys:

u = iam.users['someuser']
access_key = u.access_keys.create
access_key.credentials
#=> { :access_key_id => 'ID', :secret_access_key => 'SECRET' }

See AccessKeyCollection and AccessKey for more information about working with access keys.

Users & Groups

Each AWS account can have multiple users. Users can be used to easily manage permissions. Users can also be organized into groups.

user = iam.users.create('JohnDoe')
group = iam.groups.create('Developers')

# add a user to a group
user.groups.add(group)

# remove a user from a group
user.groups.remove(group)

# add a user to a group
group.users.add(user)

# remove a user from a group
group.users.remove(user)

See User, UserCollection, Group and GroupCollection for more information on how to work with users and groups.

Other Interfaces

Other useful IAM interfaces: * User Login Profiles (LoginProfile) * Policies (Policy) * Server Certificates (ServerCertificateCollection, ServerCertificate) * Signing Certificates (SigningCertificateCollection, SigningCertificate) * Multifactor Authentication Devices (MFADeviceCollection, MFADevice)

Defined Under Namespace

Modules: Collection, Errors, PolicyCollection Classes: AccessKey, AccessKeyCollection, Client, Group, GroupCollection, GroupPolicyCollection, GroupUserCollection, LoginProfile, MFADevice, MFADeviceCollection, Policy, Resource, ServerCertificate, ServerCertificateCollection, SigningCertificate, SigningCertificateCollection, User, UserCollection, UserGroupCollection, UserPolicy, UserPolicyCollection, VirtualMfaDevice, VirtualMfaDeviceCollection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #initialize, #inspect

Instance Attribute Details

#clientClient (readonly)

Returns the low-level IAM client object

Returns:

  • (Client)

    the low-level IAM client object



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
# File 'lib/aws/iam.rb', line 137

class IAM

  autoload :AccessKey, 'aws/iam/access_key'
  autoload :AccessKeyCollection, 'aws/iam/access_key_collection'
  autoload :AccountAliasCollection, 'aws/iam/account_alias_collection'
  autoload :Client, 'aws/iam/client'
  autoload :Collection, 'aws/iam/collection'
  autoload :Errors, 'aws/iam/errors'
  autoload :Group, 'aws/iam/group'
  autoload :GroupCollection, 'aws/iam/group_collection'
  autoload :GroupPolicyCollection, 'aws/iam/group_policy_collection'
  autoload :GroupUserCollection, 'aws/iam/group_user_collection'
  autoload :LoginProfile, 'aws/iam/login_profile'
  autoload :MFADevice, 'aws/iam/mfa_device'
  autoload :MFADeviceCollection, 'aws/iam/mfa_device_collection'
  autoload :Policy, 'aws/iam/policy'
  autoload :PolicyCollection, 'aws/iam/policy_collection'
  autoload :Resource, 'aws/iam/resource'
  autoload :ServerCertificate, 'aws/iam/server_certificate'
  autoload :ServerCertificateCollection, 'aws/iam/server_certificate_collection'
  autoload :SigningCertificate, 'aws/iam/signing_certificate'
  autoload :SigningCertificateCollection, 'aws/iam/signing_certificate_collection'
  autoload :User, 'aws/iam/user'
  autoload :UserCollection, 'aws/iam/user_collection'
  autoload :UserGroupCollection, 'aws/iam/user_group_collection'
  autoload :UserPolicy, 'aws/iam/user_policy'
  autoload :UserPolicyCollection, 'aws/iam/user_policy_collection'
  autoload :VirtualMfaDeviceCollection, 'aws/iam/virtual_mfa_device_collection'
  autoload :VirtualMfaDevice, 'aws/iam/virtual_mfa_device'

  include Core::ServiceInterface

  endpoint_prefix 'iam', :global => true

  # Returns a collection that represents all AWS users for this account:
  #
  # @example Getting a user by name
  #
  #   user = iam.users['username']
  #
  # @example Enumerating users
  #
  #   iam.users.each do |user|
  #     puts user.name
  #   end
  #
  # @return [UserCollection] Returns a collection that represents all of
  #   the IAM users for this AWS account.
  def users
    UserCollection.new(:config => config)
  end

  # Returns a collection that represents all AWS groups for this account:
  #
  # @example Getting a group by name
  #
  #   group = iam.groups['groupname']
  #
  # @example Enumerating groups
  #
  #   iam.groups.each do |group|
  #     puts group.name
  #   end
  #
  # @return [GroupCollection] Returns a collection that represents all of
  #   the IAM groups for this AWS account.
  def groups
    GroupCollection.new(:config => config)
  end

  # Returns a collection that represents the access keys for this
  # AWS account.
  #
  #     iam = AWS::IAM.new
  #     iam.access_keys.each do |access_key|
  #       puts access_key.id
  #     end
  #
  # @return [AccessKeyCollection] Returns a collection that represents all
  #   access keys for this AWS account.
  def access_keys
    AccessKeyCollection.new(:config => config)
  end

  # Returns a collection that represents the signing certificates
  # for this AWS account.
  #
  #     iam = AWS::IAM.new
  #     iam.signing_certificates.each do |cert|
  #       # ...
  #     end
  #
  # If you need to access the signing certificates of a specific user,
  # see {User#signing_certificates}.
  #
  # @return [SigningCertificateCollection] Returns a collection that
  #   represents signing certificates for this AWS account.
  def signing_certificates
    SigningCertificateCollection.new(:config => config)
  end

  # @note Currently, Amazon Elastic Load Balancing is the only
  #   service to support the use of server certificates with
  #   IAM. Using server certificates with Amazon Elastic Load
  #   Balancing is described in the
  #   {http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/US_SettingUpLoadBalancerHTTPSIntegrated.html
  #   Amazon Elastic Load Balancing} Developer Guide.
  #
  # Returns a collection that represents the server certificates
  # for this AWS account.
  #
  #     iam = AWS::IAM.new
  #     iam.server_certificates.each do |cert|
  #       # ...
  #     end
  #
  # @return [ServerCertificateCollection] Returns a collection that
  #   represents server certificates for this AWS account.
  def server_certificates
    ServerCertificateCollection.new(:config => config)
  end

  # Returns a collection that represents the virtual MFA devices
  # that are not assigned to an IAM user.
  #
  #     iam = AWS::IAM.new
  #     iam.virtual_mfa_devices.each do |cert|
  #       # ...
  #     end
  #
  # @return [VirtualMfaDeviceCollection] Returns a collection that
  #   represents the virtual MFA devices that are not assigned to an
  #   IAM user.
  def virtual_mfa_devices
    VirtualMfaDeviceCollection.new(:config => config)
  end

  # Sets the account alias for this AWS account.
  # @param [String] account_alias
  # @return [String] Returns the account alias passed.
  def  
    .nil? ?
       :
      .create()
  end

  # @return [String,nil] Returns the account alias.  If this account has
  #   no alias, then `nil` is returned.
  def 
    .first
  end

  # Deletes the account alias (if one exists).
  # @return [nil]
  def 
    .each do ||
      .delete()
    end
    nil
  end

  # @api private
  def 
    AccountAliasCollection.new(:config => config)
  end

  # Retrieves account level information about account entity usage
  # and IAM quotas.  The returned hash contains the following keys:
  #
  # * `:users` - Number of users for the AWS account
  # * `:users_quota` - Maximum users allowed for the AWS account
  # * `:groups` - Number of Groups for the AWS account
  # * `:groups_quota` - Maximum Groups allowed for the AWS account
  # * `:server_certificates` - Number of Server Certificates for the
  #   AWS account
  # * `:server_certificates_quota` - Maximum Server Certificates
  #   allowed for the AWS account
  # * `:user_policy_size_quota` - Maximum allowed size for user policy
  #   documents (in kilobytes)
  # * `:group_policy_size_quota` - Maximum allowed size for Group
  #   policy documents (in kilobyes)
  # * `:groups_per_user_quota` - Maximum number of groups a user can
  #   belong to
  # * `:signing_certificates_per_user_quota` - Maximum number of X509
  #   certificates allowed
  #   for a user
  # * `:access_keys_per_user_quota` - Maximum number of access keys
  #   that can be created per user
  # @return [Hash]
  def 
    client..data[:summary_map].inject({}) do |h,(k,v)|
      h.merge(Core::Inflection.ruby_name(k).to_sym => v)
    end
  end

  # Changes the web password associated with the current IAM user.
  # In order to change your password you must configure the sdk
  # to use your IAM user credentials.
  #
  #
  # To change a user password, you must be using credentials from the
  # user you want to change:
  #
  #     # pass in a key pair generated for the user you want to change
  #     # the password for
  #     iam = AWS::IAM.new(:access_key_id => '...', :secret_access_key => '...)
  #     iam.change_password('old-password', 'new-password')
  #
  # @param [String] old_password
  #
  # @param [String] new_password
  #
  # @return [nil]
  #
  def change_password old_password, new_password
    client_opts = {}
    client_opts[:old_password] = old_password
    client_opts[:new_password] = new_password
    client.change_password(client_opts)
    nil
  end

  # Updates the account password policy for all IAM accounts.
  # @param [Hash] options
  # @option options [Integer] :minimum_password_length
  # @option options [Boolean] :require_symbols
  # @option options [Boolean] :require_numbers
  # @option options [Boolean] :require_uppercase_characters
  # @option options [Boolean] :require_lowercase_characters
  # @return [nil]
  def  options = {}
    client.(options)
    nil
  end

  # Removes the account password policy.
  # @return [nil]
  def 
    client.
    nil
  end

  # Returns the account password policy details as a hash.  This method
  # returns nil if no password policy has been set for this account.
  #
  #     # set the policy
  #     iam.update_account_password_policy :minimum_password_length => 8
  #
  #     iam.account_password_policy
  #     #=> {:require_symbols=>false, :require_numbers=>false, :require_uppercase_characters=>false, :require_lowercase_characters=>false, :minimum_password_length=>8}
  #
  # @return [Hash,nil]
  def 
    begin
      policy = client..password_policy
      [
        :minimum_password_length,
        :require_symbols?,
        :require_numbers?,
        :require_uppercase_characters?,
        :require_lowercase_characters?,
      ].inject({}) do |hash,method|
        key = method.to_s.sub(/\?/, '').to_sym
        hash.merge(key => policy.send(method))
      end
    rescue Errors::NoSuchEntity
      nil
    end
  end

end

Instance Method Details

#access_keysAccessKeyCollection

Returns a collection that represents the access keys for this AWS account.

iam = AWS::IAM.new
iam.access_keys.each do |access_key|
  puts access_key.id
end

Returns:

  • (AccessKeyCollection)

    Returns a collection that represents all access keys for this AWS account.



217
218
219
# File 'lib/aws/iam.rb', line 217

def access_keys
  AccessKeyCollection.new(:config => config)
end

#account_aliasString?

Returns the account alias. If this account has no alias, then nil is returned.

Returns:

  • (String, nil)

    Returns the account alias. If this account has no alias, then nil is returned.



285
286
287
# File 'lib/aws/iam.rb', line 285

def 
  .first
end

#account_alias=(account_alias) ⇒ String

Sets the account alias for this AWS account.

Parameters:

  • account_alias (String)

Returns:

  • (String)

    Returns the account alias passed.



277
278
279
280
281
# File 'lib/aws/iam.rb', line 277

def  
  .nil? ?
     :
    .create()
end

#account_password_policyHash?

Returns the account password policy details as a hash. This method returns nil if no password policy has been set for this account.

# set the policy
iam. :minimum_password_length => 8

iam.
#=> {:require_symbols=>false, :require_numbers=>false, :require_uppercase_characters=>false, :require_lowercase_characters=>false, :minimum_password_length=>8}

Returns:

  • (Hash, nil)


389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
# File 'lib/aws/iam.rb', line 389

def 
  begin
    policy = client..password_policy
    [
      :minimum_password_length,
      :require_symbols?,
      :require_numbers?,
      :require_uppercase_characters?,
      :require_lowercase_characters?,
    ].inject({}) do |hash,method|
      key = method.to_s.sub(/\?/, '').to_sym
      hash.merge(key => policy.send(method))
    end
  rescue Errors::NoSuchEntity
    nil
  end
end

#account_summaryHash

Retrieves account level information about account entity usage and IAM quotas. The returned hash contains the following keys:

  • :users - Number of users for the AWS account
  • :users_quota - Maximum users allowed for the AWS account
  • :groups - Number of Groups for the AWS account
  • :groups_quota - Maximum Groups allowed for the AWS account
  • :server_certificates - Number of Server Certificates for the AWS account
  • :server_certificates_quota - Maximum Server Certificates allowed for the AWS account
  • :user_policy_size_quota - Maximum allowed size for user policy documents (in kilobytes)
  • :group_policy_size_quota - Maximum allowed size for Group policy documents (in kilobyes)
  • :groups_per_user_quota - Maximum number of groups a user can belong to
  • :signing_certificates_per_user_quota - Maximum number of X509 certificates allowed for a user
  • :access_keys_per_user_quota - Maximum number of access keys that can be created per user

Returns:

  • (Hash)


326
327
328
329
330
# File 'lib/aws/iam.rb', line 326

def 
  client..data[:summary_map].inject({}) do |h,(k,v)|
    h.merge(Core::Inflection.ruby_name(k).to_sym => v)
  end
end

#change_password(old_password, new_password) ⇒ nil

Changes the web password associated with the current IAM user. In order to change your password you must configure the sdk to use your IAM user credentials.

To change a user password, you must be using credentials from the user you want to change:

# pass in a key pair generated for the user you want to change
# the password for
iam = AWS::IAM.new(:access_key_id => '...', :secret_access_key => '...)
iam.change_password('old-password', 'new-password')

Parameters:

  • old_password (String)
  • new_password (String)

Returns:

  • (nil)


351
352
353
354
355
356
357
# File 'lib/aws/iam.rb', line 351

def change_password old_password, new_password
  client_opts = {}
  client_opts[:old_password] = old_password
  client_opts[:new_password] = new_password
  client.change_password(client_opts)
  nil
end

#delete_account_password_policynil

Removes the account password policy.

Returns:

  • (nil)


374
375
376
377
# File 'lib/aws/iam.rb', line 374

def 
  client.
  nil
end

#groupsGroupCollection

Returns a collection that represents all AWS groups for this account:

Examples:

Getting a group by name


group = iam.groups['groupname']

Enumerating groups


iam.groups.each do |group|
  puts group.name
end

Returns:

  • (GroupCollection)

    Returns a collection that represents all of the IAM groups for this AWS account.



203
204
205
# File 'lib/aws/iam.rb', line 203

def groups
  GroupCollection.new(:config => config)
end

#remove_account_aliasnil

Deletes the account alias (if one exists).

Returns:

  • (nil)


291
292
293
294
295
296
# File 'lib/aws/iam.rb', line 291

def 
  .each do ||
    .delete()
  end
  nil
end

#server_certificatesServerCertificateCollection

Note:

Currently, Amazon Elastic Load Balancing is the only service to support the use of server certificates with IAM. Using server certificates with Amazon Elastic Load Balancing is described in the Amazon Elastic Load Balancing Developer Guide.

Returns a collection that represents the server certificates for this AWS account.

iam = AWS::IAM.new
iam.server_certificates.each do |cert|
  # ...
end

Returns:



255
256
257
# File 'lib/aws/iam.rb', line 255

def server_certificates
  ServerCertificateCollection.new(:config => config)
end

#signing_certificatesSigningCertificateCollection

Returns a collection that represents the signing certificates for this AWS account.

iam = AWS::IAM.new
iam.signing_certificates.each do |cert|
  # ...
end

If you need to access the signing certificates of a specific user, see AWS::IAM::User#signing_certificates.

Returns:



234
235
236
# File 'lib/aws/iam.rb', line 234

def signing_certificates
  SigningCertificateCollection.new(:config => config)
end

#update_account_password_policy(options = {}) ⇒ nil

Updates the account password policy for all IAM accounts.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :minimum_password_length (Integer)
  • :require_symbols (Boolean)
  • :require_numbers (Boolean)
  • :require_uppercase_characters (Boolean)
  • :require_lowercase_characters (Boolean)

Returns:

  • (nil)


367
368
369
370
# File 'lib/aws/iam.rb', line 367

def  options = {}
  client.(options)
  nil
end

#usersUserCollection

Returns a collection that represents all AWS users for this account:

Examples:

Getting a user by name


user = iam.users['username']

Enumerating users


iam.users.each do |user|
  puts user.name
end

Returns:

  • (UserCollection)

    Returns a collection that represents all of the IAM users for this AWS account.



185
186
187
# File 'lib/aws/iam.rb', line 185

def users
  UserCollection.new(:config => config)
end

#virtual_mfa_devicesVirtualMfaDeviceCollection

Returns a collection that represents the virtual MFA devices that are not assigned to an IAM user.

iam = AWS::IAM.new
iam.virtual_mfa_devices.each do |cert|
  # ...
end

Returns:

  • (VirtualMfaDeviceCollection)

    Returns a collection that represents the virtual MFA devices that are not assigned to an IAM user.



270
271
272
# File 'lib/aws/iam.rb', line 270

def virtual_mfa_devices
  VirtualMfaDeviceCollection.new(:config => config)
end