ASP.NET Core 기본 예제 1 - 구글 OAuth 로그인 인증

ASP.NET Core 기초 예제 - Google OAuth 로그인 구현 흐름

이전 글에서는 ASP.NET Core에서 HTTP 요청이 처리되는 기본 구조를 정리했다.
요청은 웹 서버 엔진이 TCP 스트림을 HTTP

메시지로 파싱된 뒤 ASP.NET Core 내부의 Dispatch 과정으로 전달되고,

이 과정에서 Middleware 체인을 거쳐 최종적으로 Controller가 실행된다는 구조였다.

이번 글에서는 이러한 구조가 실제로 어떻게 사용되는지 간단한 예제를 통해 살펴보려고 한다.

예제로 사용할 것은 Google OAuth 로그인이다.

최근 모바일 게임이나 웹 서비스에서는 자체 계정 시스템 대신 Google, Apple, Facebook과 같은 외부 계정 시스템을 이용해 로그인하는 경우가 많다. 이러한 인증 방식을 일반적으로 OAuth 기반 로그인이라고 부른다.

ASP.NET Core는 이러한 OAuth 인증을 비교적 간단하게 구현할 수 있도록

Middleware 형태의 인증 시스템을 제공한다.

---

Google OAuth 콘솔에서 클라이언트 생성

Google OAuth 로그인을 사용하려면 먼저 Google Cloud Console에서 OAuth Client를 생성해야 한다.

먼저 다음 페이지로 이동한다.

https://console.cloud.google.com/

이후 다음 순서로 설정을 진행한다.

먼저 새로운 프로젝트를 생성한다.
프로젝트 이름은 자유롭게 지정하면 된다.

 

프로젝트가 생성되면 API 및 서비스 -> 사용자 인증 정보 메뉴로 이동한다.

여기서 사용자 인증 정보 만들기 -> OAuth 클라이언트 ID를 선택한다.

애플리케이션 유형은 웹 애플리케이션을 선택한다.

이후 다음 항목을 설정해야 한다.

 

Authorized redirect URI

예제에서는 다음 주소를 사용한다.

https://localhost:5001/signin-google

 

이 URI는 OAuth 인증이 완료된 이후 Google이 다시 리다이렉트할 주소이다.

설정을 완료하면 다음 두 가지 값이 생성되고, json 파일을 하나 준다.

Client ID
Client Secret

 

이 값들은 ASP.NET Core 애플리케이션에서 OAuth 인증을 설정할 때 사용된다.

---

OAuth 로그인 전체 흐름

Google OAuth 로그인은 전체적으로 다음과 같은 흐름으로 동작한다.

먼저 클라이언트가 로그인 요청을 보내면 서버는 Google 인증 서버로 리다이렉트를 수행한다.

사용자는 Google 로그인 페이지에서 계정을 선택하고 인증을 진행한다.

인증이 성공하면 Google은 다시 서비스 서버로 리다이렉트를 수행하며 이때 인증 코드가 함께 전달된다.

서버는 이 인증 코드를 Google 서버에 전달하여 실제 사용자 인증 정보를 확인하고 이후 애플리케이션 내부 로그인 처리를 진행한다.

정리하면 다음과 같은 흐름이다.

 

1) 클라이언트가 로그인 요청을 보낸다.

 

2) 서버는 Google OAuth 인증 서버로 리다이렉트한다.

 

3) 사용자가 Google 계정으로 로그인한다.

이 과정에서 클라이언트가 인증 코드를 얻게 된다. 

 

4) 클라이언트는 구글과의 작업이 끝났다.

이제 인증 코드를 포함해 서버로 다시 리다이렉트한다.

 

5) 서버는 클라이언트로부터 받은 인증 코드를 다시 전달해 사용자 정보를 검증한다. 

이후 우리가 작성한 애플리케이션 내부 로그인 로직을 수행 된다. 

이 과정에서 중요한 점은 클라이언트가 전달한 인증 결과를 그대로 신뢰하지 않는다는 것이다.

서버는 반드시 Google 서버와 직접 통신하여 인증 코드를 검증한다.

 

---

NuGet 패키지 설치

ASP.NET Core에서 Google OAuth를 사용하려면 관련 패키지를 설치해야 한다.

프로젝트에 다음 패키지를 추가한다.

Microsoft.AspNetCore.Authentication.Google

패키지 관리자 콘솔에서는 다음과 같이 설치할 수 있다.

Install-Package Microsoft.AspNetCore.Authentication.Google -Version 8.0.6

 

.NET 8 기준이라면 8.x 버전을 사용하는 것이 자연스럽다.
최신 버전을 그대로 설치할 경우 .NET 10 전용 패키지가 선택되어 호환성 문제가 발생할 수 있으므로 버전을 명시하는 편이 안전하다.

이 단계가 완료되어야 AddGoogle() 확장 메서드를 사용할 수 있다.

ASP.NET Core에서 Google OAuth 설정

ASP.NET Core에서는 인증 시스템을 Middleware 형태로 구성한다.

먼저 Program.cs에서 인증 Middleware를 등록한다.

ClientId와 ClientSecret 은 앞서 획득한 JSON 키 파일 내에 들어있으니, 이것으로 설정하면 된다.

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.Google;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
})
.AddCookie()
.AddGoogle(options =>
{
    options.ClientId = "CLIENT_ID";
    options.ClientSecret = "CLIENT_SECRET";
});


// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

 

여기서 AddGoogle() 호출은 Google OAuth 인증을 처리하는 Middleware를 등록하는 역할을 한다.

---

Controller 코드 작성 - AuthController.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Google;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

[ApiController]
[Route("auth")]
public class AuthController : Controller
{
    [HttpGet("login")]
    public IActionResult Login()
    {
        var props = new AuthenticationProperties
        {
            RedirectUri = "/auth/callback"
        };

        return Challenge(props, GoogleDefaults.AuthenticationScheme);
    }

    [HttpGet("callback")]
    public IActionResult Callback()
    {
        var email = User.FindFirst(ClaimTypes.Email)?.Value;
        var name = User.FindFirst(ClaimTypes.Name)?.Value;

        return Ok(new
        {
            name,
            email
        });
    }
}

로그인을 시작하는 Controller는 매우 단순하다.

클라이언트의 인증 시작은 우리가 작성한 서버로부터 시작한다.

즉, auth/login 메서드가 Google OAuth 인증을 시작하는 역할을 한다.

Challenge() 메서드를 호출하면 ASP.NET Core 인증 시스템이 동작하며

Google OAuth 인증 서버로 리다이렉트가 발생한다.

즉 이 메서드는 실제 로그인 처리를 수행하는 것이 아니라 OAuth 인증 흐름을 시작하는 역할을 한다.

---

그러면 /signin-google 경로는 어디서 처리되는가?

OAuth 콘솔에서, Authorized redirect URI를 singin-google로 설정해뒀다.

그런데, Controller 그 어디에도 이와 관련된 코드는 없다.

그런데도 잘 동작한다.

앞서 Program.cs 에서 Google OAuth Middleware를 사용하도록 설정했다.

이 미들웨어는 다음 작업을 수행한다.

• 인증 코드 수신
• Google 서버에 Access Token 요청
• 사용자 정보 조회
• 인증 정보 생성

바로 이 미들웨어가 내부적으로 사용하는 callback endpoint가 singin-google 이다.

---

웹 서버 포트 설정

ASP.NET Core 프로젝트는 launchSettings.json 파일을 통해 개발 환경에서 사용할 포트를 설정할 수 있다.

파일 위치는 다음과 같다.

예제에서는 다음과 같이 설정한다.

{
"$schema": "http://json.schemastore.org/launchsettings.json",
"profiles": {
"https": {
"commandName": "Project",
"launchBrowser": true,
"launchUrl": "swagger",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}

여기서 중요한 항목은 applicationUrl이다.

이름에서 알 수 있듯 Url 을 설정하는데,

 

Url은 Google OAuth 콘솔 웹페이지에서 설정에서 등록한 

Authorized redirect URI 와 반드시 일치하도록 설정하자.

 

만약 그렇지 않다면?

예를 들어 이 웹서버의 포트는 9054,

Authorized redirect URI 는 5001/singin-google로 설정했다고 해보자.

 

당연히 클라이언트는 초기 흐름에서 9054로 요청을 보낸다.

웹 서버는 우리의 cliend id와 구글 인증 서버를 클라이언트에게 친절하게 안내 해준다.

클라이언트가 로그인 까지 성공했다.

그런데 이때 받는 주소는 5001/signin-google 이다.

이 주소는 열려 있지 않다.

 

반드시 url을 일치 시키도록 하자.

 

---

인증 이후 Callback 처리

Google OAuth 콘솔을 통해서 Authorized redirect URI를 넣어 두었다.

구글 계정으로 로그인을 성공하면

구글 인증 서버는 클라이언트에게 Authorized redirect URI를 준다.   

ASP.NET Core는 내부적으로 /signin-google 경로에서 인증 코드를 처리한다.

이 과정은 Controller가 아니라 Authentication Middleware 내부에서 처리된다.

Middleware는 Google 서버에 인증 코드를 전달하여 Access Token을 요청하고 이후 사용자 정보를 확인한다.

인증이 완료되면 앞서 컨트롤러에서 설정한 RedirectUri로 다시 리다이렉트가 수행된다.

---

요청 흐름 정리

전체 요청 흐름을 정리하면 다음과 같다.

클라이언트가 /auth/login 요청을 보낸다.
Controller에서 Challenge()가 호출된다.
Authentication Middleware가 Google OAuth 인증 서버로 리다이렉트를 수행한다.
사용자가 Google 로그인 페이지에서 인증을 진행한다.
Google이 인증 코드를 포함해 /signin-google로 리다이렉트한다.
Authentication Middleware가 인증 코드를 처리하고 사용자 정보를 생성한다.
설정된 RedirectUri로 다시 리다이렉트된다.
최종적으로 Controller가 실행된다.

이 흐름에서 중요한 점은 OAuth 인증 처리의 대부분이 Middleware 내부에서 수행된다는 것이다.

---

정리

ASP.NET Core에서 OAuth 로그인 구현은 생각보다 단순하다.

인증 흐름의 대부분은 Middleware 내부에서 처리되기 때문에 Controller에서는

로그인 시작과 로그인 완료 이후의 처리만 구현하면 된다.

중요한 점은 이러한 인증 처리 역시 ASP.NET Core의 요청 처리 구조 위에서 동작한다는 것이다.

HTTP 요청은 웹서버 엔진에서 파싱되고 이후 Middleware 체인을 거쳐 최종적으로 Controller가 실행된다.