groups

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

Overview

Name	groups
Type	Resource
Id	aws.cognito_idp.groups

Fields

The following fields are returned by SELECT queries:

get_group

Name	Datatype	Description
creation_date	string (date-time)	The date and time when the item was created. Amazon Cognito returns this timestamp in UNIX epoch time format. Your SDK might render the output in a human-readable format like ISO 8601 or a Java Date object.
description	string	A friendly description of the group.
group_name	string	The name of the group. (pattern: <code>[\p{L}\p{M}\p{S}\p{N}\p{P}]+</code>)
last_modified_date	string (date-time)	The date and time when the item was modified. Amazon Cognito returns this timestamp in UNIX epoch time format. Your SDK might render the output in a human-readable format like ISO 8601 or a Java Date object.
precedence	integer	A non-negative integer value that specifies the precedence of this group relative to the other groups that a user can belong to in the user pool. Zero is the highest precedence value. Groups with lower Precedence values take precedence over groups with higher ornull Precedence values. If a user belongs to two or more groups, it is the group with the lowest precedence value whose role ARN is given in the user's tokens for the cognito:roles and cognito:preferred_role claims. Two groups can have the same Precedence value. If this happens, neither group takes precedence over the other. If two groups with the same Precedence have the same role ARN, that role is used in the cognito:preferred_role claim in tokens for users in each group. If the two groups have different role ARNs, the cognito:preferred_role claim isn't set in users' tokens. The default Precedence value is null.
role_arn	string	The ARN of the IAM role associated with the group. If a group has the highest priority of a user's groups, users who authenticate with an identity pool get credentials for the RoleArn that's associated with the group. (pattern: <code>arn:[\w+=/,.@-]+:[\w+=/,.@-]+:([\w+=/,.@-]*)?:[0-9]+:[\w+=/,.@-]+(:[\w+=/,.@-]+)?(:[\w+=/,.@-]+)?</code>)
user_pool_id	string	The ID of the user pool that contains the group. (pattern: <code>[\w-]+_[0-9a-zA-Z]+</code>)

list_groups

Name	Datatype	Description
creation_date	string (date-time)	The date and time when the item was created. Amazon Cognito returns this timestamp in UNIX epoch time format. Your SDK might render the output in a human-readable format like ISO 8601 or a Java Date object.
description	string	A friendly description of the group.
group_name	string	The name of the group. (pattern: <code>[\p{L}\p{M}\p{S}\p{N}\p{P}]+</code>)
last_modified_date	string (date-time)	The date and time when the item was modified. Amazon Cognito returns this timestamp in UNIX epoch time format. Your SDK might render the output in a human-readable format like ISO 8601 or a Java Date object.
precedence	integer	A non-negative integer value that specifies the precedence of this group relative to the other groups that a user can belong to in the user pool. Zero is the highest precedence value. Groups with lower Precedence values take precedence over groups with higher ornull Precedence values. If a user belongs to two or more groups, it is the group with the lowest precedence value whose role ARN is given in the user's tokens for the cognito:roles and cognito:preferred_role claims. Two groups can have the same Precedence value. If this happens, neither group takes precedence over the other. If two groups with the same Precedence have the same role ARN, that role is used in the cognito:preferred_role claim in tokens for users in each group. If the two groups have different role ARNs, the cognito:preferred_role claim isn't set in users' tokens. The default Precedence value is null.
role_arn	string	The ARN of the IAM role associated with the group. If a group has the highest priority of a user's groups, users who authenticate with an identity pool get credentials for the RoleArn that's associated with the group. (pattern: <code>arn:[\w+=/,.@-]+:[\w+=/,.@-]+:([\w+=/,.@-]*)?:[0-9]+:[\w+=/,.@-]+(:[\w+=/,.@-]+)?(:[\w+=/,.@-]+)?</code>)
user_pool_id	string	The ID of the user pool that contains the group. (pattern: <code>[\w-]+_[0-9a-zA-Z]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_group	select	region		Given a user pool ID and a group name, returns information about the user group. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints
list_groups	select	region		Given a user pool ID, returns user pool groups and their details. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints
create_group	insert	region, GroupName, UserPoolId		Creates a new group in the specified user pool. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints
update_group	update	region, GroupName, UserPoolId		Given the name of a user pool group, updates any of the properties for precedence, IAM role, or description. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints
delete_group	delete	region		Deletes a group from the specified user pool. When you delete a group, that group no longer contributes to users' cognito:preferred_group or cognito:groups claims, and no longer influence access-control decision that are based on group membership. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

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
region	string	AWS region (default: us-east-1)

SELECT examples

get_group

Given a user pool ID and a group name, returns information about the user group. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

SELECT
creation_date,
description,
group_name,
last_modified_date,
precedence,
role_arn,
user_pool_id
FROM aws.cognito_idp.groups
WHERE region = '{{ region }}' -- required
;

list_groups

Given a user pool ID, returns user pool groups and their details. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

SELECT
creation_date,
description,
group_name,
last_modified_date,
precedence,
role_arn,
user_pool_id
FROM aws.cognito_idp.groups
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_group

Creates a new group in the specified user pool. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

INSERT INTO aws.cognito_idp.groups (
GroupName,
UserPoolId,
Description,
RoleArn,
Precedence,
region
)
SELECT 
'{{ GroupName }}' /* required */,
'{{ UserPoolId }}' /* required */,
'{{ Description }}',
'{{ RoleArn }}',
{{ Precedence }},
'{{ region }}'
RETURNING
group
;

Manifest

# Description fields are for documentation purposes
- name: groups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the groups resource.
  - name: GroupName
    value: "{{ GroupName }}"
    description: |
      A name for the group. This name must be unique in your user pool.
  - name: UserPoolId
    value: "{{ UserPoolId }}"
    description: |
      The ID of the user pool where you want to create a user group.
  - name: Description
    value: "{{ Description }}"
    description: |
      A description of the group that you're creating.
  - name: RoleArn
    value: "{{ RoleArn }}"
    description: |
      The Amazon Resource Name (ARN) for the IAM role that you want to associate with the group. A group role primarily declares a preferred role for the credentials that you get from an identity pool. Amazon Cognito ID tokens have a cognito:preferred_role claim that presents the highest-precedence group that a user belongs to. Both ID and access tokens also contain a cognito:groups claim that list all the groups that a user is a member of.
  - name: Precedence
    value: {{ Precedence }}
    description: |
      A non-negative integer value that specifies the precedence of this group relative to the other groups that a user can belong to in the user pool. Zero is the highest precedence value. Groups with lower Precedence values take precedence over groups with higher or null Precedence values. If a user belongs to two or more groups, it is the group with the lowest precedence value whose role ARN is given in the user's tokens for the cognito:roles and cognito:preferred_role claims. Two groups can have the same Precedence value. If this happens, neither group takes precedence over the other. If two groups with the same Precedence have the same role ARN, that role is used in the cognito:preferred_role claim in tokens for users in each group. If the two groups have different role ARNs, the cognito:preferred_role claim isn't set in users' tokens. The default Precedence value is null. The maximum Precedence value is 2^31-1.

UPDATE examples

update_group

Given the name of a user pool group, updates any of the properties for precedence, IAM role, or description. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

UPDATE aws.cognito_idp.groups
SET 
GroupName = '{{ GroupName }}',
UserPoolId = '{{ UserPoolId }}',
Description = '{{ Description }}',
RoleArn = '{{ RoleArn }}',
Precedence = {{ Precedence }}
WHERE 
region = '{{ region }}' --required
AND GroupName = '{{ GroupName }}' --required
AND UserPoolId = '{{ UserPoolId }}' --required
RETURNING
group;

DELETE examples

delete_group

Deletes a group from the specified user pool. When you delete a group, that group no longer contributes to users' cognito:preferred_group or cognito:groups claims, and no longer influence access-control decision that are based on group membership. For more information about user pool groups, see Adding groups to a user pool. Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy. Learn more Signing Amazon Web Services API Requests Using the Amazon Cognito user pools API and user pool endpoints

DELETE FROM aws.cognito_idp.groups
WHERE region = '{{ region }}' --required
;