Selecting and migrating a Facebook API version for Amazon Cognito

September 8, 2023: It’s important to know that if you activate user sign-up in your user pool, anyone on the internet can sign up for an account and sign in to your apps. Don’t enable self-registration in your user pool unless you want to open your app to allow users to sign up.

On May 1, 2020, Facebook will remove version 2.12 of the Facebook Graph API. This change impacts Amazon Cognito customers who are using version 2.12 of the Facebook Graph API in their identity federation configuration. In this post, I explain how to migrate your Amazon Cognito configuration to use the latest version of the Facebook API.

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.

An Amazon Cognito User Pool is a user directory that helps you manage identities. It’s also where users can sign into your web or mobile app. User pools support federation through third-party identity providers, such as Google, Facebook, and Apple, as well as Amazon’s own Login with Amazon. Additionally, federation can use identity providers that work with OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) 2.0. Federating a user through the third-party identity provider streamlines the user experience, because users don’t need to sign up directly for your web or mobile app.

Amazon Cognito User Pools now enable users to select the version of the Facebook API for federated login. Previously, version 2.12 of Facebook’s Graph API was automatically used for federated login and to retrieve user attributes from Facebook. By selecting a specific version of Facebook’s API, you can now upgrade versions and test changes. This provides a mechanism to revert back to earlier versions if necessary.

To help ease this transition for our customers, we are doing two phases of mitigation. In the first phase, already underway, you can choose which Facebook version to use for federated login. You can test out the new API version and discover the impact upgrading has on your application. If you must make changes, you can revert to the older version, and you have until May 1, 2020 to perform updates. In the second phase, starting sometime in April, we will automatically migrate customers to version 5.0 if they haven’t selected an API version.

There are benefits to having access to newer versions of Facebook APIs. For instance, if customers who use version 5.0 store a Facebook access token and use it to call the Messenger API, they can use webhook events. This type of benefit is useful for users who react or reply to messages from businesses. You can also use business asset groups to manage a large number of assets with Facebook API v4.0 and the Facebook Marketing API.

How to use different Facebook API versions with Amazon Cognito

These instructions assume you’re familiar with Amazon Cognito User Pools and the User Pool clients. You also need a User Pool domain already set up with the appropriate settings for a hosted UI. If you haven’t set up a user pool yet, you can find the instructions in the Amazon Cognito Developer Guide. You need your User Pool domain information when you set up your Facebook app.

Set up the Facebook app

Go to the Facebook for Developers website and sign in, or sign up if you do not have an account. Create a new Facebook app if you must, or you can reuse an existing one.
Navigate to the App Dashboard and select your App.
On the navigation menu, select Products, then Facebook Login, and then Settings.
In the Valid OAuth Redirect URLs field, add your user pool domain with the endpoint /oauth2/idpresponse. As shown in Figure 1, it should look like https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/oauth2/idpresponse.

Figure 1
In the navigation menu, select Settings, then choose Basic.
Note your App ID and your App Secret for the next step.

Adding your Facebook app to your Amazon Cognito user pool

Next, you need to add your Facebook app to your user pool. This can be done either through the AWS Management Console or the command line interface (CLI) and I will show you both methods.

Adding the Facebook app to a user pool through using the AWS Management Console

1. On the AWS Management Console, navigate to Amazon Cognito, then select Manage Pools. From the list that shows up, select your user pool.
2. On the navigation menu, select Federation, then Identity Providers.
3. Select Facebook. Enter the Facebook App ID and App Secret from step 6 above. Then, under Authorize Scopes, enter the appropriate scopes.
4. In the navigation menu, select Federation and go to Attributes Mapping.
5. Now select the version of the Facebook API you want to use. By default, the highest available version (v6.0) for newly created Facebook identity providers is pre-selected for you.
6. After choosing your API version and attribute mapping, click Save.

Figure 2

Adding the Facebook app to a user pool through the CLI

The command below adds the Facebook app configuration to your user pool. Use the values for <USER_POOL_ID>,<FACEBOOK_APP_ID> and <FACEBOOK_APP_SECRET> that you noted earlier:


