Page updated Feb 13, 2024

Add social provider sign-in

You can enable the use of sign-in with social providers using the amplify/auth/resource.ts file. With Amplify Auth, you can enable your users to Sign in With Apple, Sign in with Google, Login with Amazon, and Facebook.

In this guide we will review how you can add sign-in with social providers by first setting up your developer account with the provider. After this step, you can then configure your Auth category and integrate social sign-in with your app.

If you have not yet created an Amplify (Gen 2) app, visit the quickstart.

Learn more
Review how OAuth authentication works

The preferred way to incorporate social provider sign-in is via an OAuth redirect which lets users sign in using their social media account and creates a corresponding user in the Cognito User Pool.

OAuth 2.0 is the common Authorization framework used by web and mobile applications for accessing user information ("scopes") in a limited manner. Common analogies you will hear in OAuth is that of boarding a plane or staying in a hotel - showing your identification is the authentication piece (signing into an app) and using the boarding pass/hotel key is what you are authorized to access.

OAuth support in Amplify uses Cognito User Pools and supports federation with social providers, which will automatically create a corresponding user in the User Pool after they sign in. With this design you do not need to include an SDK for the social provider in your app. After you set up your developer account with these social providers you can configure by specifying externalProviders under loginWith. You can then use signInWithRedirect() in your app to either show a pre-built "Hosted UI" or pass in a provider name (e.g. signInWithRedirect({ provider: 'Facebook' })) to interface directly and build your own UI. Image

Set up your social auth provider

Before you configure social sign-in with Amplify Auth you will need to set up your developer account with each provider you are using.

Note: Amazon Cognito provides first class support for Facebook Login, Google Sign-In, Login with Amazon, and Sign in with Apple for seamless setup. However you can configure other Identity Providers that support SAML or OpenID Connect (OIDC).

  1. Create a developer account with Facebook.
  2. Sign in with your Facebook credentials.
  3. Choose My Apps from the top navigation bar, and on the page that loads choose Create App. Create App button in the My Apps page of the Facebook developer account.
  4. For your use case, choose Set up Facebook Login. Set up Facebook Login option selected from list.
  5. For platform, choose Website and select No, I'm not building a game.
  6. Give your Facebook app a name and choose Create app. Form fields for the Facebook create app form.
  7. On the left navigation bar, choose Settings and then Basic. App ID and App Secret in the basic settings tab of the dashboard.
  8. Note the App ID and the App Secret. You will use them in the next section in the CLI flow.
  1. Go to Google developer console.
  2. Click Select a project. Select a project button on the nav bar is circled.
  3. Click NEW PROJECT. The new project button is circled on the select a project popup.
  4. Type in project name and click CREATE. The create button is circled in the new project page.
  5. Once the project is created, from the left navigation menu, select APIs & Services, then select Credentials. The top left menu icon is selected, then the APIs and services option, then the credentials option.
  6. Click CONFIGURE CONSENT SCREEN. The configure consent screen button is circled in the oauth consent screen section.
  7. Click CREATE. The create button is circled in the OAuth consent screen section.
  8. Type in App Information and Developer contact information which are required fields and click SAVE AND CONTINUE three times (OAuth consent screen -> Scopes -> Test Users) to finish setting up the consent screen.
  9. Back under the Credentials tab, Create your OAuth2.0 credentials by choosing OAuth client ID from the Create credentials drop-down list. The Create credentials button is circled, then the oauth client ID button is circled in the credentials section..
  10. Choose Web application as Application type and name your OAuth Client.
  11. Click Create.
  12. Take note of Your client ID and Your Client Secret. You will need them for the next section in the CLI flow.
  13. Choose OK.
  1. Create a developer account with Amazon.
  2. Sign in with your Amazon credentials.
  3. You need to create an Amazon security profile to receive the Amazon Client ID and Client Secret. Choose Create a Security Profile. The login with Amazon console with a create a new security profile button displayed.
  4. Type in a Security Profile Name, a Security Profile Description, and a Consent Privacy Notice URL. Security profile management page with steps to fill out a form for the new security profile.
  5. Choose Save.
  6. Choose Show Client ID and Client Secret to show the client ID and secret. You will need them for the next section in the CLI flow. Choosing client ID and client secret.
  1. Sign In with your Apple developer credentials.
  2. On the main developer portal page, select Certificates, IDs, & Profiles.
  3. On the left navigation bar, select Identifier.
  4. On the Identifiers page, select the plus icon (+).
  5. On the Register a New Identifier page, select App IDs.
  6. On the Register an App ID page, under App ID Prefix, take note of the Team ID value.
  7. Provide a description in the Description text box and provide the bundleID of the iOS app. Register an App ID in the certificates, identifiers and profiles section.
  8. Under Capabilities, select Sign in with Apple.
  9. Select Continue, review the configuration, and then select Register.
  10. On the Identifiers page, on the right, select App IDs, and then select Services ID.
  11. Select the plus icon (+) and, on the Register a New Identifier page, select Services IDs.
  12. Provide a description in the Description text box and provide an identifier for the Service ID. Register a services ID in the certificates, identifiers and profiles section.
  13. Select Continue and register the Service ID.

Your developer accounts with the social providers are now set up and you can return to the Amplify specific configuration.

Configure social sign-in backend

In amplify/auth/resource.ts the social providers need to be added.

The following is an example of how you would set up access to all of the social providers supported by Amplify Auth. Please note you will need to configure your callbackUrls and logoutUrls URLs for your application, which will inform your backend resources how to behave when initiating sign in and sign out operations in your app. You will also need to configure your domainPrefix for your user pool domain, which will be the redirect URI for your OAuth provider.

Secrets must be created manually with amplify sandbox secret for use with cloud sandbox, or via Amplify Console for branch environments.

import { defineAuth, secret } from '@aws-amplify/backend'; export const auth = defineAuth({ loginWith: { externalProviders: { google: { clientId: secret('GOOGLE_CLIENT_ID'), clientSecret: secret('GOOGLE_CLIENT_SECRET') }, signInWithApple: { keyId: secret('SIWA_KEY_ID'), privateKey: secret('SIWA_PRIVATE_KEY'), teamId: secret('SIWA_TEAM_ID') }, loginWithAmazon: { clientId: secret('LOGINWITHAMAZON_CLIENT_ID'), clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET') }, facebook: { clientId: secret('FACEBOOK_CLIENT_ID'), clientSecret: secret('FACEBOOK_CLIENT_SECRET') }, callbackUrls: [ 'http://localhost:3000/profile', 'https://mywebsite.com/profile' ], logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'], domainPrefix: 'subdomain' } } });
amplify/auth/resource.ts
1import { defineAuth, secret } from '@aws-amplify/backend';
2
3export const auth = defineAuth({
4 loginWith: {
5 externalProviders: {
6 google: {
7 clientId: secret('GOOGLE_CLIENT_ID'),
8 clientSecret: secret('GOOGLE_CLIENT_SECRET')
9 },
10 signInWithApple: {
11 keyId: secret('SIWA_KEY_ID'),
12 privateKey: secret('SIWA_PRIVATE_KEY'),
13 teamId: secret('SIWA_TEAM_ID')
14 },
15 loginWithAmazon: {
16 clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
17 clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET')
18 },
19 facebook: {
20 clientId: secret('FACEBOOK_CLIENT_ID'),
21 clientSecret: secret('FACEBOOK_CLIENT_SECRET')
22 },
23 callbackUrls: [
24 'http://localhost:3000/profile',
25 'https://mywebsite.com/profile'
26 ],
27 logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'],
28 domainPrefix: 'subdomain'
29 }
30 }
31});

You need to now inform your social provider of the newly configured authentication resource and its OAuth redirect URI:

  1. Sign In to your Facebook developer account with your Facebook credentials.

  2. Choose My Apps from the top navigation bar, and on the Apps page, choose your app you created before.

  3. On the left navigation bar, choose Products. Add Facebook Login if it isn't already added.

  4. If already added, choose Settings under the Configure dropdown. The Settings option is circled from the configure dropdown.

  5. Under Valid OAuth Redirect URIs type your user pool domain with the /oauth2/idpresponse endpoint.

    https://<your-user-pool-domain>/oauth2/idpresponse

Userpool domain is pasted into the text field with /oauth2/ endpoint.

  1. Save your changes.
  1. Go to the Google developer console.

  2. On the left navigation bar, look for APIs and Services under Pinned or under More Products if not pinned.

  3. Within the APIs and Services sub menu, choose Credentials.

  4. Select the client you created in the first step and click the Edit button.

  5. Type your user pool domain into the Authorized JavaScript origins form.

  6. Type your user pool domain with the /oauth2/idpresponse endpoint into Authorized Redirect URIs.

    The URLs 1 form fields for authorized JavaScript origins and authorized redirect URLs are circled.

    Note: If you saw an error message Invalid Redirect: domain must be added to the authorized domains list before submitting. when adding the endpoint, please go to the Authorized Domains List and add the domain.

  7. Click Save.

  1. Sign in with your Amazon credentials.
  2. Hover over the gear and choose Web Settings associated with the security profile you created in the previous step, and then choose Edit. The web settings option is selected in the dropdown menu from the gear icon.
  3. Type your user pool domain into Allowed Origins and type your user pool domain with the /oauth2/idpresponse endpoint into Allowed Return URLs. Userpool domain is typed into the allowed origins field with /oauth2/ as the endpoint in the Allowed Return URLs field.
  4. Choose Save.
  1. Sign In with your Apple developer credentials.
  2. On the main developer portal page, select Certificates, IDs, & Profiles.
  3. On the left navigation bar, select Identifiers and then select Service IDs from the drop down list on the right.
  4. Select the Service ID created when you set up your auth provider as outlined in the section above.
  5. Enable Sign In with Apple and select Configure.
  6. Under Primary App ID select the App ID that was created before.
  7. Type your user pool domain into Domains and Subdomains.
  8. Type your user pool domain with the /oauth2/idpresponse endpoint into Return URLs. The return URLs text field is selected.
  9. Click Next, review the information, then select Done.
  10. On Edit your Services ID Configuration click Continue, review the information, then select Save.
  11. On the main Certificates, Identifiers & Profiles, select Keys.
  12. On the Keys page, select the plus icon (+).
  13. Provide a name for the key under Key Name.
  14. Enable Sign in with Apple and select Configure. The sign in with apple option is enabled and the key name text field is filled out.
  15. Under Primary App ID select the App ID that was created before.
  16. Click on Save.
  17. On Register a New Key click Continue, review the information, then select Register.
  18. You will be redirected to a new page. Take note of the Key ID and download the .p8 file containing the private key. The download key page is shown with the option to download the .p8 file with the private key.

Customizing scopes for retrieving user data from social providers

You can determine the pieces of data you want to retrieve from each social provider when setting them up in the amplify/auth/resource.ts file using scopes.

// amplify/auth/resource.ts import { defineAuth } from '@aws-amplify/backend'; export const auth = defineAuth({ loginWith: { externalAuthProviders: { loginWithAmazon: { clientId: secret('LOGINWITHAMAZON_CLIENT_ID'), clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'), // highlight-next-line scopes: ['email'] }, callbackUrls: [ 'http://localhost:3000/profile', 'https://mywebsite.com/profile' ], logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'], domainPrefix: 'subdomain' } } });
amplify/auth/resource.ts
1// amplify/auth/resource.ts
2import { defineAuth } from '@aws-amplify/backend';
3
4export const auth = defineAuth({
5 loginWith: {
6 externalAuthProviders: {
7 loginWithAmazon: {
8 clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
9 clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'),
10 scopes: ['email']
11 },
12 callbackUrls: [
13 'http://localhost:3000/profile',
14 'https://mywebsite.com/profile'
15 ],
16 logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'],
17 domainPrefix: 'subdomain'
18 }
19 }
20});

Attribute mapping

You can map which attributes are mapped between your social login provider and your users created in Cognito. We will be able to have the best level of protection for developers if we ensure that attribute mappings that would not work are called out by the type system.

If you specify an attribute in your authentication resource as required, and it is not allowed for your social providers, signing in with that social provider will cause an error.

// amplify/auth/resource.ts import { defineAuth } from '@aws-amplify/backend'; export const auth = defineAuth({ loginWith: { externalAuthProviders: { loginWithAmazon: { clientId: secret('LOGINWITHAMAZON_CLIENT_ID'), clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'), // highlight-start userAttributeMapping: { email: 'email' } // highlight-end }, callbackUrls: [ 'http://localhost:3000/profile', 'https://mywebsite.com/profile' ], logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'], domainPrefix: 'subdomain' } } });
amplify/auth/resource.ts
1// amplify/auth/resource.ts
2import { defineAuth } from '@aws-amplify/backend';
3
4export const auth = defineAuth({
5 loginWith: {
6 externalAuthProviders: {
7 loginWithAmazon: {
8 clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
9 clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'),
10 userAttributeMapping: {
11 email: 'email'
12 }
13 },
14 callbackUrls: [
15 'http://localhost:3000/profile',
16 'https://mywebsite.com/profile'
17 ],
18 logoutUrls: ['http://localhost:3000/', 'https://mywebsite.com'],
19 domainPrefix: 'subdomain'
20 }
21 }
22});

Learn more about configuring the React Authenticator component for social providers

Set up your frontend

If you are using the Authenticator component with Amplify (Gen 2), this feature works without any additional code. The guide below is for writing your own implementation.

Enabling a signing in of a user with a social provider can be done as shown in the following code snippet.

import { Auth } from 'aws-amplify'; try { const { user } = await Auth.signInWithWebUI({ provider: 'google' }); } catch (error) { console.log('error signing up:', error); }
src/my-client-side-js.js
1import { Auth } from 'aws-amplify';
2
3try {
4 const { user } = await Auth.signInWithWebUI({
5 provider: 'google'
6 });
7} catch (error) {
8 console.log('error signing up:', error);
9}

Conclusion

Congratulations! You finished the Add social provider sign-in guide. In this guide, you learned how to set up your social auth provider with Amplify. Your users can now sign into your app using their social provider accounts.

Next steps

Now that you have social provider sign-in you may also want to learn additional ways to customize these workflows. We recommend you learn more about: