Menu
Amazon Cognito
Developer Guide (Version Last Updated: 07/28/2016)

Getting Started with User Pools App Integration and Federation

Amazon Cognito User Pools app integration and federation provide a customizable experience to sign in users and built-in integrations with Facebook, Google, and Login with Amazon as well as SAML 2.0 identity providers. With the Amazon Cognito SDK and a few lines of code, you can add sign-up and sign-in pages to your mobile or web app. With these new features, Amazon Cognito User Pools can authenticate and manage both sets of users: those who sign in directly to your user pool and users who sign in through an external identity provider. All users have profiles and tokens provided by Amazon Cognito.

This guide describes how to get started with Amazon Cognito User Pools using the customizable user experience and built-in integrations with identity providers. If you prefer to build your own user experience and connect it to Amazon Cognito User Pools using our SDK, see the Getting Started with Amazon Cognito User Pools. If your app needs to get AWS credentials for federated users, but you do not want to link federated users with Amazon Cognito User Pool profiles or tokens, see Getting Started with Amazon Cognito Federated Identities.

Setting Up an Amazon Cognito User Pool as Your User Directory

A user pool is a user directory that you can use to sign up and sign in users and to manage user profiles. User pools also provide tokens for your users when they sign in. You can use these tokens to control access for the user (via your app) to resources such as backend APIs. User pools can contain both native users who sign in directly (i.e., with a username and password stored in the user pool) and federated users who sign in via an external identity provider. You can also map external identity provider user attributes (e.g., name or email address) to user pool attribute values. Both native and federated users have a user profile and receive user pool tokens when they sign in, so you can standardize your app to handle all users through Amazon Cognito.

If you do not already have a user pool, you can create and configure one from the Amazon Cognito console. For more information, see Quickstart: Using the Console to Create a New User Pool and Step Through Amazon Cognito User Pool Settings in the AWS Management Console.

To try the app integration and federation features, we recommend you create a user pool with the following settings in the Amazon Cognito console:

  • On the Attributes tab, select Email address or phone number and select Allow email addresses.

  • On the Policies tab, select Allow users to sign themselves up (default).

  • On the Verifications tab, under Do you want to require verification of emails or phone numbers?, select Email (default).

  • On the App clients tab, create an app client.

Configuring App Integration

After you create a user pool, the Amazon Cognito console displays an App integration tab where you can configure settings for the customizable, built-in UI for signing up and signing in users. For more information, see Integrating Mobile and Web Apps into Amazon Cognito User Pools.

To use app integration, specify the following settings in the Amazon Cognito console:

  1. On the App client settings tab:

    1. Select the appropriate boxes to enable the identity providers you want to allow your users to sign in with.

      Note

      To allow your users to sign in with external identity providers such as Facebook or a SAML identity provider, you first configure them as described next and then return to the App client settings tab to enable them.

    2. Enter a callback URL for the Amazon Cognito authorization server to call after users are authenticated. For a web app, the URL must start with https://. For an iOS or Android app, you can use a callback URL such as myapp://. You may want to return to this setting after you’ve integrated the SDK, as described in the following section.

    3. Unless you specifically want to exclude one, select the boxes for all of the Allowed OAuth Flows and Allowed OAuth scopes.

  2. On the Domain name tab, enter a domain prefix that is available.

  3. On the UI customization tab, you can upload a logo for the hosted end-user pages and edit the CSS values to change the look and feel to match your app and branding.

    Note

    You can view the hosted UI with your customizations by constructing the following URL, with the specifics for your user pool, and typing it into a browser: https://<your_domain>/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url> You may have to wait up to one minute to refresh your browser before changes made in the console appear.

    Your domain is shown on the Domain name tab. Your app client ID and callback URL are shown on the App client settings tab.

Configuring Federation with a Social Identity Provider

Amazon Cognito User Pools provide built-in integrations with social identity providers, such as Facebook, Google, and Login with Amazon. By configuring these social identity providers for an Amazon Cognito user pool, you can quickly and easily add them as choices for your end users to sign in. The user pool becomes a single point of identity management for your application. You can add one or more social identity providers in the Amazon Cognito console and define mappings of user attributes (such as email addresses) from social identity providers to user attributes in your user pool.

You can skip this step if you do not want to enable your end users to sign in through social identity.

For more information, see Adding Social Identity Providers. To try this feature, make the following choices in the Amazon Cognito console:

To add a social identity provider, you first create a developer account with the identity provider. After you have your developer account, you register your app with the identity provider. The identity provider creates an app ID and an app secret for your app, and you need to configure those values in your user pool.

Here are some links to get started with social identity providers:

You will need to configure your user pool domain or redirect URL with the identity provider. This ensures that the identity provider will accept the redirect URL supplied by Amazon Cognito when it authenticates users.

  • For Google, add your Amazon Cognito user pool domain URL (https://<your-user-pool-domain>/oauth2/idpresponse) in the Google app's Authorized redirect URIs (in the Credentials section).

  • For Facebook, add your Amazon Cognito user pool domain URL (https://<your-user-pool-domain>/) in the Facebook app's Settings (Basic), Website URL.

  • For Login with Amazon, add your Amazon Cognito user pool domain URL (https://<your-user-pool-domain>/oauth2/idpresponse) to the Login with Amazon app's Allowed Return URLs.

To configure a social identity provider in Amazon Cognito User Pools

  1. On the Identity providers tab, choose the button for your social identity provider: Facebook, Google, or Login with Amazon.

  2. Enter the app ID and app secret that you received from the identity provider.

  3. Enter the names of the scopes that you want to authorize. Scopes define which user attributes (such as name and email) you want to access with your app. For Facebook, these should be separated by commas (for example, public_profile, email). For Google and Login with Amazon, they should be separated by spaces. (Google example: profile email openid. Login with Amazon example: profile postal_code.)

    The end-user is asked to consent to providing these attributes to your app. For more information about their scopes, see the documentation from Google, Facebook, and Login with Amazon.

  4. Choose Update Facebook (or Google or Amazon).

  5. On the Attribute mapping tab, add mappings for at least the required attributes, typically email, as follows:

    1. Select the check box to choose the Facebook, Google, or Amazon attribute name. You can also enter the names of additional attributes that are not listed in the Amazon Cognito console.

    2. Select the destination user pool attribute from the drop-down list.

Configuring Federation with a SAML 2.0 Identity Provider

Amazon Cognito User Pools support SAML 2.0 federation with post-binding endpoints. This eliminates the need for your app to retrieve or parse SAML assertion responses, because the user pool directly receives the SAML response from your identity provider via a user agent. Amazon Cognito acts as an authentication service provider on behalf of your application. The user pool becomes a single point of identity management for your application, so that your application does not need to integrate with multiple SAML identity providers. You can add one or more SAML identity providers in the Amazon Cognito console and define mappings of user attributes (such as email addresses) from the SAML identity provider (via SAML assertion claims) to user attributes in your user pool.

You can skip this step if you do not want to enable your end users to sign in via SAML federation. To set up a SAML identity provider, you will do configuration tasks both in Amazon Cognito and in the SAML identity provider.

You configure your user pool as a relying party or application in your SAML 2.0 identity provider. See the documentation for your identity provider for more information.

You enter a redirect or sign-in URL, which is https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse. You can find your domain prefix and the region value for your user pool on the Domain name tab of the Amazon Cognito console.

Note

Any SAML identity providers that you created in a user pool during the public beta before August 10, 2017 have redirect URLs of https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login/redirect. If you have one of these SAML identity providers from the public beta in your user pool, you must either:

  • Replace it with a new one that uses the new redirect URL.

  • Update the configuration in your SAML identity provider to accept both the old and new redirect URLs.

All SAML identity providers in Amazon Cognito will switch to the new URLs, and the old ones will stop working on October 31, 2017.

For some SAML Identity providers you must provide the urn / Audience URI / SP Entity ID, in the form urn:amazon:cognito:sp:<yourUserPoolID>. You can find your user pool ID on the App client settings tab in the Amazon Cognito console.

You must also configure your SAML identity provider to provide attributes values for any attributes required in your user pool. Typically email is a required attribute for user pools, and in that case the SAML identity provider must provide an email value (claim) in the SAML assertion.

To configure a SAML 2.0 identity provider in Amazon Cognito User Pools

For more information, see Using Federation for Amazon Cognito User Pools . To try this feature, make the following choices in the Amazon Cognito console:

  1. On the Identity providers tab, create a new provider by uploading or entering a URL for the metadata document from your SAML identity provider. For more information about the metadata document, see Using Federation for Amazon Cognito User Pools.

  2. On the Attribute mapping tab, add mappings for at least the required attributes, typically email, as follows:

    1. Enter the SAML attribute name as it appears in the SAML assertion from your identity provider. If your identity provider offers sample SAML assertions, that may help you to find the name. Some identity providers use simple names, such as email, while others use names similar to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

    2. Select the destination user pool attribute from the drop-down list.

You can use the Amazon Cognito iOS, Android, and JavaScript SDKs to integrate the customizable sign-in flows into your mobile or web app. The SDKs help you display the hosted UI, receive the user pool tokens, and refresh tokens. For more information, see the documentation with each SDK.

Your app can also form requests and call the Amazon Cognito authorization server directly. The following example shows the hosted sign-in page and tests signing in from a browser with an authorize request:

Copy
https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/authorize? response_type=code& client_id=<yourAppClientId>& redirect_uri=<yourRedirectURL>& state=STATE& scope=email+phone+openid+profile+aws.cognito.signin.user.admin

For more information, see the Amazon Cognito Auth API Reference.

Where to Find the SDKs and Sample Apps for App Integration and Federation

You can find the SDKs and sample apps for Amazon Cognito User Pools app integration and federation in the following locations:

Where to Go from Here

With the preceding instructions and the SDKs you can add user sign-up and sign-in, with social identity or SAML federation, to your mobile or web app with Amazon Cognito User Pools. After a user signs in, your app can use the user pool profile to manage users and the tokens the user pool provides to authorize access to your APIs and resources. If your app needs to use these user pool tokens to get AWS credentials to access resources, such as in an S3 bucket or DynamoDB table, see Integrating User Pools with Federated Identities. For information about using Amazon Cognito user pool tokens directly with API Gateway, see Use Amazon Cognito User Pools in the API Gateway Developer Guide.