Identity Management for Your Users and Apps: A Deep Dive on Amazon Cognito - SID332 - re:Invent 2017

© 2017, Amazon Web Services, Inc. or its Affiliates. All rights reserved.
Identity Management for Your
Users and Apps:
A Deep Dive on Amazon Cognito
Dav i d Be hro o zi , Se ni o r So f tw are E ngi ne e r
Sanj e e v K ri s hnan, P ri nci pal So f tw are E ngi ne e r
N o v e m b e r 3 0 , 2 0 1 7
S I D 3 3 2

What to Expect from This Session
• Amazon Cognito overview
• Use Cases
• Secure authentication and authorization
• Simple hosted UI, identity provider federation, and user
migration
• Flexible app integration with custom authentication flows and
UIs
• Demo
• Summary and additional resources

Minimize user friction Prepare for success (scale)Put security first
Identity Is Important: Get It Right
Customer
ownership
Customer
relationships
Security and
access
User experience

AWS credentials and access control OpenID Connect and OAuth 2.0-based
Managed user directory Sign in with existing
identities (federation)
Customizable, hosted UI or
SDK
Amazon Cognito

Amazon Cognito: Identity Scenarios
Business to Consumer Business to Business
Business to Employee IoT Scenarios
Enterprise
DirectoryEnterprise
Directory
SAML
Enterprise
Directory
SAML
AWS IoT

Amazon Cognito: Services
User Pools Federated Identity (Identity Pools)
• Sign up/sign in
• User profiles
• Issue tokens
• Hosted UIs
• OAuth2/OIDC
Identity Provider/Client
• SAML2 Service Provider
Federation
• Guest access
• AWS credentials

Use Amazon Cognito User Pools If
You have:
1. Users who want to create an account
2. Users who have an existing social or corporate account
You want:
1. Managed scalable and secure user directory
2. User authentication
3. User profiles
4. OpenID Connect id token, access token, and refresh token to authenticate/authorize against
your backend service
5. OAuth 2.0 flows for your app to authenticate with User Pool
6. OAuth 2.0 and SAML2 redirect/POST bindings to authenticate with identity providers
7. Integration with Amazon API Gateway

Use Amazon Cognito Identity Pools If
You have:
1. User that has authenticated with a social or corporate identity provider and has a token
2. User that is unauthenticated
You want:
1. Scoped, time-bound AWS credentials for that identity
2. Direct access to AWS services from your web or mobile app
3. Role mapping

Authentication and Access
Get AWS
credentials
Amazon
Cognito
Identity Pool
DynamoDB S3
Access AWS Services
Federating
IdP
Amazon
Cognito
User Pool
• User pools authenticate users
and vend standard tokens
• User pool tokens are used to
access backend resources
• Identity pools provide AWS
credentials to access AWS
services
Authenticate
3
CUP
Token1
IdP
Token
2
Redirect /
Post back
CUP
Token
56
Access Serverless BackendCUP
Token
API GW
4
Lambda

Secure authentication and
authorization

User Pools: Authentication Flow
• Every authentication is one or more rounds of a challenge and a
response
• Upon successful completion of the challenges, tokens are issued
• You can customize the authentication flow using an AWS Lambda
function

User Pools: Multi-Factor Authentication
• Enable additional factors to verify user identity
• Send a code via SMS, which the user enters as part of
authentication
• Request a code for a registered time-based software token
• Enhances security
• Enabled at the User Pool level, optionally configured at user level

User Pools: Multi-factor Authentication
Scenario:
• Enhance protection for security-sensitive apps
Recommendation:
• Enable multi-factor authentication on your pool. Choose required or optional
• Configure an IAM role to enable User Pools to send SMS on your behalf via SNS
• Enable phone number verification
Do
✅ Request increased spending limit for SNS
Don’t
❌ Forget the end-user experience, i.e., requiring
MFA on non-security-sensitive apps

User Pools: Device Tracking
Scenario:
• Reduce friction by avoiding user interaction for known devices
Recommendation:
• Enable Remember Device in AWS Console
• On first sign-in, the Amazon Cognito SDK will store a device identifier and secret
securely on the device
• On future sign-ins, Amazon Cognito SDK will automatically authenticate the device
• Amazon Cognito SDK enables you get user consent via callback
Do
✅ Use AdminListDevices to see users’ devices
Don’t
❌ Forget to enable MFA on your pool

User Pools: Authorization Using Groups
Scenario:
• Authorize access to backend resources and APIs using user groups
Recommendation:
• Add users to User Pool groups using Amazon Cognito console, CLI, or APIs
• Create IAM roles to associate with each User Pool group
• Amazon Cognito id token will contain the following group related claims:
• cognito:groups has all groups user belongs to
• cognito:roles has all roles for all those groups
• cognito:preferred_role has role for group with lowest precedence number
• Groups attributes from federated identity providers (i.e. SAML) can be mapped to User
Pool attributes for inclusion in the id token
Do
✅ Configure unique precedence for groups
Don’t
❌ Exceed 25 groups

Authorization With User Attributes
Scenario:
• Fine-grained authorization using user attributes and app permissions
Recommendation:
• Use access token and id token attributes for authorizing access to backend APIs
and resources
• Define resource server scopes allowed for a User Pool app client
• E.g. https://myphotosapi.example.com/photos.read
• E.g. Java Spring Security: create Authentication object with custom UserDetails
containing id token attributes. Use annotations to authorize APIs:
@PreAuthorize("hasRole('ROLE_ADMIN')")
public void adminAPI(...) {
....
}
@PreAuthorize("principal.userType == 'Premium'")
public void premiumFeatureAPI(...) {
....
}

Amazon API Gateway Authorization
Scenario:
• Fine-grained authorization for resources accessed using Amazon API Gateway
Recommendation:
• Configure User Pool authorizer in Amazon API Gateway
• Sign in user to User Pool and get Amazon Cognito tokens
• Send Amazon Cognito id token as HTTP authorization header in Amazon API
Gateway request

User Pools: Advanced Security Features Beta
Scenario:
• Protect user profiles from attackers without adding friction
Recommendation:
• Enable advanced security and risk-based Adaptive Multi-Factor
Authentication
• Adds compromised credentials detection
• Adds challenges to anomalous sign-in attempts

Advanced Security: Compromised
Credentials
Detect the reuse of compromised
credentials as users sign up, sign in, or
change their password
Choose whether to block users from reusing
compromised credentials

Advanced Security: Anomaly Detection
Detect anomalies during sign-in events:
• Sign-in from previously unseen or atypical location,
from previously unknown device
• Sign-in from IP addresses with a high number of
failed sign-in attempts
Customizable
• Set thresholds for blocking requests or requiring
MFA depending on the risk level (low, med, high)
• Define whitelist/blacklist IP addresses to exempt
from protections or block always

Advanced Security: Reporting
Alert users to suspicious sign-in attempts
View aggregate metrics in AWS CloudWatch on
the threats detected by each feature
Review activity see recent sign-in activity for
users

User Pools: Signing Out Users
Scenario:
• Sign out a user from all apps
• Sign out a user from all devices
Recommendation:
• For hosted UI: use logout URI
1. User clicks Sign Out in your app
2. App sends a request to Amazon Cognito
https://yourdomain/logout?logout_uri=...
3. Amazon Cognito removes its authentication session cookie and redirects browser
to your app’s logout_uri
• For native SDK: call GlobalSignOut API (user) or AdminUserGlobalSignOut API
(admin) to sign-out the user from all devices

Simple hosted UI, identity provider
federation, and user migration

User Pools: Hosted UI
• Fastest way to add authentication to your app
• Supports customization (logos, colors, CSS)
• Easily add social and corporate sign up/sign in
• Built-in flows for sign up, forgot password, MFA

User Pools: Hosted UI
Scenario:
Authenticate your end users with minimal development effort
Recommendation:
Use the hosted UI in conjunction with the Amazon Cognito Auth SDKs for iOS, Android, and
JS
Do
✅ Configure a sub-domain for your User Pool.
✅ Customize logos, colors and CSS.
✅ Use Amazon API Gateway to authorize
tokens and create a Serverless backend.
Don’t
❌ Use the Amazon Cognito Auth SDK if you
want a native app experience (use the AWS
Mobile SDK instead).

User Pools: Sign in with Social IDs (1)
Scenario:
• Avoid friction of asking consumer app users to register for a new account
• Enable users to use social identities to sign in to your app
• Facebook
• Gmail
• Amazon (log in with Amazon)
• Avoid developing integrations with many
identity providers
Recommendation: Configure social identity
providers in your User Pool

User Pools: Sign in with Social IDs (2)
How to set up User Pool for Facebook authentication:
1. Add Facebook as identity provider in your User Pool
• Enter your app's Facebook app ID, app secret, and Facebook scopes
(permissions) to be requested
2. Add User Pool domain URL in Facebook app’s OAuth2 Redirect URLs
3. Map Facebook attributes to User Pool attributes
• Standard + custom attributes are in id token, e.g. name, email
• Map Facebook access token so your app can call Facebook APIs
4. Configure settings for your app client
• Enable Facebook identity provider for your app client
• Set redirect URIs, OAuth2 flows and scopes ("openid" to get id token)
5. Use Amazon Cognito Auth SDK for Android / iOS / Javascript

Sign in Enterprise Users (1)
Scenario:
• Avoid friction of asking enterprise app users to register for a new account
• Enable users to use enterprise identities to sign in to your app
• SAML identity providers include Microsoft ADFS, Okta, PingFederate, etc.
• Avoid developing integrations with many enterprise directories
• Avoid development effort of implementing SAML in your app
• Constructing and parsing XML messages
• HTTP redirect and POST bindings
Recommendation: Use User Pools SAML IdP federation.

Sign in Enterprise Users (2)
How to setup User Pool for authentication with SAML enterprise identity
provider:
1. Get your enterprise identity provider’s SAML metadata URL or XML file
2. Add a SAML identity provider in your User Pool
• Enter enterprise identity provider SAML metadata URL or upload XML file
3. Add User Pool URL as SAML POST binding URL in enterprise identity provider
4. Map SAML attributes to User Pool attributes
• Standard + custom attributes are in id token, e.g. name, email
5. Configure settings for your app client
• Enable your SAML identity provider for your app client
• Set redirect URIs, OAuth 2.0 flows and scopes ("openid" to get id token)
6. Use Amazon Cognito Auth SDK for Android / iOS / Javascript

Sign in Users with Federated IdPs
Amazon
Cognito
User Pool
Federated
IdP
API GW AWS Lambda
EC2, Beanstalk, ECS
Backend Service
or App
4
6
5
3 1 7
Code or
Assertions
Tokens
8
2
Mobile or web app
Federated authentication with OAuth 2.0 authorization code or SAML flows
Sign-in
Code
IdP Token
Tokens

Do
✅ Ensure IdP identifiers are unique
Select SAML IdP with User Email
Scenario:
• Enterprise apps whose users are in multiple enterprise directories (e.g., multi-
tenanted SaaS apps)
• Enterprise identity provider can be identified by user email domain
Recommendation:
• In SAML IdP settings, provide email domains as identifiers, e.g.
“yourcustomer.com”
• Hosted UI shows a sign-in page with only email address field
• User enters email address “joe@yourcustomer.com”
• Amazon Cognito maps email domain to IdP and redirects to it
• Rest of the SAML flow is the same

User Pools: SSO Across Apps
Scenario:
You have multiple apps but want a unified user profile and to be authenticated across all
Recommendation:
• Create a single User Pool, and one app client for each app
• Each app has a client id, and different auth flows / attribute permissions
• After authentication, Amazon Cognito stores a cookie in user’s browser
• When second app redirects browser to Amazon Cognito for sign-in, Amazon Cognito
checks cookie. If valid, Amazon Cognito redirects back to your app with tokens.
Do
✅ Set allowed OAuth2 flows for each app
✅ Set attribute read/write permissions for each app

Do
✅ Provide IAM role for Amazon Cognito to write CloudWatch logs to your account
✅ Set required user attributes in CSV file
Migrating Users to User Pool: Bulk
Scenario:
• Many users in existing user directory in your app
• You want to bulk migrate to Cognito User Pool
Recommendation:
• Create a CSV file with all users, one row per user, one column per user attribute
• Must have username, verified email, or phone number attributes
• Upload CSV files using Amazon Cognito console or AWS CLI, start import job
• Track user import job using Amazon CloudWatch logs in your AWS account
• Update your mobile apps and web apps to use Amazon Cognito for sign-in
• Users will need to reset their password at first sign-in, using forgot-password
flow (verification code sent to their email/phone)

Migrating Users: Without Password Reset
Existing AppNew App
Migration
Lambda wraps
existing IdP
User Pool
Create
User
Existing
IdP
1
2
3
4
Existing
IdP
Existing app,
modified to call
Migration Lambda
after sign-in
New App
Migration
LambdaUser Pool
Create
User
1
3
4 2
Option 1 Option 2

Flexible app integration with custom
authentication flows and UIs

User Pools: Customizing with AWS Lambda
36
Category Lambda Hook Example Scenarios
Custom
Authentication
Flow
Define Auth Challenge Determines the next challenge in a custom auth flow
Create Auth Challenge Creates a challenge in a custom auth flow
Verify Auth Challenge Response Determines if a response is correct in a custom auth flow
Authentication
Events
Pre Authentication Custom validation to accept or deny the sign-in request
Post Authentication Event logging for custom analytics
Pre Token Generation Augment or suppress token claims
Sign-Up
Pre Sign-up Custom validation to accept or deny the sign-up request
Post Confirmation Custom welcome messages or event logging for custom analytics
Messages Custom Message Advanced customization and localization of messages

Token Customization with AWS Lambda
Scenario:
Part of your user profile lives in a separate system. You want to avoid a query for user
profile on every request to your backend service.
Recommendation:
Use Pre Token Generation Lambda trigger to inject additional claims into the ID token
Do
✅ Suppress claims not needed by app clients
Don’t
❌ Bloat your token (keep claims small)
❌ Exceed 5 second run time for AWS Lambda

exports.handler = function(event, context) {
// call function to generate an access code to be added to ID token
var accessCode = generateAccessCode(event.request.userAttributes['cognito:username']);
event.response = {
claimsOverrideDetails: {
claimsToAddOrOverride: {
“accessCode”: accessCode
}
}
};
context.done(null, event);
}
Token Customization with AWS Lambda

User Pools: Customizing Authentication
Scenario:
Add additional challenges into the authentication flow, e.g., secret questions, captcha
Recommendation:
• Create DefineAuthChallenge Lambda function: called in beginning and after each
challenge, determines next step (challenge name, or success/failure). Can use password /
MFA / custom challenge.
• Create CreateAuthChallenge Lambda function: creates challenge (e.g. captcha URL /
secret question) and answer, for custom challenge.
• Create VerifyAuthChallenge: called after user inputs answer, verifies answer from user;
then Amazon Cognito calls DefineAuthChallenge again.
Do
✅ Use built-in auth flows if you can
✅ Use privateChallengeParameters for answers
✅ Use high-level SDKs
Don’t
❌ Exceed 5 second run time for Lambda

A User Pools SDK for Every App
Backend
Service app
Mobile app,
Native UI
Mobile app,
Hosted UI,
IdP federation
Web app,
Native UI
Web app,
Hosted UI,
IdP federation
AWS Mobile SDK
for iOS, Android
AWS SDK
for Java
Cognito Auth SDK
for JavaScript
AWS Mobile SDK
for JavaScript
Cognito Auth SDK
for iOS, Android

Identity Pools: Getting AWS Credentials
• If you have a token for your end user, Identity Pools can exchange it for
temporary AWS Credentials
• You use IAM roles to define what AWS resources your user can access
directly
• There are two roles by default: unauthenticated and authenticated
• You can use role mappings to map a claim in a token to a specific role
• The returned AWS Credentials contain the chosen role

Identity Pools: Getting AWS Credentials
Scenario:
• Give User Pool users in admin group access to entire Amazon S3 bucket
Recommendation:
• Create an IAM Role that grants access to the Amazon S3 bucket
• Configure your admin group in User Pools with your admin role
• Configure Identity Pool’s Role Mapping to use role from the User Pool ID
token
Do
✅ Limit permissions for unauthenticated
users

Demo

Amazon Cognito Summary
• Secure authentication and authorization
• Simple hosted UI, identity provider federation, and user
migration
• Flexible app integration with custom authentication flows and
UIs

Additional Resources
See aws.amazon.com/cognito/dev-resources/ for links to:
§ Getting started guides
§ Documentation, SDKs, and sample apps
§ Videos
§ Presentation slides
§ Blog posts
§ Developer forums

Thank you!
P l e a s e r e m e m b e r t o c o m p l e t e t h e s u r v e y
S I D 3 3 2

Details of Configuration and Flows

User Pools: Attributes
• OpenID-Connect Standard Attributes Out of the Box:
• address, birthdate, email, family_name, gender, given_name, locale,
middle_name, name, nickname, phone_number, picture,
preferred_username, profile, timezone, updated_at, website
• You can add custom attributes
• Attributes can be specified as required at sign up
• Attributes can be read-only for apps

User Pools: Attributes
Scenario:
You need to track whether a customer has paid for a feature
Recommendation:
Add a custom attribute named isPaid
Do
Make attribute read-only for your app client
Use AdminUpdateUser to write attribute
Don’t
Use custom attributes for high write rates

User Pools: Attributes—Example
1. Add a custom attribute in the console
2. Make attribute read-only for your app client
3. Use AdminUpdateUserAttributes to set paid status on a user
aws cli cognito-idp admin-update-user-attributes --user-pool-id us-east-1:dead-
beef-cafe-beef1234566 --username david --user-attributes Name=custom:isPaid,Value=Y

User Pools: Aliases
• Enables end users to sign in with multiple identifiers
• Two types
1. User signs up with username and signs in with username or alias
2. User signs up and signs in with email or phone number instead of
username
david
206-555-5555
david@domain.com

