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

#arnString (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 Using IAM guide.

Returns:

  • (String)

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

#create_dateTime (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.

#nameString (readonly)

Returns:

  • (String)

#password_last_usedTime (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 Using IAM 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 20th, 2014.

A null 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 actions.

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.

#pathString (readonly)

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

Returns:

  • (String)

    The path to the user.

#user_idString (readonly)

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

Returns:

  • (String)

    The stable and unique string identifying the user.

#user_nameString (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) — default: Optional

    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, it 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 (per 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 paramater allows (per 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, containing any ASCII character from the ! (\u0021) thru 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) — default: Optional

    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, it 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",
})

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 paramater allows (per 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, containing any ASCII character from the ! (\u0021) thru the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.

Returns:

See Also:

#create_access_key_pairAccessKeyPair

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 used to validate this parameter is a string of characters consisting of 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. Although any of these characters are valid in a password, note that many tools, such as the AWS Management Console, might restrict the ability to enter 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 (per 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.

    The regex pattern used to validate this parameter is a string of characters consisting of any printable ASCII character ranging from the space character (\u0020) through end of the ASCII character range as well as the printable characters in the Basic Latin and Latin-1 Supplement character set (through \u00FF). It also includes the special characters tab (\u0009), line feed (\u000A), and carriage return (\u000D).

Returns:

See Also:

#deleteStruct

Deletes the specified IAM user. The user must not belong to any groups or have any access keys, signing certificates, or attached policies.

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 (per 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 6 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 6 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) — default: Optional

    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, it 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_profileLoginProfile

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) — default: Optional

    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, it 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) — default: Optional

    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, it 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 (per 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) — default: Optional

    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, it 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 paramater allows (per 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, containing any ASCII character from the ! (\u0021) thru 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.

    This parameter allows (per 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:

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: