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

Class: Aws::IAM::User

Inherits:
Resources::Resource show all
Defined in:
(unknown)

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(name, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(name, options = {}) ⇒ Object

    Parameters:

    • name (String)

    Options Hash (options):

    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :name (required, String)
    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#arn ⇒ String (readonly)

The Amazon Resource Name (ARN) that identifies the user. For more information about ARNs and how to use ARNs in policies, see IAM Identifiers in the IAM User Guide.

Returns:

  • (String) —

    The Amazon Resource Name (ARN) that identifies the user.

#create_date ⇒ Time (readonly)

The date and time, in ISO 8601 date-time format, when the user was created.

Returns:

  • (Time) —

    The date and time, in [ISO 8601 date-time format][1], when the user was created.

#name ⇒ String (readonly)

Returns:

  • (String)

#password_last_used ⇒ Time (readonly)

The date and time, in ISO 8601 date-time format, when the user\'s password was last used to sign in to an AWS website. For a list of AWS websites that capture a user\'s last sign-in time, see the Credential Reports topic in the IAM User Guide. If a password is used more than once in a five-minute span, only the first use is returned in this field. If the field is null (no value), then it indicates that they never signed in with a password. This can be because:

  • The user never had a password.

  • A password exists but has not been used since IAM started tracking this information on October 20, 2014.

A null value does not mean that the user never had a password. Also, if the user does not currently have a password but had one in the past, then this field contains the date and time the most recent password was used.

This value is returned only in the GetUser and ListUsers operations.

Returns:

  • (Time) —

    The date and time, in [ISO 8601 date-time format][1], when the user\'s password was last used to sign in to an AWS website.

#path ⇒ String (readonly)

The path to the user. For more information about paths, see IAM Identifiers in the IAM User Guide.

Returns:

  • (String) —

    The path to the user.

#permissions_boundary ⇒ Types::AttachedPermissionsBoundary (readonly)

The ARN of the policy used to set the permissions boundary for the user.

For more information about permissions boundaries, see Permissions Boundaries for IAM Identities in the IAM User Guide.

Returns:

#tags ⇒ Array<Types::Tag> (readonly)

A list of tags that are associated with the specified user. For more information about tagging, see Tagging IAM Identities in the IAM User Guide.

Returns:

  • (Array<Types::Tag>) —

    A list of tags that are associated with the specified user.

#user_id ⇒ String (readonly)

The stable and unique string identifying the user. For more information about IDs, see IAM Identifiers in the IAM User Guide.

Returns:

  • (String) —

    The stable and unique string identifying the user.

#user_name ⇒ String (readonly)

The friendly name identifying the user.

Returns:

  • (String) —

    The friendly name identifying the user.

Instance Method Details

#access_key(id) ⇒ AccessKey

Parameters:

Returns:

See Also:

#access_keys(options = {}) ⇒ Collection<AccessKey>

Returns a Collection of AccessKey resources. No API requests are made until you call an enumerable method on the collection. Client#list_access_keys will be called multiple times until every AccessKey has been yielded.

Examples:

Request syntax example with placeholder values


user.access_keys({
  marker: "markerType",
  max_items: 1,
})

Enumerating AccessKey resources.

user.access_keys.each do |accesskey|
  # yields each accesskey
end

Enumerating AccessKey resources with a limit.

user.access_keys.limit(10).each do |accesskey|
  # yields at most 10 access_keys
end

Options Hash (options):

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#add_group(options = {}) ⇒ Struct

Adds the specified user to the specified group.

Examples:

Request syntax example with placeholder values


user.add_group({
  group_name: "groupNameType", # required
})

Options Hash (options):

  • :group_name (required, String) —

    The name of the group to update.

    This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#attach_policy(options = {}) ⇒ Struct

Attaches the specified managed policy to the specified user.

You use this API to attach a managed policy to a user. To embed an inline policy in a user, use PutUserPolicy.

For more information about policies, see Managed Policies and Inline Policies in the IAM User Guide.

Examples:

Request syntax example with placeholder values


user.attach_policy({
  policy_arn: "arnType", # required
})

Options Hash (options):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#attached_policies(options = {}) ⇒ Collection<Policy>

Returns a Collection of Policy resources. No API requests are made until you call an enumerable method on the collection. Client#list_attached_user_policies will be called multiple times until every Policy has been yielded.

Examples:

Request syntax example with placeholder values


user.attached_policies({
  path_prefix: "policyPathType",
  marker: "markerType",
  max_items: 1,
})

Enumerating Policy resources.

user.attached_policies.each do |policy|
  # yields each policy
end

Enumerating Policy resources with a limit.

user.attached_policies.limit(10).each do |policy|
  # yields at most 10 attached_policies
end

Options Hash (options):

  • :path_prefix (String) —

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

    This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#create(options = {}) ⇒ User

Examples:

Request syntax example with placeholder values


user.create({
  path: "pathType",
  permissions_boundary: "arnType",
  tags: [
    {
      key: "tagKeyType", # required
      value: "tagValueType", # required
    },
  ],
})

Basic usage

user = user.create(options)
user.name
#=> "user-name"

Options Hash (options):

  • :path (String) —

    The path for the user name. For more information about paths, see IAM Identifiers in the IAM User Guide.

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

    This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.

  • :permissions_boundary (String) —

    The ARN of the policy that is used to set the permissions boundary for the user.

  • :tags (Array<Types::Tag>) —

    A list of tags that you want to attach to the newly created user. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM Identities in the IAM User Guide.

    If any one of the tags is invalid or if you exceed the allowed number of tags per user, then the entire request fails and the user is not created.

Returns:

See Also:

#create_access_key_pair ⇒ AccessKeyPair

Examples:

Request syntax example with placeholder values


user.create_access_key_pair()

Basic usage

accesskeypair = user.create_access_key_pair(options)
accesskeypair.secret
#=> "accesskeypair-secret"

Returns:

See Also:

#create_login_profile(options = {}) ⇒ LoginProfile

Examples:

Request syntax example with placeholder values


user.({
  password: "passwordType", # required
  password_reset_required: false,
})

Basic usage

loginprofile = user.(options)
loginprofile.user_name
#=> "loginprofile-user-name"

Options Hash (options):

  • :password (required, String) —

    The new password for the user.

    The regex pattern that is used to validate this parameter is a string of characters. That string can include almost any printable ASCII character from the space (\u0020) through the end of the ASCII character range (\u00FF). You can also include the tab (\u0009), line feed (\u000A), and carriage return (\u000D) characters. Any of these characters are valid in a password. However, many tools, such as the AWS Management Console, might restrict the ability to type certain characters because they have special meaning within that tool.

  • :password_reset_required (Boolean) —

    Specifies whether the user is required to set a new password on next sign-in.

Returns:

See Also:

#create_policy(options = {}) ⇒ UserPolicy

Examples:

Request syntax example with placeholder values


user.create_policy({
  policy_name: "policyNameType", # required
  policy_document: "policyDocumentType", # required
})

Basic usage

userpolicy = user.create_policy(options)
userpolicy.name
#=> "userpolicy-name"

Options Hash (options):

  • :policy_name (required, String) —

    The name of the policy document.

    This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-

  • :policy_document (required, String) —

    The policy document.

    You must provide policies in JSON format in IAM. However, for AWS CloudFormation templates formatted in YAML, you can provide the policy in JSON or YAML format. AWS CloudFormation always converts a YAML policy to JSON format before submitting it to IAM.

    The regex pattern used to validate this parameter is a string of characters consisting of the following:

    • Any printable ASCII character ranging from the space character (\u0020) through the end of the ASCII character range

    • The printable characters in the Basic Latin and Latin-1 Supplement character set (through \u00FF)

    • The special characters tab (\u0009), line feed (\u000A), and carriage return (\u000D)

Returns:

See Also:

#delete ⇒ Struct

Deletes the specified IAM user. Unlike the AWS Management Console, when you delete a user programmatically, you must delete the items attached to the user manually, or the deletion fails. For more information, see Deleting an IAM User. Before attempting to delete a user, remove the following items:

Examples:

Request syntax example with placeholder values


user.delete()

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#detach_policy(options = {}) ⇒ Struct

Removes the specified managed policy from the specified user.

A user can also have inline policies embedded with it. To delete an inline policy, use the DeleteUserPolicy API. For information about policies, see Managed Policies and Inline Policies in the IAM User Guide.

Examples:

Request syntax example with placeholder values


user.detach_policy({
  policy_arn: "arnType", # required
})

Options Hash (options):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#enable_mfa(options = {}) ⇒ MfaDevice

Examples:

Request syntax example with placeholder values


user.enable_mfa({
  serial_number: "serialNumberType", # required
  authentication_code_1: "authenticationCodeType", # required
  authentication_code_2: "authenticationCodeType", # required
})

Basic usage

mfadevice = user.enable_mfa(options)
mfadevice.serial_number
#=> "mfadevice-serial-number"

Options Hash (options):

  • :serial_number (required, String) —

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

    This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@:/-

  • :authentication_code_1 (required, String) —

    An authentication code emitted by the device.

    The format for this parameter is a string of six digits.

    Submit your request immediately after generating the authentication codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device becomes out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can resync the device.

  • :authentication_code_2 (required, String) —

    A subsequent authentication code emitted by the device.

    The format for this parameter is a string of six digits.

    Submit your request immediately after generating the authentication codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device becomes out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can resync the device.

Returns:

See Also:

#exists? ⇒ Boolean

Returns true if this User exists. Returns false otherwise.

Returns:

  • (Boolean) —

    Returns true if this User exists. Returns false otherwise.

#groups(options = {}) ⇒ Collection<Group>

Returns a Collection of Group resources. No API requests are made until you call an enumerable method on the collection. Client#list_groups_for_user will be called multiple times until every Group has been yielded.

Examples:

Request syntax example with placeholder values


user.groups({
  marker: "markerType",
  max_items: 1,
})

Enumerating Group resources.

user.groups.each do |group|
  # yields each group
end

Enumerating Group resources with a limit.

user.groups.limit(10).each do |group|
  # yields at most 10 groups
end

Options Hash (options):

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#login_profile ⇒ LoginProfile

Returns:

See Also:

#mfa_device(serial_number) ⇒ MfaDevice

Parameters:

Returns:

See Also:

#mfa_devices(options = {}) ⇒ Collection<MfaDevice>

Returns a Collection of MfaDevice resources. No API requests are made until you call an enumerable method on the collection. Client#list_mfa_devices will be called multiple times until every MfaDevice has been yielded.

Examples:

Request syntax example with placeholder values


user.mfa_devices({
  marker: "markerType",
  max_items: 1,
})

Enumerating MfaDevice resources.

user.mfa_devices.each do |mfadevice|
  # yields each mfadevice
end

Enumerating MfaDevice resources with a limit.

user.mfa_devices.limit(10).each do |mfadevice|
  # yields at most 10 mfa_devices
end

Options Hash (options):

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#policies(options = {}) ⇒ Collection<UserPolicy>

Returns a Collection of Aws::IAM::UserPolicy resources. No API requests are made until you call an enumerable method on the collection. Client#list_user_policies will be called multiple times until every Aws::IAM::UserPolicy has been yielded.

Examples:

Request syntax example with placeholder values


user.policies({
  marker: "markerType",
  max_items: 1,
})

Enumerating Aws::IAM::UserPolicy resources.

user.policies.each do |userpolicy|
  # yields each userpolicy
end

Enumerating Aws::IAM::UserPolicy resources with a limit.

user.policies.limit(10).each do |userpolicy|
  # yields at most 10 policies
end

Options Hash (options):

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#policy(name) ⇒ UserPolicy

Parameters:

Returns:

See Also:

#remove_group(options = {}) ⇒ Struct

Removes the specified user from the specified group.

Examples:

Request syntax example with placeholder values


user.remove_group({
  group_name: "groupNameType", # required
})

Options Hash (options):

  • :group_name (required, String) —

    The name of the group to update.

    This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#signing_certificate(id) ⇒ SigningCertificate

Parameters:

Returns:

See Also:

#signing_certificates(options = {}) ⇒ Collection<SigningCertificate>

Returns a Collection of SigningCertificate resources. No API requests are made until you call an enumerable method on the collection. Client#list_signing_certificates will be called multiple times until every SigningCertificate has been yielded.

Examples:

Request syntax example with placeholder values


user.signing_certificates({
  marker: "markerType",
  max_items: 1,
})

Enumerating SigningCertificate resources.

user.signing_certificates.each do |signingcertificate|
  # yields each signingcertificate
end

Enumerating SigningCertificate resources with a limit.

user.signing_certificates.limit(10).each do |signingcertificate|
  # yields at most 10 signing_certificates
end

Options Hash (options):

  • :marker (String) —

    Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.

  • :max_items (Integer) —

    Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true.

    If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.

Returns:

See Also:

#update(options = {}) ⇒ User

Examples:

Request syntax example with placeholder values


user.update({
  new_path: "pathType",
  new_user_name: "userNameType",
})

Basic usage

user = user.update(options)
user.name
#=> "user-name"

Options Hash (options):

  • :new_path (String) —

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

    This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.

  • :new_user_name (String) —

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

    IAM user, group, role, and policy names must be unique within the account. Names are not distinguished by case. For example, you cannot create resources named both \"MyResource\" and \"myresource\".

Returns:

See Also:

#wait_until_exists {|waiter| ... } ⇒ User

Waits until this User is exists. This method waits by polling Client#get_user until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 1
#max_attempts 20

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

user.wait_until_exists

Yield Parameters:

Returns:

  • (User) —

    Returns a copy of this User that is not loaded.

Raises:

See Also: