AWS News Blog

New – Amazon Cognito Groups and Fine-Grained Role-Based Access Control

One of the challenges in building applications has been around user authentication and management.  Let’s face it, not many developers want to build yet another user identification and authentication system for their application nor would they want to cause a user to create yet another account unless needed.  Amazon Cognito makes it simpler for developers to manage user identities, authentication, and permissions in order to access their applications’ data and back end systems.  Now, if only there were a service feature to make it even easier for developers to assign different permissions to different users of their applications.

Today we are excited to announce Cognito User Pools support for groups and Cognito Federated Identities support for fine-grained Role-Based Access Control (RBAC).  With Groups support in Cognito, developers can easily customize users’ app experience by creating groups which represent different user types and app usage permissions.  Developers have the ability to add users and remove users from groups and manage group permissions for sets of users.

Speaking of permissions, support for fine-grained Role-Based Access Control (RBAC) in Cognito Federated Identities allows developers to now assign different IAM roles to different authenticated users.  Previously, Amazon Cognito only supported one IAM role for all authenticated users.  With fine-grained RBAC, a developer can map federated users to different IAM roles; this functionality is available for both user authentication using existing identity providers like Facebook or Active Directory and using Cognito User Pools.

Groups in Cognito User Pools

The best way to examine the new Cognito group feature is take a walkthrough of creating a new group in the Amazon Cognito console and adding users to the different group types.

Cognito - UserPoolCreateGroup


After selecting my user pool, TestAppPool, I see the updated menu item; Users and groups.  Upon selection of the menu option, a panel is presented with tabs for both User and Groups.  To create my new group, I select the Create group button.

A dialog box will open to allow for the creation of my group.  Here I will create a group for admin users named AdminGroup.  I will fill in the name for the group, provide a description for the group, and setting the order of precedence the group is ready to be created.  Note that setting the numerical precedence a group determine which group permission is prioritized and therefore utilized for users that have been assigned to multiple groups.  The lower the numerical precedence the higher the prioritization of the group to be used by the user.  Since this is my AdminGroup, I will give this group the precedence of zero (0).  After I click the Create group button, I have successfully created my user pool group.

Cognito - CreateGroupDialog-s

Now all that is left to do is add my user(s) to the group. In my test app pool, I have two (2) users; TestAdminUser and TestUnregisteredUser as shown below. I will add my TestAdminUser to my newly created group.

Cognito - Users

To add my user to the AdminGroup user pool group, I simply go into the Groups tab and select my AdminGroup.  Once the AdminGroup details screen is shown, a click of the Add users button will bring up a dialog box displaying users within my user pool.  Adding a user to this group is a straightforward process, which only requires me to selecting the plus symbol next to the username desired to be added.  Once I receive the confirmation that the user has been added to the group, the process is complete.

As you can see from the walkthrough is easy for a developer to create groups in user pools. Groups can be created and managed groups in a user pool from the AWS management console, the APIs, and the CLI. As a developer you can create, read, update, delete, and list the groups for a user pool using AWS Credentials. Each user pool can contain up to 25 groups.  Additionally, you can add users and remove users from groups within a user pool, and you can use groups to control permissions to access your resources in AWS by assigning an AWS IAM roles for the groups.  You can also use Amazon Cognito combined with Amazon API Gateway to control permissions to your own back end resources.

Cognito - AddUsersAdminGroup - small


Fine-grained Role-Based Access Control in Cognito Federated Identities

Let’s now dig into the Cognito Federated Identities’ feature, fine-grained Role-Based Access Control, which we will refer to going forward as RBAC. Before we dive into to RBAC, let do a quick review of features of Cognito Federated Identities.  Cognito Identity assigns users a set of temporary, limited privilege credentials to access the AWS resources from your application without having to use AWS account credentials. The permissions for each user are controlled through AWS IAM roles that you create.

At this point let’s journey into RBAC by doing another walkthrough in the management console.  Once in the console and selected the Cognito service, we will now select Federated Identities.  I think it would be best to show Cognito user pools and Federated Identities in action while examining RBAC, so I am going to create a new identity pool that utilizes Cognito user pools as its authentication provider.  To create a new pool, I will first enter a name for my identity pool and select the Enable access to unauthenticated identities checkbox.  Then under Authentication Providers, I will select the Cognito tab so that I can enter my TestAppPool user pool ID and the app client ID.  Please note, that you must have created an app (app client) within your Cognito user pool in order to obtain the app client ID and to allow the app leveraging the Cognito identity pool to access the associated user pool.

