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/client.rb,
lib/aws/iam/errors.rb,
lib/aws/iam/policy.rb,
lib/aws/iam/request.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/access_key_collection.rb,
lib/aws/iam/group_user_collection.rb,
lib/aws/iam/mfa_device_collection.rb,
lib/aws/iam/user_group_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:

Defined Under Namespace

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

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #initialize, #inspect

Instance Method Details

#access_keys ⇒ AccessKeyCollection

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.



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

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

#account_alias ⇒ String?

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.



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

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.



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

def  
  .nil? ?
     :
    .create()
end

#account_aliases ⇒ Object 



298
299
300
 
# File 'lib/aws/iam.rb', line 298

def 
  AccountAliasCollection.new(:config => config)
end

#account_password_policy ⇒ Hash?

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) 


399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/aws/iam.rb', line 399

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_summary ⇒ Hash

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) 


336
337
338
339
340
 
# File 'lib/aws/iam.rb', line 336

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) 


361
362
363
364
365
366
367
 
# File 'lib/aws/iam.rb', line 361

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_policy ⇒ nil

Removes the account password policy.

Returns:

  • (nil) 


384
385
386
387
 
# File 'lib/aws/iam.rb', line 384

def 
  client.
  nil
end

#groups ⇒ GroupCollection

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.



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

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

#remove_account_alias ⇒ nil

Deletes the account alias (if one exists).

Returns:

  • (nil) 


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

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

#server_certificates ⇒ ServerCertificateCollection

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:



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

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

#signing_certificates ⇒ SigningCertificateCollection

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:



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

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) 


377
378
379
380
 
# File 'lib/aws/iam.rb', line 377

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

#users ⇒ UserCollection

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.



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

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

#virtual_mfa_devices ⇒ VirtualMfaDeviceCollection

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.



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

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