Amazon Cognito - Developer Guide

209 Pages·2017·1.51 MB·English

Amazon Cognito
Developer Guide
Amazon Cognito Developer Guide
Amazon Cognito: Developer Guide
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
Amazon Cognito Developer Guide
Table of Contents
What is Amazon Cognito?................................................................................................................... 1
Features of Amazon Cognito ....................................................................................................... 2
Getting started with Amazon Cognito ........................................................................................... 2
Regional availability................................................................................................................... 3
Pricing for Amazon Cognito ........................................................................................................ 3
Using the Amazon Cognito console .............................................................................................. 3
Getting started with Amazon Cognito................................................................................................... 6
Get an AWS account and your root user credentials ........................................................................ 6
Creating an IAM user .................................................................................................................. 7
Signing in as an IAM user........................................................................................................... 8
Creating IAM user access keys ...................................................................................................... 8
Common Amazon Cognito scenarios ................................................................................................... 10
Authenticate with a user pool.................................................................................................... 10
Access your server-side resources............................................................................................... 10
Access resources with API Gateway and Lambda ........................................................................... 11
Access AWS services with a user pool and an identity pool ............................................................ 12
Authenticate with a third party and access AWS services with an identity pool .................................. 12
Access AWS AppSync resources with Amazon Cognito ................................................................... 13
Tutorials.......................................................................................................................................... 14
Creating a user pool ................................................................................................................. 14
Related Resources............................................................................................................ 15
Creating an identity pool .......................................................................................................... 15
Related resources............................................................................................................. 15
Cleaning up your AWS resources ................................................................................................ 15
Integrating with apps....................................................................................................................... 17
Amazon Cognito authentication with the AWS Amplify framework ................................................. 17
Authentication with amazon-cognito-identity-js ........................................................................... 17
Authentication with AWS SDKs .................................................................................................. 18
Multi-tenant application best practices ............................................................................................... 19
User-pool-based multi-tenancy.................................................................................................. 19
App-client-based multi-tenancy................................................................................................. 20
Group-based multi-tenancy....................................................................................................... 20
Custom-attribute-based multi-tenancy........................................................................................ 20
Multi-tenancy security recommendations..................................................................................... 20
Amazon Cognito user pools ............................................................................................................... 22
Getting started with user pools.................................................................................................. 23
Prerequisite: Sign up for an AWS account ............................................................................ 23
Step 1. Create a user pool ................................................................................................. 23
Step 2. Add an app client and set up the hosted UI .............................................................. 25
Step 3. Add social sign-in to a user pool (optional) ............................................................... 28
Step 4. Add sign-in with a SAML identity provider to a user pool (optional) .............................. 34
Next steps....................................................................................................................... 36
Using the APIs......................................................................................................................... 37
User pool API authentication............................................................................................. 38
Updating a user pool................................................................................................................ 43
Updating a user pool with the Amazon Cognito API or AWS CLI .............................................. 44
Using the hosted UI.................................................................................................................. 45
Setting up the hosted UI with AWS Amplify ........................................................................ 45
Setting up the hosted UI with the Amazon Cognito console ................................................... 45
Configuring an app client.................................................................................................. 49
Configuring a domain....................................................................................................... 54
Customizing the built-in webpages ..................................................................................... 60
How to use the hosted UI ................................................................................................. 64
Defining resource servers .................................................................................................. 76
iii
Amazon Cognito Developer Guide
Adding sign-in through a third party.......................................................................................... 79
How federated sign-in works in Amazon Cognito user pools .................................................. 79
Adding social identity providers ......................................................................................... 81
Adding SAML providers ..................................................................................................... 88
Adding OIDC providers ...................................................................................................... 99
Specifying attribute mappings ......................................................................................... 106
Linking federated users to an existing user profile .............................................................. 110
Using Lambda triggers............................................................................................................ 111
Important considerations................................................................................................. 112
Adding a user pool trigger ............................................................................................... 114
User pool Lambda trigger event ....................................................................................... 115
User pool Lambda trigger common parameters .................................................................. 115
Lambda trigger sources ................................................................................................... 116
Pre sign-up Lambda trigger ............................................................................................. 118
Post confirmation Lambda trigger .................................................................................... 124
Pre authentication Lambda trigger ................................................................................... 127
Post authentication Lambda trigger .................................................................................. 130
Challenge Lambda triggers.............................................................................................. 133
Pre token generation Lambda trigger ................................................................................ 143
Migrate user Lambda trigger............................................................................................ 147
Custom message Lambda trigger...................................................................................... 151
Custom sender Lambda triggers....................................................................................... 156
Using Amazon Pinpoint analytics .............................................................................................. 166
Find Amazon Cognito and Amazon Pinpoint Region mappings .............................................. 166
Integrating your app with Amazon Pinpoint ....................................................................... 169
Managing users...................................................................................................................... 170
Signing up and confirming user accounts ........................................................................... 170
Creating users as administrator ........................................................................................ 180
Adding groups to a user pool ........................................................................................... 185
Managing and searching for users .................................................................................... 188
Recovering user accounts ................................................................................................. 192
Importing users into a user pool ...................................................................................... 193
Email settings........................................................................................................................ 205
Default email functionality .............................................................................................. 205
Amazon SES email configuration ...................................................................................... 205
Configuring the email account ......................................................................................... 207
SMS message settings ............................................................................................................. 211
Setting up SMS messaging for the first time in Amazon Cognito user pools ............................ 211
Using tokens.......................................................................................................................... 216
Using the ID token ......................................................................................................... 216
Using the access token .................................................................................................... 219
Using the refresh token ................................................................................................... 220
Revoking tokens............................................................................................................. 221
Verifying a JSON web token ............................................................................................ 223
Caching tokens............................................................................................................... 226
Accessing resources after sign-in .............................................................................................. 227
Accessing server-side resources .......................................................................................... 10
Accessing resources with API Gateway and Lambda ............................................................. 228
Accessing AWS resources using an identity pool ................................................................. 229
Using security features ............................................................................................................ 232
Adding MFA................................................................................................................... 232
Adding advanced security ................................................................................................ 240
AWS WAF Web ACLs ....................................................................................................... 250
Case sensitivity............................................................................................................... 253
User pools console reference ................................................................................................... 254
User pool name.............................................................................................................. 255
Users and groups ........................................................................................................... 255
iv
Amazon Cognito Developer Guide
Attributes...................................................................................................................... 255
Password requirements................................................................................................... 263
Admin create user policy ................................................................................................. 264
Deletion protection......................................................................................................... 264
Email or phone verification .............................................................................................. 265
Message customizations.................................................................................................. 268
Tags.............................................................................................................................. 272
Devices.......................................................................................................................... 272
App clients.................................................................................................................... 273
Triggers......................................................................................................................... 276
Review settings.............................................................................................................. 276
Analytics........................................................................................................................ 276
App client settings .......................................................................................................... 277
Domain name................................................................................................................ 279
UI customization............................................................................................................ 280
Resource servers............................................................................................................. 281
Identity providers........................................................................................................... 282
Attribute mapping .......................................................................................................... 288
Managing error responses ........................................................................................................ 290
User creation and authentication operations ...................................................................... 290
Password reset operations ............................................................................................... 293
Confirmation operations.................................................................................................. 293
Amazon Cognito identity pools ........................................................................................................ 294
Getting started with identity pools ........................................................................................... 294
Sign up for an AWS account ............................................................................................ 295
Create an identity pool in Amazon Cognito ........................................................................ 295
Install the Mobile or JavaScript SDK ................................................................................. 296
Integrate the identity providers ........................................................................................ 296
Get credentials............................................................................................................... 296
Using identity pools ................................................................................................................ 296
User IAM roles ............................................................................................................... 297
Authenticated and unauthenticated identities.................................................................... 297
Enable or disable unauthenticated identities...................................................................... 297
Change the role associated with an identity type ................................................................ 298
Enable or edit authentication providers ............................................................................. 298
Delete an identity pool ................................................................................................... 299
Delete an identity from an identity pool ........................................................................... 299
Using Amazon Cognito Sync with identity pools ................................................................. 299
Identity pools concepts ........................................................................................................... 301
Identity pools authentication flow .................................................................................... 301
IAM roles....................................................................................................................... 306
Role trust and permissions .............................................................................................. 311
Using attributes for access control ............................................................................................ 312
Using attributes for access control with Amazon Cognito identity pools ................................. 313
Using attributes for access control policy example .............................................................. 314
Disable attributes for access control .................................................................................. 315
Default provider mappings .............................................................................................. 316
Role-based access control ........................................................................................................ 317
Creating roles for role mapping ........................................................................................ 317
Granting pass role permission .......................................................................................... 317
Using tokens to assign roles to users ................................................................................ 318
Using rule-based mapping to assign roles to users .............................................................. 318
Token claims to use in rule-based mapping ........................................................................ 320
Best practices for role-based access control ....................................................................... 321
Getting credentials................................................................................................................. 321
Android ......................................................................................................................... 321
iOS - Objective-C ............................................................................................................ 322
v
Amazon Cognito Developer Guide
iOS - Swift .................................................................................................................... 323
JavaScript...................................................................................................................... 324
Unity............................................................................................................................. 325
Xamarin......................................................................................................................... 326
Accessing AWS services ........................................................................................................... 327
Android ......................................................................................................................... 327
iOS - Objective-C ............................................................................................................ 327
iOS - Swift .................................................................................................................... 327
JavaScript...................................................................................................................... 328
Unity............................................................................................................................. 328
Xamarin......................................................................................................................... 328
Identity pools external identity providers ................................................................................... 328
Facebook....................................................................................................................... 329
Login with Amazon ......................................................................................................... 334
Google.......................................................................................................................... 337
Sign in with Apple.......................................................................................................... 343
Open ID Connect providers .............................................................................................. 347
SAML identity providers .................................................................................................. 349
Developer authenticated identities ............................................................................................ 351
Understanding the authentication flow ............................................................................. 351
Define a developer provider name and associate it with an identity pool ................................ 351
Implement an identity provider ........................................................................................ 352
Updating the logins map (Android and iOS only) ................................................................ 357
Getting a token (server side) ............................................................................................ 358
Connect to an existing social identity ................................................................................ 359
Supporting transition between providers ........................................................................... 359
Switching identities................................................................................................................ 362
Android ......................................................................................................................... 362
iOS - objective-C ............................................................................................................ 362
iOS - swift ..................................................................................................................... 363
JavaScript...................................................................................................................... 363
Unity............................................................................................................................. 364
Xamarin......................................................................................................................... 364
Amazon Cognito Sync ..................................................................................................................... 365
Getting started with Amazon Cognito Sync ................................................................................ 365
Sign up for an AWS account ............................................................................................ 365
Set up an identity pool in Amazon Cognito ........................................................................ 366
Store and sync data ........................................................................................................ 366
Synchronizing data................................................................................................................. 366
Initializing the Amazon Cognito Sync client ....................................................................... 366
Understanding datasets................................................................................................... 368
Reading and writing data in datasets ................................................................................ 369
Synchronizing local data with the sync store ...................................................................... 371
Handling callbacks.................................................................................................................. 373
Android ......................................................................................................................... 373
iOS - Objective-C ............................................................................................................ 375
iOS - Swift .................................................................................................................... 377
JavaScript...................................................................................................................... 379
Unity............................................................................................................................. 381
Xamarin......................................................................................................................... 383
Push sync.............................................................................................................................. 385
Create an Amazon Simple Notification Service (Amazon SNS) app ......................................... 385
Enable push sync in the Amazon Cognito console ............................................................... 385
Use push sync in your app: Android .................................................................................. 386
Use push sync in your app: iOS - Objective-C ..................................................................... 387
Use push sync in your app: iOS - Swift .............................................................................. 389
Amazon Cognito Streams ........................................................................................................ 391
vi
Amazon Cognito Developer Guide
Amazon Cognito Events .......................................................................................................... 393
Security......................................................................................................................................... 397
Data protection...................................................................................................................... 397
Data encryption............................................................................................................. 398
Identity and access management .............................................................................................. 398
Audience....................................................................................................................... 399
Authenticating with identities.......................................................................................... 399
Managing access using policies ......................................................................................... 401
How Amazon Cognito works with IAM ............................................................................... 403
Identity-based policy examples ........................................................................................ 409
Troubleshooting............................................................................................................. 412
Using service-linked roles ................................................................................................ 414
Authentication............................................................................................................... 417
Logging and monitoring.......................................................................................................... 424
Tracking quotas and usage in CloudWatch and Service Quotas ............................................. 424
Logging Amazon Cognito API calls with AWS CloudTrail ...................................................... 431
Compliance validation............................................................................................................. 444
Resilience.............................................................................................................................. 444
Regional data considerations ............................................................................................ 445
Infrastructure security............................................................................................................. 445
Configuration and vulnerability analysis .................................................................................... 445
AWS managed policies ............................................................................................................ 446
Policy updates................................................................................................................ 446
Tagging resources........................................................................................................................... 448
Supported resources............................................................................................................... 448
Tag restrictions...................................................................................................................... 448
Managing tags with the console ............................................................................................... 449
AWS CLI examples .................................................................................................................. 449
Assigning tags................................................................................................................ 449
Viewing tags.................................................................................................................. 450
Removing tags............................................................................................................... 451
Applying tags when you create resources .......................................................................... 451
API actions............................................................................................................................ 452
API actions for user pool tags .......................................................................................... 452
API actions for identity pool tags ..................................................................................... 452
Quotas.......................................................................................................................................... 453
Understanding API request rate quotas ..................................................................................... 453
Quota categorization...................................................................................................... 453
Amazon Cognito user pools API operations with special request rate handling ........................ 453
Monthly active users ....................................................................................................... 454
Managing API request rate quotas ............................................................................................ 454
Identify quota requirements ............................................................................................ 454
Optimize quotas............................................................................................................. 454
Track quota usage .......................................................................................................... 455
Requesting a quota increase ............................................................................................ 456
User pools request rate quotas ................................................................................................ 456
Identity pools request rate quotas ............................................................................................ 461
Quotas on resource number and size ........................................................................................ 462
API references................................................................................................................................ 466
Hosted UI and OIDC endpoints reference ................................................................................... 466
Authorize endpoint......................................................................................................... 467
Token endpoint.............................................................................................................. 473
UserInfo endpoint........................................................................................................... 477
Login endpoint............................................................................................................... 478
Logout endpoint............................................................................................................. 480
Revoke endpoint............................................................................................................ 482
User pools API reference ......................................................................................................... 483
vii
Amazon Cognito Developer Guide
Identity pools API reference ..................................................................................................... 483
Cognito sync API reference ...................................................................................................... 484
Document history........................................................................................................................... 485
viii
Amazon Cognito Developer Guide
What is Amazon Cognito?
Amazon Cognito provides authentication, authorization, and user management for your web and mobile
apps. Your users can sign in directly with a user name and password, or through a third party such as
Facebook, Amazon, Google or Apple.
The two main components of Amazon Cognito are user pools and identity pools. User pools are user
directories that provide sign-up and sign-in options for your app users. Identity pools enable you to
grant your users access to other AWS services. You can use identity pools and user pools separately or
together.
An Amazon Cognito user pool and identity pool used together
See the diagram for a common Amazon Cognito scenario. Here the goal is to authenticate your user, and
then grant your user access to another AWS service.
1. In the first step your app user signs in through a user pool and receives user pool tokens after a
successful authentication.
2. Next, your app exchanges the user pool tokens for AWS credentials through an identity pool.
3. Finally, your app user can then use those AWS credentials to access other AWS services such as
Amazon S3 or DynamoDB.
For more examples using identity pools and user pools, see Common Amazon Cognito
scenarios (p. 10).
Amazon Cognito is compliant with SOC 1-3, PCI DSS, ISO 27001, and is HIPAA-BAA eligible. For more
information, see AWS services in scope. See also Regional data considerations (p. 445).
Topics
• Features of Amazon Cognito (p. 2)
• Getting started with Amazon Cognito (p. 2)
1
Amazon Cognito Developer Guide
Features of Amazon Cognito
• Regional availability (p. 3)
• Pricing for Amazon Cognito (p. 3)
• Using the Amazon Cognito console (p. 3)
Features of Amazon Cognito
User pools
A user pool is a user directory in Amazon Cognito. With a user pool, your users can sign in to your web or
mobile app through Amazon Cognito, or federate through a third-party identity provider (IdP). Whether
your users sign in directly or through a third party, all members of the user pool have a directory profile
that you can access through an SDK.
User pools provide:
• Sign-up and sign-in services.
• A built-in, customizable web UI to sign in users.
• Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple, and through SAML
and OIDC identity providers from your user pool.
• User directory management and user profiles.
• Security features such as multi-factor authentication (MFA), checks for compromised credentials,
account takeover protection, and phone and email verification.
• Customized workflows and user migration through AWS Lambda triggers.
For more information about user pools, see Getting started with user pools (p. 23) and the Amazon
Cognito user pools API reference.
Identity pools
With an identity pool, your users can obtain temporary AWS credentials to access AWS services, such
as Amazon S3 and DynamoDB. Identity pools support anonymous guest users, as well as the following
identity providers that you can use to authenticate users for identity pools:
• Amazon Cognito user pools
• Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple
• OpenID Connect (OIDC) providers
• SAML identity providers
• Developer authenticated identities
To save user profile information, your identity pool needs to be integrated with a user pool.
For more information about identity pools, see Getting started with Amazon Cognito identity pools
(federated identities) (p. 294) and the Amazon Cognito identity pools API reference.
Getting started with Amazon Cognito
For a guide to top tasks and where to start, see Getting started with Amazon Cognito (p. 6).
For videos, articles, documentation, and sample apps, see Amazon Cognito developer resources.
To use Amazon Cognito, you need an AWS account. For more information, see Using the Amazon Cognito
console (p. 3).
2