The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-Amazon-IAM-0.04
River stage zero No dependents
1 ++
/ Net::Amazon::IAM

NAME

Net::Amazon::IAM - Perl interface to the Amazon Identity and Access Management.

VERSION

This is Net::Amazon::IAM version 0.04

IAM Query API version: '2010-05-08'

SYNOPSIS

 use Net::Amazon::IAM;

 my $iam = Net::Amazon::IAM->new(
   AWSAccessKeyId  => 'PUBLIC_KEY_HERE',
   SecretAccessKey => 'SECRET_KEY_HERE'
 );

 # create new user
 my $user = $iam->create_user (
   UserName => 'testuser',
   Path     => '/path/to/test/user/',
 );

 # delete user
 my $delete = $iam->delete_user(UserName => 'testuser');
 if($delete->isa("Net::Amazon::IAM::Error")) {
   print Dumper $delete;
 }else{
   print "User was successfuly deleted\n";
 }

 # prepare user policy document
 my $policy_document = {
   Version => '2012-10-17',
   Statement => [
      {
         Effect   => 'Allow',
         Action   => [
            's3:Get*',
            's3:List*',
         ],
         Resource => [
            'arn:aws:s3:::sometestbucket',
            'arn:aws:s3:::sometestbucket/*',
         ],
      },
   ],
 };

 # attach the document to the user
 my $policy = $iam->put_user_policy (
    PolicyName     => 'somtestpolicy',
    UserName       => 'sometestuser',
    PolicyDocument => $policy_document,
 );

 if($policy->isa("Net::Amazon::IAM::Error")) {
   print Dumper $policy;
 }else{
   print "Policy was added\n";
 }

If an error occurs while communicating with IAM, these methods will throw a Net::Amazon::IAM::Error exception.

DESCRIPTION

This module is a Perl interface to Amazon's Identity and Access Management (IAM). It uses the Query API to communicate with Amazon's Web Services framework.

CLASS METHODS

new(%params)

This is the constructor, it will return you a Net::Amazon::IAM object to work with. It takes these parameters:

AWSAccessKeyId (required)

Your AWS access key.

SecretAccessKey (required)

Your secret key, WARNING! don't give this out or someone will be able to use your account and incur charges on your behalf.

debug (optional)

A flag to turn on debugging. Among other useful things, it will make the failing api calls print a stack trace. It is turned off by default.

return_errors (optional)

A flag to enable returning errors as objects instead of throwing them as exceptions.

create_user(%params)

Create new IAM user

UserName (required)

New user username

Path (optional)

Where to create new user

Returns a Net::Amazon::IAM::User object on success or Net::Amazon::IAM::Error on fail.

delete_user(%params)

Delete IAM User

UserName (required)

What user should be deleted

Returns true on success or Net::Amazon::IAM::Error on fail.

get_user(%params)

Get IAM user details

UserName (required)

New user username

Returns a Net::Amazon::IAM::User object on success or Net::Amazon::IAM::Error on fail.

update_user(%params)

Updates the name and/or the path of the specified user.

UserName (required)

Name of the user to update. If you're changing the name of the user, this is the original user name.

NewPath (optional)

New path for the user. Include this parameter only if you're changing the user's path.

NewUserName (optional)

New name for the user. Include this parameter only if you're changing the user's name.

Returns true on success or Net::Amazon::IAM::Error on fail.

list_users(%params)

Lists the IAM users that have the specified path prefix. If no path prefix is specified, the action returns all users in the AWS account.

Marker (required)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of user names you want in the response. If there are additional user names beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

PathPrefix (optional)

The path prefix for filtering the results. For example: /division_abc/subdivision_xyz/, which would get all user names whose path starts with /division_abc/subdivision_xyz/.

Returns Net::Amazon::IAM::Users object on success or Net::Amazon::IAM::Error on fail.

add_user_to_group(%params)

Adds the specified user to the specified group.

GroupName (required)

The name of the group to update.

UserName (required)

The name of the user to add.

Returns true on success or Net::Amazon::IAM::Error on fail.

remove_user_from_group(%params)

Removes the specified user from the specified group.

GroupName (required)

The name of the group to update.

UserName (required)

The name of the user to remove.

Returns true on success or Net::Amazon::IAM::Error on fail.

create_group(%params)

Creates a new group.

GroupName (required)

The name of the group to create.

Path (optional)

The path to the group.

Returns Net::Amazon::IAM::Group object on success or Net::Amazon::IAM::Error on fail.

get_group(%params)

Returns group details and list of users that are in the specified group.

GroupName (required)

The name of the group.

