Amazon Cognito
Developer Guide

Tutorial: Integrating User Pools for iOS Apps

This tutorial helps you get started with user pools.

Step 1: Creating a User Pool for Your App by Using the Console

The following procedure describes how to create a user pool and use it in your app. This procedure creates a pool ID, an app client ID, and an app client secret using default settings. For information on customizing these settings, see User Pools Reference (AWS Management Console).

To create a user pool for your app

  1. Sign in to the Amazon Cognito console

  2. Choose Manage your User Pools.

  3. Choose Create a User Pool.

  4. In Pool name, type a name for the pool and then choose Review defaults.

  5. From the left navigation bar, choose App clients and then choose Add an app. You can create multiple app clients for a user pool.

  6. For App name, type a name for your app. Keep Generate client secret selected, choose Create app, and then choose Save changes.

  7. From the left navigation bar, choose Review and then choose Create pool.

  8. Note the pool ID. You can find the app client ID and app client secret under App clients on the left navigation bar.

Step 2: Creating a UserPool Object

Create a user pool object in your client app by using the user pool ID, app client ID, and app client secret that you obtained in step 1.

//setup service config AWSServiceConfiguration *serviceConfiguration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:nil]; //create a pool AWSCognitoIdentityUserPoolConfiguration *configuration = [[AWSCognitoIdentityUserPoolConfiguration alloc] initWithClientId:@"CLIENT_ID" clientSecret:@"CLIENT_SECRET" poolId:@"USER_POOL_ID"]; [AWSCognitoIdentityUserPool registerCognitoIdentityUserPoolWithConfiguration:serviceConfiguration userPoolConfiguration:configuration forKey:@"UserPool"]; AWSCognitoIdentityUserPool *pool = [AWSCognitoIdentityUserPool CognitoIdentityUserPoolForKey:@"UserPool"];

Step 3: Signing up Users for Your App

To sign up users, your app's registration UI must collect information from users and call signUp.

NSMutableArray * attributes = [NSMutableArray new]; //Set user attributes by retrieving them from your UI. These values are hardcoded for this example AWSCognitoIdentityUserAttributeType * phone = [AWSCognitoIdentityUserAttributeType new]; = @"phone_number"; //All phone numbers require +country code as a prefix phone.value = @"+15555555555"; AWSCognitoIdentityUserAttributeType * email = [AWSCognitoIdentityUserAttributeType new]; = @"email"; email.value = @""; [attributes addObject:phone]; [attributes addObject:email]; //set username and password by retrieving them from your UI. They are hardcoded in this example. AWSCognitoIdentityUser *user = [[pool signUp:@"username" password:@"password" userAttributes:attributes validationData:nil] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUser *> * _Nonnull task) { NSLog(@"Successfully registered user: %@",task.result.username); return nil; }];

Step 4: Confirming Users for Your App

Users are confirmed when either their email address or phone number is verified. In the following example, users receive a verification code at their email address or via SMS on their mobile phone during the registration flow and must input the code to complete sign-up. After obtaining the verification code from your end user, call confirmSignUp.

//replace VERIFICATION_CODE with the value the user inputs [[user confirmSignUp:@"VERIFICATION_CODE"] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityProviderConfirmSignUpResponse *> * _Nonnull task) { NSLog(@"Successfully confirmed user: %@",user.username); return nil; }];

Step 5: Authenticating Users for Your App

To authenticate the confirmed user, implement the AWSCognitoIdentityInteractiveAuthenticationDelegate protocol, as shown next, and set the delegate for the pool. This protocol manages your custom login UI and accepts username and password information from your end user. The protocol's methods are only invoked if the user has never authenticated, if the user has signed out, or if the user's refresh token (which is valid for 30 days) has expired.

//This code goes in your AppDelegate pool.delegate = self; -(id<AWSCognitoIdentityPasswordAuthentication>) startPasswordAuthentication{ //implement code to instantiate and display login UI here //return something that implements the AWSCognitoIdentityPasswordAuthentication protocol return loginUI; } //This code goes in your Login UI -(void) getPasswordAuthenticationDetails: (AWSCognitoIdentityPasswordAuthenticationInput *) authenticationInput passwordAuthenticationCompletionSource: (AWSTaskCompletionSource *) passwordAuthenticationCompletionSource { //using inputs from login UI create an AWSCognitoIdentityPasswordAuthenticationDetails object. //These values are hardcoded for this example. AWSCognitoIdentityPasswordAuthenticationDetails * result = [[AWSCognitoIdentityPasswordAuthenticationDetails alloc] initWithUsername:@"USERNAME" password:@"PASSWORD"]; //set the result to continue the sign-in process passwordAuthenticationDetails.result = result; }; -(void) didCompletePasswordAuthenticationStepWithError:(NSError*) error { dispatch_async(dispatch_get_main_queue(), ^{ //present error to end user if(error){ [[[UIAlertView alloc] initWithTitle:error.userInfo[@"__type"] message:error.userInfo[@"message"] delegate:nil cancelButtonTitle:nil otherButtonTitles:@"Ok", nil] show]; }else{ //dismiss view controller [self dismissViewControllerAnimated:YES completion:nil]; } }); }

Step 6: Getting User Details

To get user details, call getDetails, as shown next.

[[user getDetails] continueWithSuccessBlock:^id _Nullable(AWSTask<AWSCognitoIdentityUserGetDetailsResponse *> * _Nonnull task) { AWSCognitoIdentityUserGetDetailsResponse *response = task.result; for (AWSCognitoIdentityUserAttributeType *attribute in response.userAttributes) { //print the user attributes NSLog(@"Attribute: %@ Value: %@",, attribute.value); } return nil; }];

Step 7: Getting Credentials to Access AWS Resources For an App User

To get credentials to access AWS resources for your user, first associate your user pool with an identity pool, and then provide AWSCognitoIdentityUserPool to your AWSCognitoCredentialsProvider. The following procedure describes how to get an identity pool.

To create an identity pool

  1. Sign in to the Amazon Cognito console.

  2. Choose Manage Federated Identities.

  3. Choose Create new identity pool. Type a name for your identity pool in Identity pool name.

  4. Expand the Authentication providers section.

  5. On the Cognito tab, specify your User Pool ID and App Client ID.

  6. After you configure the identity pool association, get AWS credentials into your app by providing AWSCognitoIdentityUserPool to your AWSCognitoCredentialsProvider.

    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:@"IDENTITY_POOL_ID" identityProviderManager:pool]; AWSServiceConfiguration *defaultServiceConfiguration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:credentialsProvider]; AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = defaultServiceConfiguration;

Next Steps

For a working example demonstrating the functionality described in this tutorial, see the Objective-C sample on Github, or the Swift sample on Github.