User Pools: Aliases
Scenario:
Enable sign in with phone number, email, and username
Recommendation:
Use aliases if you want end users to have multiple usernames
Use username attribute if you want end user to log in with email or phone
Do
Turn on auto-verification
Use preferred_username for mutable usernames
Don’t
Set email or phone as username

Sign In With Social Network IDs Flow (1)
Federated authentication with OAuth 2.0 authorization code grant flows:
1. Unauthenticated user requests a protected page or API in your app or backend service
2. Your app directs browser to Amazon Cognito User Pool at
https://yourdomain.auth.us-east-1.amazoncognito.com/authorize?
client_id=... (your App’s Cognito client id)
&response_type=code (either "code" or "token" for implicit flow)
&redirect_uri=... (optional, if multiple URLs configured for app)
&state=... (optional, opaque string returned to your app with code)
&scope=... (optional, default is all configured scopes for app)
&identity_provider=... (needed if you have more than one provider)
Note: Amazon Cognito Auth SDK does all this for mobile apps
3. Amazon Cognito redirects browser to Facebook OAuth URL
4. User signs in to Facebook and consents to some or all requested permissions
5. Facebook redirects browser back to Amazon Cognito URL/oauth2/idpresponse with authorization
code

Sign In With Social Network IDs Flow (2)
6. Amazon Cognito calls Facebook token API to exchange authorization code for access token, calls
Facebook user profile API, then stores mapped profile attributes in User Pool
7. Amazon Cognito creates authorization code and redirects browser to your app's redirect_uri
e.g. https://app.yourdomain.com/resource?code=...&state=...
e.g. yourcustomscheme://app.yourdomain.com/resource?code=...&state=...
8. Your backend web service or app sends HTTP POST to Amazon Cognito User Pools token API to
exchange authorization code for Amazon Cognito access token, ID token, and refresh token
• https://yourdomain.auth.us-east-1.amazoncognito.com/oauth2/token
• Include your app client's client_id and client_secret in HTTP basic authorization header
• Include parameters in request body: code, grant_type, redirect_uri
• Amazon Cognito Auth SDK does this for mobile apps, using PKCE to prevent URL
hijacking
9. Your app or service parses the id token JWT and gets user’s User Pool attributes, sets an
authentication session cookie, and returns the requested page to the user

Sign In with Enterprise Identities Flow (1)
Authentication flows using SAML 2.0 Redirect and POST bindings:
1. Unauthenticated user requests a protected page or API in your app or backend service
2. Your app directs browser to Amazon Cognito User Pool at
https://yourdomain.auth.us-east-1.amazoncognito.com/authorize?
client_id=... (your app’s Amazon Cognito client id)
&response_type=code (either "code" or "token" for implicit flow)
&redirect_uri=... (optional, if multiple URLs configured for app)
&state=... (optional, opaque string returned to your app with code)
&scope=... (optional, default is all configured scopes for app)
&identity_provider=... (needed if you have more than one provider)
Note: Amazon Cognito Auth SDK does all this for mobile apps.
3. Amazon Cognito redirects browser to enterprise SAML identity provider’s SingleSignOnService URL
4. User signs in to SAML identity provider using corporate (e.g. Active Directory) credentials
5. SAML identity provider POST’s SAML response back to Amazon Cognito URL / saml2 / idpresponse

Sign In with Enterprise Identities Flow (2)
6. Amazon Cognito verifies SAML response signature and stores mapped attributes in User Pool
7. Amazon Cognito creates authorization code and redirects browser to your app's redirect_uri
e.g. https://app.yourdomain.com/resource?code=...&state=...
e.g. yourcustomscheme://app.yourdomain.com/resource?code=...&state=...
8. Your backend web service or app sends HTTP POST to Amazon Cognito User Pools token API to
exchange authorization code for Amazon Cognito access token, id token, and refresh token
• https://yourdomain.auth.us-east-1.amazoncognito.com/oauth2/token
• Include your app client's client_id and client_secret in HTTP basic authorization header
• Include parameters in request body: code, grant_type, redirect_uri
• Amazon Cognito Auth SDK does this for mobile apps, using PKCE to prevent URL
hijacking
9. Your app or service parses the id token JWT and gets user's User Pool attributes, sets an
authentication session cookie, and returns the requested page to the browser

Identity Management for Your Users and Apps: A Deep Dive on Amazon Cognito - SID332 - re:Invent 2017

More Related Content

Identity Management for Your Users and Apps: A Deep Dive on Amazon Cognito - SID332 - re:Invent 2017