Skip to main content

users

Creates, updates, deletes, gets or lists a users resource.

Overview​

Nameusers
TypeResource
Idaws.iam.users

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
arnstringThe 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.
create_datestringThe date and time, in ISO 8601 date-time format, when the user was created.
password_last_usedstringThe date and time, in ISO 8601 date-time format, when the user's password was last used to sign in to an Amazon Web Services website. For a list of Amazon Web Services 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.
pathstringThe path to the user. For more information about paths, see IAM identifiers in the IAM User Guide. The ARN of the policy used to set the permissions boundary for the user.
permissions_boundarystringFor more information about permissions boundaries, see Permissions boundaries for IAM identities in the IAM User Guide.
tagsstringA list of tags that are associated with the user. For more information about tagging, see Tagging IAM resources in the IAM User Guide.
user_idstringThe stable and unique string identifying the user. For more information about IDs, see IAM identifiers in the IAM User Guide.
user_namestringThe friendly name identifying the user.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_userselectUserName, regionRetrieves information about the specified IAM user, including the user's creation date, path, unique ID, and ARN. If you do not specify a user name, IAM determines the user name implicitly based on the Amazon Web Services access key ID used to sign the request to this operation.
list_usersselectregionPathPrefix, Marker, MaxItemsLists the IAM users that have the specified path prefix. If no path prefix is specified, the operation returns all users in the Amazon Web Services account. If there are none, the operation returns an empty list. IAM resource-listing operations return a subset of the available attributes for the resource. This operation does not return the following attributes, even though they are an attribute of the returned object: PermissionsBoundary Tags To view all of the information for a user, see GetUser. You can paginate the results using the MaxItems and Marker parameters.
create_userinsertUserName, regionPath, PermissionsBoundary, TagsCreates a new IAM user for your Amazon Web Services account. For information about quotas for the number of IAM users you can create, see IAM and STS quotas in the IAM User Guide.
update_userupdateUserName, regionNewPath, NewUserNameUpdates the name and/or the path of the specified IAM user. You should understand the implications of changing an IAM user's path or name. For more information, see Renaming an IAM user and Renaming an IAM group in the IAM User Guide. To change a user name, the requester must have appropriate permissions on both the source object and the target object. For example, to change Bob to Robert, the entity making the request must have permission on Bob and Robert, or must have permission on all (*). For more information about permissions, see Permissions and policies.
put_user_permissions_boundaryreplaceUserName, PermissionsBoundary, regionAdds or updates the policy that is specified as the IAM user's permissions boundary. You can use an Amazon Web Services managed policy or a customer managed policy to set the boundary for a user. Use the boundary to control the maximum permissions that the user can have. Setting a permissions boundary is an advanced feature that can affect the permissions for the user. Policies that are used as permissions boundaries do not provide permissions. You must also attach a permissions policy to the user. To learn how the effective permissions for a user are evaluated, see IAM JSON policy evaluation logic in the IAM User Guide.
delete_userdeleteUserName, regionDeletes the specified IAM user. Unlike the Amazon Web Services 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: Password (DeleteLoginProfile) Access keys (DeleteAccessKey) Signing certificate (DeleteSigningCertificate) SSH public key (DeleteSSHPublicKey) Git credentials (DeleteServiceSpecificCredential) Multi-factor authentication (MFA) device (DeactivateMFADevice, DeleteVirtualMFADevice) Inline policies (DeleteUserPolicy) Attached managed policies (DetachUserPolicy) Group memberships (RemoveUserFromGroup)
delete_user_permissions_boundaryexecUserName, regionDeletes the permissions boundary for the specified IAM user. Deleting the permissions boundary for a user might increase its permissions by allowing the user to perform all the actions granted in its permissions policies.
resync_mfa_deviceexecUserName, SerialNumber, AuthenticationCode1, AuthenticationCode2, regionSynchronizes the specified MFA device with its IAM resource object on the Amazon Web Services servers. For more information about creating and working with virtual MFA devices, see Using a virtual MFA device in the IAM User Guide.
upload_ssh_public_keyexecUserName, SSHPublicKeyBody, regionUploads an SSH public key and associates it with the specified IAM user. The SSH public key uploaded by this operation can be used only for authenticating the associated IAM user to an CodeCommit repository. For more information about using SSH keys to authenticate to an CodeCommit repository, see Set up CodeCommit for SSH connections in the CodeCommit User Guide.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
AuthenticationCode1stringAn authentication code emitted by the device. The format for this parameter is a sequence of six digits.
AuthenticationCode2stringA subsequent authentication code emitted by the device. The format for this parameter is a sequence of six digits.
PermissionsBoundarystringThe ARN of the managed policy that is used to set the permissions boundary for the user. A permissions boundary policy defines the maximum permissions that identity-based policies can grant to an entity, but does not grant permissions. Permissions boundaries do not define the maximum permissions that a resource-based policy can grant to an entity. To learn more, see Permissions boundaries for IAM entities in the IAM User Guide. For more information about policy types, see Policy types in the IAM User Guide.
SSHPublicKeyBodystringThe SSH public key. The public key must be encoded in ssh-rsa format or PEM format. The minimum bit-length of the public key is 2048 bits. For example, you can generate a 2048-bit key, and the resulting PEM file is 1679 bytes long. 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)
SerialNumberstringSerial number that uniquely identifies the MFA device. 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: _+=,.@-
UserNamestringThe name of the IAM user to associate the SSH public key with. 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: _+=,.@-
regionstringAWS region (default: us-east-1)
MarkerstringUse 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.
MaxItemsintegerUse 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.
NewPathstringNew 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.
NewUserNamestringNew 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".
PathstringThe 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.
PathPrefixstringThe 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/. This parameter is optional. If it is not included, it defaults to a slash (/), listing all user names. 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.
PermissionsBoundarystringThe ARN of the managed policy that is used to set the permissions boundary for the user. A permissions boundary policy defines the maximum permissions that identity-based policies can grant to an entity, but does not grant permissions. Permissions boundaries do not define the maximum permissions that a resource-based policy can grant to an entity. To learn more, see Permissions boundaries for IAM entities in the IAM User Guide. For more information about policy types, see Policy types in the IAM User Guide.
TagsarrayA list of tags that you want to attach to the new user. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM resources in the IAM User Guide. If any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request fails and the resource is not created.