MaxItems (optional)

Use this only when paginating results to indicate the maximum number of groups you want in the response. If there are additional groups beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

Marker (optional)

Use this only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

Returns Net::Amazon::IAM::GetGroupResult object on success or Net::Amazon::IAM::Error on fail.

delete_group(%params)

Deletes the specified group. The group must not contain any users or have any attached policies.

GroupName (required)

The name of the group to delete.

Returns true on success or Net::Amazon::IAM::Error on fail.

list_groups(%params)

Lists the groups that have the specified path prefix.

Marker (optional)

Use this only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this only when paginating results to indicate the maximum number of groups you want in the response. If there are additional groups beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

PathPrefix (optional)

The path prefix for filtering the results. For example, the prefix /division_abc/subdivision_xyz/ gets all groups whose path starts with /division_abc/subdivision_xyz/.

Returns Net::Amazon::IAM::Groups object on success or Net::Amazon::IAM::Error on fail.

create_policy(%params)

Creates a new managed policy for your AWS account.

PolicyName (required)

The name of the policy document.

PolicyDocument (required)

The policy document.

Description (optional)

A friendly description of the policy.

Path (optional)

The path for the policy.

Returns Net::Amazon::IAM::Policy object on success or Net::Amazon::IAM::Error on fail.

get_policy(%params)

Retrieves information about the specified managed policy.

PolicyArn (required)

The Amazon Resource Name (ARN). ARNs are unique identifiers for AWS resources.

Returns Net::Amazon::IAM::Policy object on success or Net::Amazon::IAM::Error on fail.

delete_policy(%params)

Deletes the specified managed policy.

PolicyArn (required)

The Amazon Resource Name (ARN). ARNs are unique identifiers for AWS resources.

Returns true on success or Net::Amazon::IAM::Error on fail.

list_policies(%params)

Lists all the managed policies that are available to your account, including your own customer managed policies and all AWS managed policies.

You can filter the list of policies that is returned using the optional OnlyAttached, Scope, and PathPrefix parameters. For example, to list only the customer managed policies in your AWS account, set Scope to Local. To list only AWS managed policies, set Scope to AWS.

OnlyAttached (optional)

A flag to filter the results to only the attached policies. When OnlyAttached is true, the returned list contains only the policies that are attached to a user, group, or role. When OnlyAttached is false, or when the parameter is not included, all policies are returned.

PathPrefix (optional)

The path prefix for filtering the results. If it is not included, it defaults to a slash (/), listing all policies.

Scope (optional)

The scope to use for filtering the results.

To list only AWS managed policies, set Scope to AWS. To list only the customer managed policies in your AWS account, set Scope to Local. If it is not included, or if it is set to All, all policies are returned.

MaxItems (optional)

Maximum number of policies to retrieve.

Marker (optional)

If IsTruncated is true, this element is present and contains the value to use for the Marker parameter in a subsequent pagination request.

Example: my $policies = $iam->list_policies( MaxItems => 1 );

 while($policies->IsTruncated eq 'true') {
    for my $policy(@{$policies->{'Policies'}}) {
       print $policy->PolicyId . "\n";
    }

    $policies = $iam->list_policies(
       MaxItems => 50,
       Marker   => $policies->Marker,
    );
 }

Returns Net::Amazon::IAM::Policies on success or Net::Amazon::IAM::Error on fail. When no policies found, the Policies attribute will be just empty array.

put_user_policy(%params)

Deletes the specified managed policy.

PolicyDocument (required)

The policy document. Must be HashRef.

PolicyName (required)

The name of the policy document.

UserName (required)

The name of the user to associate the policy with.

Returns true on success or Net::Amazon::IAM::Error on fail.

get_user_policy(%params)

Retrieves the specified inline policy document that is embedded in the specified user.

PolicyName (required)

The name of the policy document to get.

UserName (required)

The name of the user who the policy is associated with.

Returns Net::Amazon::IAM::UserPolicy object on success or Net::Amazon::IAM::Error on fail.

delete_user_policy(%params)

Deletes the specified inline policy that is embedded in the specified user.

PolicyName (required)

The name identifying the policy document to delete.

UserName (required)

The name (friendly name, not ARN) identifying the user that the policy is embedded in.

Returns true on success or Net::Amazon::IAM::Error on fail.

list_user_policies(%params)

Lists the names of the inline policies embedded in the specified user.

UserName (required)

The name of the user to list policies for.

When found one or more policies, this method will return ArrayRef with policy names. Once no policies found, will return undef; Net::Amazon::IAM::Error will be returned on error

create_access_key(%params)

