groups

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

Overview

Name	groups
Type	Resource
Id	aws.iam.groups

Fields

The following fields are returned by SELECT queries:

get_group

Name	Datatype	Description
arn	string	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.
create_date	string	The date and time, in ISO 8601 date-time format, when the user was created.
password_last_used	string	The 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.
path	string	The 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_boundary	string	For more information about permissions boundaries, see Permissions boundaries for IAM identities in the IAM User Guide.
tags	string	A list of tags that are associated with the user. For more information about tagging, see Tagging IAM resources in the IAM User Guide.
user_id	string	The stable and unique string identifying the user. For more information about IDs, see IAM identifiers in the IAM User Guide.
user_name	string	The friendly name identifying the user.

list_groups

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) specifying the group. For more information about ARNs and how to use them in policies, see IAM identifiers in the IAM User Guide.
create_date	string	The date and time, in ISO 8601 date-time format, when the group was created.
group_id	string	The stable and unique string identifying the group. For more information about IDs, see IAM identifiers in the IAM User Guide.
group_name	string	The friendly name that identifies the group.
path	string	The path to the group. For more information about paths, see IAM identifiers in the IAM User Guide.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_group	select	GroupName, region	Marker, MaxItems	Returns a list of IAM users that are in the specified IAM group. You can paginate the results using the MaxItems and Marker parameters.
list_groups	select	region	PathPrefix, Marker, MaxItems	Lists the IAM groups that have the specified path prefix. You can paginate the results using the MaxItems and Marker parameters.
create_group	insert	GroupName, region	Path	Creates a new group. For information about the number of groups you can create, see IAM and STS quotas in the IAM User Guide.
add_user_to_group	update	GroupName, UserName, region		Adds the specified user to the specified group.
update_group	update	GroupName, region	NewPath, NewGroupName	Updates the name and/or the path of the specified IAM group. You should understand the implications of changing a group's path or name. For more information, see Renaming users and groups in the IAM User Guide. The person making the request (the principal), must have permission to change the role group with the old name and the new name. For example, to change the group named Managers to MGRs, the principal must have a policy that allows them to update both groups. If the principal has permission to update the Managers group, but not the MGRs group, then the update fails. For more information about permissions, see Access management.
delete_group	delete	GroupName, region		Deletes the specified IAM group. The group must not contain any users or have any attached policies.
remove_user_from_group	exec	GroupName, UserName, region		Removes the specified user from the specified group.

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.

Name	Datatype	Description
GroupName	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: _+=,.@-
UserName	string	The name of the user to remove. 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: _+=,.@-
region	string	AWS region (default: us-east-1)
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.
MaxItems	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.
NewGroupName	string	New name for the IAM group. Only include this if changing the group'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".
NewPath	string	New path for the IAM group. Only include this if changing the group'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.
Path	string	The path to the group. 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.
PathPrefix	string	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/. This parameter is optional. If it is not included, it defaults to a slash (/), listing all groups. 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.

SELECT examples

get_group

Returns a list of IAM users that are in the specified IAM group. You can paginate the results using the MaxItems and Marker parameters.

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

list_groups

Lists the IAM groups that have the specified path prefix. You can paginate the results using the MaxItems and Marker parameters.

SELECT
arn,
create_date,
group_id,
group_name,
path
FROM aws.iam.groups
WHERE region = '{{ region }}' -- required
AND PathPrefix = '{{ PathPrefix }}'
AND Marker = '{{ Marker }}'
AND MaxItems = '{{ MaxItems }}'
;

INSERT examples

create_group

Creates a new group. For information about the number of groups you can create, see IAM and STS quotas in the IAM User Guide.

INSERT INTO aws.iam.groups (
GroupName,
region,
Path
)
SELECT 
'{{ GroupName }}',
'{{ region }}',
'{{ Path }}'
RETURNING
arn,
create_date,
group_id,
group_name,
path
;

Manifest

# Description fields are for documentation purposes
- name: groups
props:
  - name: GroupName
    value: "{{ GroupName }}"
    description: Required parameter for the groups resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the groups resource.
  - name: Path
    value: "{{ Path }}"
    description: The path to the group. 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.
    description: The path to the group. 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.

UPDATE examples

add_user_to_group

Adds the specified user to the specified group.

UPDATE aws.iam.groups
SET 
-- No updatable properties
WHERE 
GroupName = '{{ GroupName }}' --required
AND UserName = '{{ UserName }}' --required
AND region = '{{ region }}' --required;

update_group

Updates the name and/or the path of the specified IAM group. You should understand the implications of changing a group's path or name. For more information, see Renaming users and groups in the IAM User Guide. The person making the request (the principal), must have permission to change the role group with the old name and the new name. For example, to change the group named Managers to MGRs, the principal must have a policy that allows them to update both groups. If the principal has permission to update the Managers group, but not the MGRs group, then the update fails. For more information about permissions, see Access management.

UPDATE aws.iam.groups
SET 
-- No updatable properties
WHERE 
GroupName = '{{ GroupName }}' --required
AND region = '{{ region }}' --required
AND NewPath = '{{ NewPath}}'
AND NewGroupName = '{{ NewGroupName}}';

DELETE examples

delete_group

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

DELETE FROM aws.iam.groups
WHERE GroupName = '{{ GroupName }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

remove_user_from_group

Removes the specified user from the specified group.

EXEC aws.iam.groups.remove_user_from_group 
@GroupName='{{ GroupName }}' --required, 
@UserName='{{ UserName }}' --required, 
@region='{{ region }}' --required
;