Social Login Setup Guide

This guide explains how to configure Google, Facebook, and Apple social login providers for the Momentum application.

Overview

The Momentum platform supports social authentication through AWS Cognito with the following providers:

  • Google - Sign in with Google
  • Facebook - Sign in with Facebook
  • Apple - Sign in with Apple

Environment Configuration

MVP Phase: Single environment deployment to momentum.cloudnnj.com

  • Cognito Domain: momentum-dev-auth.auth.us-east-1.amazoncognito.com
  • Application URL: https://momentum.cloudnnj.com

Note: Multi-environment setup (dev/staging/prod) will be introduced post-MVP.

Prerequisites

Before configuring social login, you need to:

  1. Create developer accounts for each provider
  2. Register your application with each provider
  3. Obtain OAuth credentials (Client ID, Client Secret, etc.)
  4. Configure redirect URIs for your application

1. Google OAuth Setup

Step 1: Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google+ API

Step 2: Create OAuth 2.0 Credentials

  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Web application as the application type
  4. Configure the OAuth consent screen if prompted
  5. Add authorized redirect URIs:
    • https://momentum-dev-auth.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
    • For local testing: http://localhost:3000/auth/callback
  6. Click Create and save your:
    • Client ID
    • Client Secret

Step 3: Add Credentials to Terraform

Add the following to your .env.infrastructure file:

TF_VAR_google_client_id="YOUR_GOOGLE_CLIENT_ID"
TF_VAR_google_client_secret="YOUR_GOOGLE_CLIENT_SECRET"

2. Facebook Login Setup

Step 1: Create a Facebook App

  1. Go to Facebook Developers
  2. Click My Apps > Create App
  3. Select Consumer as the app type
  4. Fill in your app details and create the app