Cognito - CreateIdentityPool

Now that we have created our identity pool, let’s assign role-based access for the Cognito user pool authentication method.  The simplest way to assign different roles is by defining rules in a Cognito identity pool.  Each rule specifies a user attribute or as noted in the console, a claim.  A claim is simply a value in a token for that attribute that will be matched by the rule and associated to a specific IAM role.

In order to truly show the benefit of RBAC, I will need a role for our Test App that gives users that are in the Engineering department access to put objects in S3 and access DynamoDB.  In order to create this role, I first have to create a policy with PutObject access to S3 and GetItem, Query, Scan, and BatchGetItem access to DynamoDB. Let’s call this policy, TestAppEngineerPolicy.  After constructing the aforementioned policy, I will create an IAM role named, EngineersRole, which will leverage this policy.

At this point we have a role with fine grained access to AWS resources, so let’s return to our Cognito identity pool.  Click Edit identity pool and drop down the section for Authentication providers.  Since the authentication provider for our identity pool is a Cognito user pool, we will select the Cognito tab.  Since we are establishing fine-grained RBAC for the federated identity, I will focus my attention to the Authenticated role selection section of the Authentication provider to define a rule.  In this section, click the drop down and select the option Choose role with rules.

Cognito - AuthenticationProvider

We will now setup rule with a claim (an attribute), a value to match, and the specific IAM role, EngineersRole.. For our example, the rule I am creating will assign our specific IAM role, i.e. EngineersRole, to any users authenticated in our Cognito user pool with a department attribute set as ‘Engineering’. Please note: The department attribute that we are basing our rule on, is a custom attribute that I created in our user pool, TestAppPool, as shown in graphic below.

Cognito - CustomAttributes - small

Now that we have that cleared up, let’s focus back on the creation of our rule.  For the claim, I will type the aforementioned custom attribute, department.  This rule will be applicable when the value of department is equal to the string “Engineering”, therefore, in the Match Type field I will select the Equals match type.  Finally, I will type the actual string value, “Engineering”, for the attribute value that should be matched in the rule.  If a user has a matching value for the department attribute, they can assume the EngineersRole IAM role when they get credentials. After completing this and clicking the Save Changes button, I have successfully created rule that allows for users that are authenticated with our Cognito user pool who are in the Engineering department to have different permissions than other authenticated users using the application.

Cognito - AuthenticationRoleSelection

Since we’ve completed our walkthrough of setting up a rule to assign different roles in a Cognito identity pool, let us discuss some key points to remember about fine-grained RBAC.  Firstly, rules are defined with an order and the IAM role for the first matching rule will be applied. Secondly to set up RBAC, you can define rules or leverage the roles passed via the ID token that was assigned by the user pool. For each authentication provider configured in your identity pool, there is a maximum of a total of 25 rules that can be created. Additionally, user permissions are controlled via AWS IAM roles that you create.

Pricing and Availability

Developers can get started right away to take advantage of these exciting new features.  Learn more about these new features and the other benefits of leveraging the Amazon Cognito service by visiting our developer resources page.

Great news is that there is no additional cost for using groups within a user pool. You pay only for Monthly Active Users (MAUs) after the free tier. Also remember that using the Cognito Federated Identities feature for controlling user permissions and generating unique identifiers is always free with Amazon Cognito.  See the Amazon Cognito pricing page for more information.


Tara Walker

Tara Walker

Tara was a Technical Evangelist for Amazon Web Services, dedicating her time to help developers build apps, games, and technical solutions in the AWS cloud. Tara worked on evangelizing AWS cloud computing architectures and development for various technologies like Mobile, Gaming, IoT, AI, Serverless just to name a few. Tara’s background is as a software engineer & developer who has worked on wide-ranging development platforms and systems while leveraging a myriad of development languages across her various technical and engineering roles. Over her 20+ year career, she has been employed by Microsoft, Turner Broadcasting/Time Warner, Georgia Pacific, and various other Fortune 500 companies. She holds a Bachelor’s degree from Georgia State University, and currently working on her Master’s degree in Computer Science (MSCS) at Georgia Institute of Technology. Tara's passion is to continue spreading the “good news” to diverse audiences about a plethora of technologies, development languages, and frameworks with a focus and proficiency in: - Cloud computing and Serverless architectures - IoT (Internet of Things) development - Mobile, Game, and Web development - Artificial Intelligence services and frameworks - NUI (Natural User Interfaces) & Biometric Interface service frameworks - Cross-Platform development frameworks You can find Tara on Twitter at @taraw.