aws cognito-idp create-identity-provider --cli-input-json '{
    "UserPoolId": "<USER_POOL_ID>",
    "ProviderName": "Facebook",
    "ProviderType": "Facebook",
    "ProviderDetails": {
        "client_id": "<FACEBOOK_APP_ID>",
        "client_secret": "<FACEBOOK_APP_SECRET>",
        "authorize_scopes": "email",
        "api_version": "v5.0"
    },
    "AttributeMapping": {
        "email": "email"
    }
}'

The command below updates the Facebook app configuration to your user pool. Use the values for <USER_POOL_ID>, <FACEBOOK_APP_ID> and <FACEBOOK_APP_SECRET> that you noted earlier:


aws cognito-idp update-identity-provider --cli-input-json '{
    "UserPoolId": "<USER_POOL_ID>",
    "ProviderName": "Facebook",
    "ProviderType": "Facebook",
    "ProviderDetails": {
        "client_id": "<FACEBOOK_APP_ID>",
        "client_secret": "<FACEBOOK_APP_SECRET>",
        "authorize_scopes": "email",
        "api_version": "v5.0"
    },
    "AttributeMapping": {
        "email": "email"
    }
}'

You can verify that the create or update was successful by checking the version returned in the describe-identity-provider call:


aws cognito-idp describe-identity-provider --user-pool-id "" --provider-name "Facebook"
{
    "IdentityProvider": {
        "UserPoolId": "<USER_POOL_ID>",
        "ProviderName": "Facebook",
        "ProviderType": "Facebook",
        "ProviderDetails": {
            "api_version": "v5.0",
            "attributes_url": "https://graph.facebook.com/v5.0/me?fields=",
            "attributes_url_add_attributes": "true",
            "authorize_scopes": "email",
            "authorize_url": "https://www.facebook.com/v5.0/dialog/oauth",
            "client_id": "<FACEBOOK_APP_ID>",
            "client_secret": "<FACEBOOK_APP_SECRET>",
            "token_request_method": "GET",
            "token_url": "https://graph.facebook.com/v5.0/oauth/access_token"
        },
        "AttributeMapping": {
            "email": "email",
            "username": "id"
        },
        ...
    }
}

Use the updated configuration with the Cognito Hosted UI:

On the AWS Console for Amazon Cognito, navigate to your user pool and go to the navigation menu. In App Integration, go to App client settings, find your app, and check Facebook as the Enabled Identity Providers.
Select Launch Hosted UI.
Select Continue with Facebook.
If you aren’t automatically signed in at this point, the URL displays your selected version. For example, if v5.0 was selected, the URL starts with: https://www.facebook.com/v5.0/dialog/oauth. If you would like to disable automatic sign-in, simply remove your app from Facebook so that the sign-in prompts for permissions again. Follow these instructions to learn more.
The browser returns to your redirect URL with a code issued by Amazon Cognito if it was successful.

Notes on testing

Facebook will redirect your API call to a more recent version if your app is not allowed to call it. For example, if you created your Facebook app in November 2018, the latest available version at the time was version 3.2. If you were to call the Graph API using version 3.0, the call is upgraded to version 3.2. You can tell which version you are using by referring to the facebook-api-version header in Facebook’s response headers.

If an attribute was not marked as required, and the attribute is missing from Facebook, federation still succeeds, but the attribute is empty in the user pool. There have been various deprecations of fields from Facebook since Facebook federation was launched for Amazon Cognito. For instance, gender and birthday attributes have since changed to be explicitly requested on their own separate permissions rather than granted by default. The cover attribute has also been deprecated. You can confirm that your attribute has successfully federated on the user’s page in the user pools page of the AWS Management Console for Amazon Cognito. You should, as part of your migration, validate that end attributes that you are working with are passed in the way you expect.

Summary

In this post, I explained how to select the version of Facebook’s Graph API for federated login. If you already use Amazon Cognito for federated login with Facebook, you should migrate to the most recent version as soon as possible. Use this process to make sure you get all the attributes you need for your application. New customers can immediately take advantage of the latest API version.

If you have feedback about this blog post, submit comments in the Comments section below. If you have questions about this blog post, start a new thread on the Amazon Cognito Forums or contact AWS Support.

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.

AWS Security Blog