GitHub HTTPS Authentication Failure and Two-Factor Authentication Solutions

Problem Description and Context

When using Git command-line tools to interact with GitHub via the HTTPS protocol, many developers encounter a perplexing authentication failure. Specifically, when executing operations like git push, git pull, or other actions requiring authentication, the system prompts for username and password. Even when users confirm their credentials are correct, they receive error messages similar to:

Username for 'https://github.com': username
Password for 'https://username@github.com': 
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/username/repository.git/'

Notably, the error message references an @github.com address, while most users do not have such email addresses. This inconsistency adds to the confusion.

Root Cause Analysis

As confirmed by GitHub's official support team, the root cause of this issue is Two-Factor Authentication (2FA) being enabled on the user's account. When 2FA is activated, traditional username/password authentication no longer works for Git operations over HTTPS. This occurs because 2FA adds an additional layer of security verification that the standard Git HTTPS authentication flow does not support.

From a technical perspective, Git HTTPS authentication typically uses Basic Authentication or Digest Authentication protocols. These protocols were not designed with multi-factor authentication scenarios in mind. When the server (GitHub) detects that an account has 2FA enabled but the client (Git) provides only single-factor credentials, authentication naturally fails.

Solution: Using OAuth Tokens

The standard solution to this problem is to use OAuth tokens instead of traditional passwords. OAuth tokens are access tokens with specific permissions that can bypass 2FA restrictions while maintaining high security.

The specific steps to create an OAuth token are:

1. Log into your GitHub account and navigate to Settings → Developer settings → Personal access tokens
2. Click the Generate new token button
3. Provide a meaningful description (e.g., "Git command-line access")
4. Select appropriate permission scopes (for most Git operations, repo permissions suffice)
5. Click Generate token to complete creation

The generated token is a string like ghp_abc123def456ghi789jkl012mno345pqr678 that must be securely stored, as it is displayed only once.

Configuration and Usage

After obtaining an OAuth token, you need to configure it in your Git environment. In the command line, when Git prompts for a password, paste the OAuth token directly. For example:

Username for 'https://github.com': your_username
Password for 'https://your_username@github.com': ghp_abc123def456ghi789jkl012mno345pqr678

To improve the user experience, you can configure Git's credential storage. On macOS systems, you can use osx-keychain to securely store tokens:

git config --global credential.helper osxkeychain

After configuration, the system will prompt for username and token during the first authentication, and this information will be securely stored in the keychain for subsequent operations.

If incorrect credentials were previously stored, you need to clear them first:

git credential-osxkeychain erase
host=github.com
protocol=https
[Press Return twice]

HTTPS vs SSH Authentication Comparison

While this article focuses on HTTPS authentication issues, understanding the differences between HTTPS and SSH authentication methods helps in making appropriate choices:

• HTTPS with OAuth tokens: Suitable for environments requiring frequent network changes or with minimal firewall restrictions. Tokens can have expiration dates and specific permissions, offering controllable security.
• SSH keys: Suitable for fixed work environments, providing a simpler authentication flow. However, they require key pair management and may encounter port restrictions in strict firewall environments.

From a security perspective, OAuth tokens offer several advantages over fixed passwords: they can be revoked at any time, have limited permissions, and can be set to expire. These features make the risk relatively controllable even if a token is accidentally exposed.

Best Practice Recommendations

Based on the above analysis, we recommend the following best practices:

1. Create different OAuth tokens for different purposes with minimal necessary permissions
2. Regularly rotate tokens, especially those used in production environments
3. In team environments, consider using GitHub Apps for more granular permission control
4. Use .gitconfig files and environment variables to manage authentication configurations for different projects
5. Monitor the authorized applications list in your GitHub account and promptly remove unused tokens

By properly configuring OAuth tokens, developers can enjoy the security enhancements of Two-Factor Authentication while maintaining efficient use of Git command-line tools. This solution not only resolves authentication failures but also enhances the overall security of the workflow.