Step 2: Add Facebook Login Product

  1. In your app dashboard, click Add Product
  2. Find Facebook Login and click Set Up
  3. Select Web as the platform
  4. Enter your site URL (e.g., https://momentum.cloudnnj.com)

Step 3: Configure OAuth Settings

  1. Go to Facebook Login > Settings
  2. Add valid OAuth redirect URIs:
    • https://momentum-dev-auth.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
  3. Save your changes

Step 4: Get App Credentials

  1. Go to Settings > Basic
  2. Copy your:
    • App ID (this is your Client ID)
    • App Secret (click “Show” to reveal)

Step 5: Add Credentials to Terraform

Add the following to your .env.infrastructure file:

TF_VAR_facebook_client_id="YOUR_FACEBOOK_APP_ID"
TF_VAR_facebook_client_secret="YOUR_FACEBOOK_APP_SECRET"

3. Apple Sign In Setup

Apple Sign In requires more configuration due to its key-based authentication.

Step 1: Enroll in Apple Developer Program

  1. You need an active Apple Developer Program membership ($99/year)

Step 2: Create an App ID

  1. Go to Apple Developer Console
  2. Navigate to Certificates, Identifiers & Profiles
  3. Click Identifiers > + button
  4. Select App IDs and click Continue
  5. Select App and click Continue
  6. Fill in:
    • Description: Momentum Web App
    • Bundle ID: com.cloudnnj.momentum (or your custom bundle ID)
  7. Enable Sign in with Apple capability
  8. Click Continue and then Register

Step 3: Create a Services ID

  1. Click Identifiers > + button
  2. Select Services IDs and click Continue
  3. Fill in:
    • Description: Momentum Sign In
    • Identifier: APPLE_CLIENT_ID_REMOVED (this will be your Client ID)
  4. Enable Sign in with Apple
  5. Click Configure next to Sign in with Apple
  6. Configure:
    • Primary App ID: Select the App ID created in Step 2
    • Domains and Subdomains:
      • momentum.cloudnnj.com
      • momentum-dev-auth.auth.us-east-1.amazoncognito.com
    • Return URLs:
      • https://momentum-dev-auth.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
  7. Click Save, Continue, then Register

Step 4: Create a Private Key

  1. Click Keys > + button
  2. Fill in:
    • Key Name: Momentum Sign In Key
  3. Enable Sign in with Apple
  4. Click Configure and select your Primary App ID
  5. Click Save, Continue, then Register
  6. Download the key file (.p8 file) - you can only download it once!
  7. Note your Key ID (10-character string)

Step 5: Get Your Team ID

  1. In the Apple Developer Console, click on your account name in the top right
  2. Your Team ID is displayed near your name (10-character alphanumeric string)

Step 6: Add Credentials to Terraform

Add the following to your .env.infrastructure file:

TF_VAR_apple_client_id="APPLE_CLIENT_ID_REMOVED"
TF_VAR_apple_team_id="YOUR_TEAM_ID"
TF_VAR_apple_key_id="YOUR_KEY_ID"
TF_VAR_apple_private_key="APPLE_PRIVATE_KEY_REMOVED"

Note: For the private key, you need to:

  1. Open the .p8 file in a text editor
  2. Copy the entire content including the BEGIN and END lines
  3. Paste it as a multi-line string in the environment variable

4. Deploy the Configuration

Once all credentials are configured:

Step 1: Source the environment variables 

source /Users/alpertovi/Development/momentum/.env.infrastructure

Step 2: Initialize and validate Terraform 

cd infrastructure/terraform
terraform init
terraform validate

Step 3: Plan the changes 

terraform plan

Review the plan to ensure:

  • 3 new identity providers will be created (Google, Facebook, Apple)
  • User pool client will be updated with supported identity providers
  • Identity pool will be updated with social login providers

Step 4: Apply the changes 

terraform apply

Type yes to confirm the changes.

5. Testing Social Login

Testing Locally

  1. Start your local development server: 
    npm run dev

  2. Navigate to http://localhost:3000/auth/signin

  3. You should see social login buttons for Google, Facebook, and Apple

  4. Click on any social login button to test the authentication flow

Testing Production

  1. Navigate to your production URL (e.g., https://momentum.cloudnnj.com/auth/signin)
  2. Click on any social login button
  3. Complete the OAuth flow with the provider
  4. You should be redirected back to your app and logged in

6. Troubleshooting

Common Issues

Google: “redirect_uri_mismatch” error

  • Solution: Ensure the redirect URI in Google Cloud Console exactly matches the Cognito hosted UI redirect URI
  • Check: https://[USER_POOL_DOMAIN].auth.[REGION].amazoncognito.com/oauth2/idpresponse

Facebook: “Can’t Load URL” error

  • Solution: Verify that your OAuth redirect URIs in Facebook App settings match your Cognito redirect URIs
  • Make sure your app is not in Development mode if testing with users outside your developer account

Apple: “invalid_client” error

  • Solution:
    • Verify your Services ID matches the apple_client_id
    • Ensure the private key is correctly formatted (including BEGIN and END lines)
    • Check that the Key ID and Team ID are correct

Users not being added to groups

  • Solution: The Cognito post-confirmation Lambda trigger automatically adds new social login users to the “free” group
  • Check CloudWatch logs for the cognito-post-confirmation Lambda function

Debugging Tips

  1. Check Cognito Configuration: 
    aws cognito-idp describe-user-pool --user-pool-id us-east-1_XXXXXX
  2. List Identity Providers: 
    aws cognito-idp list-identity-providers --user-pool-id us-east-1_XXXXXX
  3. Check Lambda Logs: 
    aws logs tail /aws/lambda/momentum-dev-cognito-post-confirmation --follow

7. Security Best Practices

  1. Keep credentials secure:
    • Never commit credentials to version control
    • Use environment variables or AWS Secrets Manager
    • Rotate credentials regularly
  2. Use HTTPS only:
    • All redirect URIs must use HTTPS in production
    • Only use HTTP for localhost testing
  3. Validate redirect URIs:
    • Only add trusted redirect URIs to your OAuth apps
    • Use specific URIs instead of wildcards
  4. Review app permissions:
    • Only request the minimum required scopes
    • Current scopes: email, profile, openid
  5. Monitor authentication events:
    • Enable CloudWatch logging for Cognito
    • Set up alarms for failed authentication attempts
    • Review user pool analytics regularly

8. User Experience Considerations

  1. Account Linking:
    • If a user signs up with email, then later uses social login with the same email, Cognito will automatically link the accounts
    • Users can have multiple identity providers linked to one account
  2. Profile Information:
    • Email and name are automatically populated from social providers
    • Users are added to the “free” group by default
    • Admins can manually promote users to “premium” or “admin” groups
  3. Session Management:
    • Social login sessions follow the same token validity rules as email/password login
    • Tokens expire after 60 minutes by default
    • Refresh tokens are valid for 30 days

9. Additional Resources

Support

For issues or questions:

  • Check CloudWatch logs for detailed error messages
  • Review Cognito user pool configuration in AWS Console
  • Contact the development team via Slack: #momentum-dev

Back to top

Momentum LMS © 2025. Distributed under the MIT license.