Mock OAuth Account Linking

Welcome to the first lesson of the "OAuth Advanced Features & Integration" course. In today's world, many applications allow users to sign in using accounts from other services, such as Google or Facebook. This is made possible by OAuth, a secure authorization protocol that lets users grant limited access to their information without sharing their passwords. In this lesson, you will learn how to work with a mock OAuth setup, which is a simulated environment for testing OAuth features without needing real third-party accounts.

By the end of this lesson, you will understand how to configure mock OAuth providers, retrieve mock user profiles, and implement account linking and unlinking features. You will also see how to apply important security practices in these workflows. This knowledge will prepare you to build and test advanced authentication features in your own projects and get you ready for hands-on practice in the CodeSignal IDE.

To make development and testing easier, we often use mock OAuth configurations. These allow us to simulate the behavior of real OAuth providers, like Google, without needing to set up actual accounts or credentials. In your project, the oauthConfig.ts file is responsible for storing these mock settings.

Here's what the oauthConfig.ts file looks like:

export const OAUTH_CONFIG = {
  google: {
    mockUserId: 'mock_google_123',
    mockEmail: 'john.google@example.com',
    mockName: 'John Doe (Google)',
    mockPicture: 'https://via.placeholder.com/150?text=Google',
    provider: 'google' as const
  },
  github: {
    mockUserId: 'mock_github_456',
    mockEmail: 'jane.github@example.com',
    mockName: 'Jane Smith (GitHub)',
    mockPicture: 'https://via.placeholder.com/150?text=GitHub',
    provider: 'github' as const
  }
};

export const AUTH_CONFIG = {
  tokenExpiry: {
    password: '1d',
    oauth: '7d'
  },
  rateLimiting: {
    maxAttempts: 5,
    windowMs: 15 * 60 * 1000
  },
  security: {
    requireConfirmation: true,
    preventDuplicateLinks: true
  }
};

Let's break down what each part does:

The OAUTH_CONFIG object contains mock user details for multiple OAuth providers (Google and GitHub). Each provider has its own set of mock data including a user ID, email, display name, profile picture URL, and a provider identifier marked with as const for type safety. This structure mimics what real OAuth providers would return, allowing you to test OAuth flows with multiple providers.

The AUTH_CONFIG object holds general authentication settings that control security and behavior:

• tokenExpiry: Defines different expiration times for different authentication methods. Password-based sessions last 1 day, while OAuth sessions last 7 days, reflecting that OAuth is typically more secure.
• rateLimiting: Protects against brute-force attacks by limiting login attempts. maxAttempts sets the maximum number of tries allowed (5), and windowMs defines the time window in milliseconds (15 minutes).
• security: Controls the account linking process. requireConfirmation ensures users must explicitly confirm before linking accounts, and preventDuplicateLinks blocks multiple users from linking to the same OAuth account.

These settings help you control and secure the authentication process, even in a mock environment.

The getMockOAuthProfile function is a helper that returns a mock user profile for a given provider. In this case, it only supports Google. When you call this function with 'google', it pulls the mock user data from OAUTH_CONFIG and returns an object with the user's ID, email, name, profile picture, and provider name.

For example, calling:

const profile = getMockOAuthProfile('google');
console.log(profile);

will output:

{
  id: 'mock_google_123',
  email: 'john.google@example.com',
  name: 'John Doe (Google)',
  picture: 'https://via.placeholder.com/150?text=Google',
  provider: 'google'
}

This function is especially useful for testing and development. It allows you to simulate the process of retrieving a user's profile from an OAuth provider, so you can build and test your authentication flows without needing real external accounts.

Account linking is a feature that lets users connect multiple authentication methods to a single account. For example, a user who originally signed up with a password can later link their Google account, so they can log in with either method. This is important in modern applications because it gives users flexibility and a better experience.

The high-level workflow for account linking starts when a logged-in user wants to connect their Google account. The system checks if the user has confirmed this action, verifies that the Google account is not already linked to another user account within the application, and ensures that the email addresses match. If all checks pass, the Google account is linked to the user's profile. The user can then log in with either their password or Google in the future.

The /link/google endpoint is responsible for linking a Google account to an existing user. When a user sends a request to this endpoint, the first step is to verify their identity using a JWT (JSON Web Token). The middleware checks the Authorization header, verifies the token, and loads the user from the database. If the token is missing or invalid, the request is rejected.

Next, the endpoint checks if the user has explicitly confirmed the linking action. This is controlled by the requireConfirmation setting in AUTH_CONFIG. If confirmation is required but not provided, the endpoint responds with an error and information about the linking attempt.

The endpoint then checks if the Google account is already linked to another user. If so, and if duplicate links are not allowed, it returns an error to prevent two users from sharing the same Google account. It also compares the email addresses of the current user and the Google account. If they do not match, the linking is blocked to prevent accidental or malicious account merges.

If all checks pass, the endpoint updates the user's profile to include the Google account ID, marks the email as verified, and updates the profile image if needed. The system logs the linking event and responds with a success message and the updated linked account status.

For example, a successful response might look like:

{
  message: 'Google account linked successfully',
  linkedAccounts: {
    google: true,
    local: true
  }
}

The /unlink/google endpoint allows a user to disconnect their Google account from their profile. Before unlinking, the system checks that the user has another way to log in, such as a password. This prevents users from accidentally locking themselves out of their account by removing their only authentication method.

If the user has a password set, the endpoint removes the Google account ID from their profile and sets the provider to 'local'. The event is logged, and the user receives a confirmation message.

For example, after a successful unlink, the response might be:

{
  message: 'Google account unlinked successfully',
  linkedAccounts: {
    google: false,
    local: true
  }
}

If the user does not have a password, the endpoint returns an error and suggests adding a password before unlinking Google. This safety check is important for maintaining account access.

Security is a key part of any authentication system. In this setup, several measures are in place to protect users and the application. The AUTH_CONFIG object defines rate limiting, which restricts the number of login attempts in a given time window to prevent brute-force attacks. Token expiry settings ensure that authentication tokens are only valid for a limited time, reducing the risk if a token is stolen.

The system also requires explicit confirmation before linking accounts and prevents duplicate links to the same Google account. These rules help prevent accidental or unauthorized account merges. Error handling is clear and informative, providing users with helpful messages and suggestions. Logging important events, such as account linking and unlinking, helps with auditing and troubleshooting.

By following these practices, you can build authentication features that are both user-friendly and secure.

In this lesson, you learned how to use mock OAuth configurations to simulate real-world authentication flows. You explored the oauthConfig.ts file, understood how to retrieve mock user profiles, and saw how account linking and unlinking work in detail. You also learned about important security settings and best practices for handling authentication.

Now that you have a solid understanding of these concepts, you are ready to move on to hands-on practice in the CodeSignal IDE. In the next exercises, you will apply what you have learned by working directly with the code, testing account linking and unlinking, and exploring how security features are enforced. This practical experience will help you build confidence and prepare you for more advanced OAuth integrations in the future.