Overview

OAuth is an open standard for access delegation commonly used as a way to grant websites or applications limited access to users' information without exposing passwords. GitHub OAuth integration allows developers to authenticate users via their GitHub accounts, which is particularly useful for applications targeting developers or tech-savvy users. By using GitHub for authentication, you can reduce friction during the registration process, allowing users to sign in quickly and securely.

Real-world use cases for GitHub OAuth integration include projects where collaboration is essential, such as code repositories, project management tools, and developer-focused applications. Instead of requiring users to create a new account for your application, you enable them to leverage their existing GitHub credentials, which can lead to higher conversion rates and enhanced user satisfaction.

Prerequisites

• ASP.NET Core SDK: Ensure that you have the .NET SDK installed for building ASP.NET Core applications.
• Visual Studio or Visual Studio Code: Use an IDE for developing and debugging your application.
• GitHub Account: A GitHub account is necessary to create an OAuth application.
• Basic Knowledge of C# and ASP.NET Core: Familiarity with the C# programming language and the ASP.NET Core framework is essential.

Setting Up a GitHub OAuth Application

Before you can implement GitHub OAuth in your ASP.NET Core application, you need to create an OAuth application on GitHub. This process involves registering your application, which will provide you with a Client ID and Client Secret. These credentials are essential for authenticating requests from your application to GitHub.

To create a new OAuth application on GitHub, follow these steps:

1. Log in to your GitHub account and navigate to Settings.
2. Scroll down to Developer settings and click on OAuth Apps.
3. Click on New OAuth App.
4. Fill in the required fields:
• Application Name: Give your application a name.
• Homepage URL: Provide the URL where users can find your application.
• Authorization callback URL: Set this to the URL where GitHub should redirect users after authorization (e.g., `https://localhost:5001/signin-github`).
5. Click on Register application.

Once registered, you will receive your Client ID and Client Secret, which you will use in your ASP.NET Core application.

Configuring ASP.NET Core for GitHub OAuth

Now that you have your OAuth application set up, the next step is to configure your ASP.NET Core application to utilize GitHub OAuth for authentication. You will need to modify the Startup.cs file to include the necessary services and middleware.

Here’s how to configure GitHub OAuth in your ASP.NET Core application:

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = GitHubDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddGitHub(options =>
    {
        options.ClientId = "YOUR_CLIENT_ID";
        options.ClientSecret = "YOUR_CLIENT_SECRET";
        options.CallbackPath = "/signin-github";
    });

    services.AddControllersWithViews();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

The code above does the following:

• Configures authentication services by setting the default authentication and challenge schemes.
• Registers Cookie Authentication, which is required for handling user sessions.
• Sets up GitHub authentication with the Client ID and Client Secret obtained from GitHub.
• Defines the callback path that GitHub will redirect to after successful authentication.
• Sets up the middleware pipeline to use HTTPS redirection, static files, routing, authentication, and authorization.

Creating a Login Action

Next, you will need to create a controller action that initiates the login process. This action will redirect users to GitHub for authentication.

[HttpGet]
public IActionResult Login()
{
    var redirectUrl = Url.Action("GitHubResponse", "Account");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    return Challenge(properties, GitHubDefaults.AuthenticationScheme);
}

This Login action does the following:

• Generates a redirect URL where GitHub will send users after authentication.
• Creates an AuthenticationProperties object to hold the redirect URI.
• Initiates the OAuth challenge, redirecting users to GitHub for login.

Handling the Callback

After the user successfully logs in via GitHub, they will be redirected back to your application. You need to handle this callback in your controller.

[HttpGet]
public async Task GitHubResponse()
{
    var result = await HttpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    if (result.Principal.Identity.IsAuthenticated)
    {
        // User is authenticated
        var name = result.Principal.FindFirst(ClaimTypes.Name)?.Value;
        // You can also retrieve additional claims here
        return RedirectToAction("Index", "Home");
    }
    return RedirectToAction("Login");
}

This GitHubResponse action does the following:

• Asynchronously authenticates the user using the cookie authentication scheme.
• Checks if the user is authenticated. If so, it retrieves user claims, such as the user's name.
• Redirects the user to the home page if authentication is successful; otherwise, it redirects back to the login page.

Edge Cases & Gotchas

When implementing GitHub OAuth, there are several edge cases and common pitfalls to be aware of:

• Redirect URI Mismatch: Ensure that the redirect URI configured in your GitHub application matches the one used in your ASP.NET Core application. Mismatches will result in authentication failures.
• Expired Tokens: Handle scenarios where the access token may expire. Implement token refresh mechanisms if necessary.
• Scope Limitations: Be aware of the scopes you request during authentication. Requesting too many scopes may lead to user rejection during the authorization process.

Performance & Best Practices

When integrating OAuth, it's vital to consider performance and security best practices:

• Use HTTPS: Ensure your application uses HTTPS to protect sensitive information during transmission.
• Limit Scopes: Only request the permissions necessary for your application to function. This minimizes the risk of exposing user data.
• Handle Exceptions Gracefully: Implement error handling to manage exceptions that may arise during authentication.
• Implement Logging: Log authentication attempts and failures for auditing and troubleshooting purposes.

Real-World Scenario: Building a GitHub Profile Viewer

As a practical application of the concepts covered, let’s build a simple GitHub Profile Viewer that allows users to log in with their GitHub account and view their profile information.

Setting Up the Project

Create a new ASP.NET Core MVC project using the following command:

dotnet new mvc -n GitHubProfileViewer

Next, navigate to the project folder and add the required NuGet packages:

dotnet add package Microsoft.AspNetCore.Authentication.GitHub

Implementing the Profile Viewer

In the HomeController, add a new action method to fetch and display the user's GitHub profile:

[HttpGet]
public async Task Profile()
{
    var result = await HttpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    if (!result.Principal.Identity.IsAuthenticated)
    {
        return RedirectToAction("Login");
    }

    var userName = result.Principal.FindFirst(ClaimTypes.Name)?.Value;
    var userProfile = await GetGitHubProfile(userName);
    return View(userProfile);
}

private async Task GetGitHubProfile(string username)
{
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/vnd.github.v3+json"));
    var response = await client.GetAsync($"https://api.github.com/users/{username}");
    response.EnsureSuccessStatusCode();
    var content = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject(content);
}

This code performs the following steps:

• Authenticates the user and checks if they are logged in.
• Retrieves the GitHub username from the claims.
• Calls the GitHub API to fetch the user's profile information.
• Deserializes the JSON response into a GitHubUserProfile model.

Creating the View

Create a new view named Profile.cshtml in the Views/Home directory to display the user's profile information:

@model GitHubUserProfile
@Model.Name's Profile

Bio: @Model.Bio
Public Repos: @Model.PublicRepos
Followers: @Model.Followers
Following: @Model.Following

The view displays the user's name, profile picture, bio, public repository count, followers, and following counts.

Conclusion

• GitHub OAuth integration simplifies user authentication, particularly for developer-focused applications.
• Properly configure your application and handle edge cases to ensure a smooth user experience.
• Always prioritize security by using HTTPS and limiting OAuth scopes.
• Consider implementing logging and error handling to improve maintainability.
• Explore additional OAuth providers to enhance your application's authentication capabilities.