Creates a new AWS secret access key and corresponding AWS access key ID for the specified user. The default status for new keys is Active. If you do not specify a user name, IAM determines the user name implicitly based on the AWS access key ID signing the request. Because this action works for access keys under the AWS account, you can use this action to manage root credentials even if the AWS account has no associated users.

Important:

To ensure the security of your AWS account, the secret access key is accessible only during key and user creation. You must save the key (for example, in a text file) if you want to be able to access it again. If a secret key is lost, you can delete the access keys for the associated user and then create new keys.

UserName (optional)

The user name that the new key will belong to.

Returns Net::Amazon::IAM::AccessKey object on success or Net::Amazon::IAM::Error on fail.

delete_access_key(%params)

Deletes the access key associated with the specified user.

If you do not specify a user name, IAM determines the user name implicitly based on the AWS access key ID signing the request. Because this action works for access keys under the AWS account, you can use this action to manage root credentials even if the AWS account has no associated users.

AccessKeyId (required)

The access key ID for the access key ID and secret access key you want to delete.

UserName (optional)

The name of the user whose key you want to delete.

Returns true on success or Net::Amazon::IAM::Error on fail.

list_access_keys(%params)

Returns information about the access key IDs associated with the specified user. If the UserName field is not specified, the UserName is determined implicitly based on the AWS access key ID used to sign the request. Because this action works for access keys under the AWS account, you can use this action to manage root credentials even if the AWS account has no associated users.

UserName (optional)

The name of the user.

Returns Net::Amazon::IAM::AccessKeysList on success. If specified user has no keys, "Keys" attribute of Net::Amazon::IAM::AccessKeysList object will be just empty array. Returns Net::Amazon::IAM::Error on fail.

create_role(%params)

Creates a new role for your AWS account.