SELECT examples​

Retrieves information about the specified IAM user, including the user's creation date, path, unique ID, and ARN. If you do not specify a user name, IAM determines the user name implicitly based on the Amazon Web Services access key ID used to sign the request to this operation.

SELECT
arn,
create_date,
password_last_used,
path,
permissions_boundary,
tags,
user_id,
user_name
FROM aws.iam.users
WHERE UserName = '{{ UserName }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new IAM user for your Amazon Web Services account. For information about quotas for the number of IAM users you can create, see IAM and STS quotas in the IAM User Guide.

INSERT INTO aws.iam.users (
UserName,
region,
Path,
PermissionsBoundary,
Tags
)
SELECT 
'{{ UserName }}',
'{{ region }}',
'{{ Path }}',
'{{ PermissionsBoundary }}',
'{{ Tags }}'
RETURNING
arn,
create_date,
password_last_used,
path,
permissions_boundary,
tags,
user_id,
user_name
;

UPDATE examples​

Updates the name and/or the path of the specified IAM user. You should understand the implications of changing an IAM user's path or name. For more information, see Renaming an IAM user and Renaming an IAM group in the IAM User Guide. To change a user name, the requester must have appropriate permissions on both the source object and the target object. For example, to change Bob to Robert, the entity making the request must have permission on Bob and Robert, or must have permission on all (*). For more information about permissions, see Permissions and policies.

UPDATE aws.iam.users
SET 
-- No updatable properties
WHERE 
UserName = '{{ UserName }}' --required
AND region = '{{ region }}' --required
AND NewPath = '{{ NewPath}}'
AND NewUserName = '{{ NewUserName}}';

REPLACE examples​

Adds or updates the policy that is specified as the IAM user's permissions boundary. You can use an Amazon Web Services managed policy or a customer managed policy to set the boundary for a user. Use the boundary to control the maximum permissions that the user can have. Setting a permissions boundary is an advanced feature that can affect the permissions for the user. Policies that are used as permissions boundaries do not provide permissions. You must also attach a permissions policy to the user. To learn how the effective permissions for a user are evaluated, see IAM JSON policy evaluation logic in the IAM User Guide.

REPLACE aws.iam.users
SET 
-- No updatable properties
WHERE 
UserName = '{{ UserName }}' --required
AND PermissionsBoundary = '{{ PermissionsBoundary }}' --required
AND region = '{{ region }}' --required;

DELETE examples​

Deletes the specified IAM user. Unlike the Amazon Web Services 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: Password (DeleteLoginProfile) Access keys (DeleteAccessKey) Signing certificate (DeleteSigningCertificate) SSH public key (DeleteSSHPublicKey) Git credentials (DeleteServiceSpecificCredential) Multi-factor authentication (MFA) device (DeactivateMFADevice, DeleteVirtualMFADevice) Inline policies (DeleteUserPolicy) Attached managed policies (DetachUserPolicy) Group memberships (RemoveUserFromGroup)

DELETE FROM aws.iam.users
WHERE UserName = '{{ UserName }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods​

Deletes the permissions boundary for the specified IAM user. Deleting the permissions boundary for a user might increase its permissions by allowing the user to perform all the actions granted in its permissions policies.

EXEC aws.iam.users.delete_user_permissions_boundary 
@UserName='{{ UserName }}' --required, 
@region='{{ region }}' --required
;
Last updated on