The example policy grants permission to an EC2 instance to assume the role. { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": ["ec2.amazonaws.com"] }, "Action": ["sts:AssumeRole"] }] }

AssumeRolePolicyDocument (required)

The policy that grants an entity permission to assume the role.

RoleName (required)

The name of the role to create.

Path (optional)

The path to the role.

Returns Net::Amazon::IAM::Role object on success or Net::Amazon::IAM::Error on fail.

get_role(%params)

Retrieves information about the specified role.

RoleName (required)

The name of the role to get information about.

Returns Net::Amazon::IAM::Role object on success or Net::Amazon::IAM::Error on fail.

list_roles(%params)

Retrieves information about the specified role.

Marker (optional)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of roles you want in the response. If there are additional roles beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

PathPrefix (optional)

The path prefix for filtering the results. For example, the prefix /application_abc/component_xyz/ gets all roles whose path starts with /application_abc/component_xyz/.

This parameter is optional. If it is not included, it defaults to a slash (/), listing all roles.

Returns Net::Amazon::IAM::Roles object on success or Net::Amazon::IAM::Error on fail.

delete_role(%params)

Deletes the specified role. The role must not have any policies attached.

Important:

Make sure you do not have any Amazon EC2 instances running with the role you are about to delete. Deleting a role or instance profile that is associated with a running instance will break any applications running on the instance.

RoleName (required)

The name of the role to delete.

Returns true on success or Net::Amazon::IAM::Error on fail.

create_virtual_MFA_device(%params)

Creates a new virtual MFA device for the AWS account. After creating the virtual MFA, use EnableMFADevice to attach the MFA device to an IAM user.

Important:

The seed information contained in the QR code and the Base32 string should be treated like any other secret access information, such as your AWS access keys or your passwords. After you provision your virtual device, you should ensure that the information is destroyed following secure procedures.

VirtualMFADeviceName (required)

The name of the virtual MFA device. Use with path to uniquely identify a virtual MFA device.

Path (required)

The path for the virtual MFA device.

Returns Net::Amazon::IAM::VirtualMFADevice object on success or Net::Amazon::IAM::Error on fail.

This method wasn't tested

delete_virtual_MFA_device(%params)

Deletes a virtual MFA device.

Note:

You must deactivate a user's virtual MFA device before you can delete it.

SerialNumber (required)

The serial number that uniquely identifies the MFA device. For virtual MFA devices, the serial number is the same as the ARN.

Returns true on success or Net::Amazon::IAM::Error on fail.

This method wasn't tested

list_virtual_MFA_devices(%params)

Lists the virtual MFA devices under the AWS account by assignment status.

Marker (optional)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of VirtualMFADevices you want in the response. If there are additional devices beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

AssignmentStatus (optional)

The status (unassigned or assigned) of the devices to list. If you do not specify an AssignmentStatus, the action defaults to Any which lists both assigned and unassigned virtual MFA devices.

Valid Values: Assigned | Unassigned | Any

Returns Net::Amazon::IAM::MFADevices object on success or Net::Amazon::IAM::Error on fail.

enable_MFA_device(%params)

Enables the specified MFA device and associates it with the specified user name. When enabled, the MFA device is required for every subsequent login by the user name associated with the device.

AuthenticationCode1 (required)

An authentication code emitted by the device.

AuthenticationCode2 (required)

A subsequent authentication code emitted by the device.

SerialNumber (required)

The serial number that uniquely identifies the MFA device. For virtual MFA devices, the serial number is the device ARN.

UserName (required)

The name of the user for whom you want to enable the MFA device.

Returns true on success or Net::Amazon::IAM::Error on fail.

This method wasn't tested

deactivate_MFA_device(%params)

Enables the specified MFA device and associates it with the specified user name. When enabled, the MFA device is required for every subsequent login by the user name associated with the device.

SerialNumber (required)

The serial number that uniquely identifies the MFA device. For virtual MFA devices, the serial number is the device ARN.

UserName (required)

The name of the user whose MFA device you want to deactivate.

Returns true on success or Net::Amazon::IAM::Error on fail.

This method wasn't tested

list_MFA_devices(%params)

Retrieves information about the specified role.

Marker (optional)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of MFADevices you want in the response. If there are additional devices beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

UserName (optional)

The name of the user whose MFA devices you want to list.

Returns Net::Amazon::IAM::MFADevices object on success or Net::Amazon::IAM::Error on fail.

create_instance_profile(%params)

Creates a new instance profile.

InstanceProfileName (required)

The name of the instance profile to create.

Path (optional)

The path to the instance profile.

Returns Net::Amazon::IAM::InstanceProfile object on success or Net::Amazon::IAM::Error on fail. The Roles attribute of Net::Amazon::IAM::InstanceProfile object will be undef.

get_instance_profile(%params)

Retrieves information about the specified instance profile, including the instance profile's path, GUID, ARN, and role.

InstanceProfileName (required)

The name of the instance profile to get information about.

Returns Net::Amazon::IAM::InstanceProfile object on success or Net::Amazon::IAM::Error on fail.

list_instance_profiles(%params)

Lists the instance profiles that have the specified path prefix.

Marker (optional)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of instance profiles you want in the response. If there are additional instance profiles beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

PathPrefix (optional)

The path prefix for filtering the results. For example, the prefix /application_abc/component_xyz/ gets all instance profiles whose path starts with /application_abc/component_xyz/.

Returns Net::Amazon::IAM::InstanceProfiles object on success or Net::Amazon::IAM::Error on fail.

delete_instance_profile(%params)

Deletes the specified instance profile. The instance profile must not have an associated role.

InstanceProfileName (required)

The name of the instance profile to delete.

Returns true object on success or Net::Amazon::IAM::Error on fail.

add_role_to_instance_profile(%params)

Adds the specified role to the specified instance profile.

InstanceProfileName (required)

The name of the instance profile to update.

RoleName (required)

The name of the role to add.

Returns true object on success or Net::Amazon::IAM::Error on fail.

remove_role_from_instance_profile(%params)

Removes the specified role from the specified instance profile.

Important:

Make sure you do not have any Amazon EC2 instances running with the role you are about to remove from the instance profile. Removing a role from an instance profile that is associated with a running instance will break any applications running on the instance.

InstanceProfileName (required)

The name of the instance profile to update.

RoleName (required)

The name of the role to remove.

Returns true object on success or Net::Amazon::IAM::Error on fail.

list_instance_profiles_for_role(%params)

Lists the instance profiles that have the specified associated role.

RoleName (required)

The name of the role to list instance profiles for.

MaxItems (optional)

Use this parameter only when paginating results to indicate the maximum number of instance profiles you want in the response. If there are additional instance profiles beyond the maximum you specify, the IsTruncated response element is true. This parameter is optional. If you do not include it, it defaults to 100.

Marker (optional)

Use this parameter only when paginating results, and only in a subsequent request after you've received a response where the results are truncated. Set it to the value of the Marker element in the response you just received.

Returns true object on success or Net::Amazon::IAM::Error on fail.

KNOWN ISSUES

* missing some ( a lot of ) methods

* missing tests

* list_user_policies returns just an ArrayRef.

AUTHOR

Igor Tsigankov <tsiganenok@gmail.com>

COPYRIGHT

Copyright (c) 2015 Igor Tsigankov.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.