👩🏻‍💻 Supabase로 OAuth Login을 구현하면서 Supabase와 OAuth 공급자 간 통신과, OAuth Login 과정에 대해 이해하기 위해 공부한 내용입니다. 설정과 관련된 게시글은 아래로 이동해 주세요.

• Kakao OAuth Login with supabase
• Google OAuth Login with supabase

🌱 OAuth

요즘 많은 애플리케이션은 회원가입을 요구하기도 하지만, 이미 사용 중인 다른 사이트의 계정을 통해 간편하게 가입하거나 로그인할 수 있는 방식도 함께 제공합니다. 매번 이름이나 이메일 같은 정보를 하나하나 입력하지 않아도 되고, 클릭 한 번으로 끝나기 때문에 매우 편리하죠.

이렇게 타 사이트의 계정으로 다른 서비스를 사용할 수 있게 해주는 것이 OAuth입니다. OAuth는 다른 서비스가 내 계정 정보에 안전하게 접근할 수 있도록 해줍니다.

예를 들어, ‘구글로 로그인하기’ 버튼을 클릭하면, 애플리케이션은 사용자의 구글 계정 비밀번호를 몰라도, 구글에서 인증된 정보를 받아와 안전하게 로그인을 처리합니다. 이를 통해 사용자 입장에서는 편리함을, 애플리케이션은 보안을 강화할 수 있습니다.

사용자 편의성을 높이기 위해, 프로젝트에서 OAuth 인증 방식을 구현하면서 OAuth 2.0의 인증 과정이 어떻게 작동하는지, 그리고 Supabase 같은 플랫폼에서 OAuth를 어떻게 구현하는지를 알아보았습니다.

☀️ 기본 개념

앞으로 설명할 supabase의 인증 흐름에서 쓰이는 방식과 인증 시 서버 간 통신에 쓰이는 다양한 개념들에 대해 먼저 알아보겠습니다.

1. OAuth Flow (인증 흐름): Authorization Code Grant

OAuth 2.0에서는 주로 Authorization Code Grant와 Implicit Grant＊ 두 가지 방식이 사용됩니다.

Supabase OAuth는 그 중 Authorization Code Grant를 기반으로 합니다. OAuth 2.0에서 가장 많이 사용되는 인증 흐름 중 하나로, 보안성이 뛰어나고 클라이언트 애플리케이션과 서버 간의 통신을 안전하게 처리하는 방법입니다.

특 징

• 클라이언트가 직접 자격 증명을 다루지 않고, 인증 코드(Authorization Code)를 통해 보안을 유지하며 액세스 토큰을 발급받습니다.

• 액세스 토큰을 서버에서 처리해 자격 증명이 노출될 위험이 줄어들고, 민감한 정보를 클라이언트 측에 노출하지 않도록 설계되어 있습니다. 즉, 서버가 토큰을 처리하고 보관하는 구조로 클라이언트 측의 보안 위험이 줄어듭니다.

• 리프레시 토큰을 통해 액세스 토큰 만료시에 사용자는 다시 로그인할 필요 없이 새롭게 토큰을 받을 수 있습니다.

• BUT, 다른 OAuth 흐름에 비해 비교적 복잡합니다. Redirect URI, Client Secret등 설정이 필요하고 서버가 반드시 필요합니다.

🆚

Implicit Grant

클라이언트 애플리케이션이 바로 액세스 토큰을 받는 방식입니다. 모든 인증 절차가 클라이언트 측에서 이루어지며 서버에서 권한 코드를 교환하는 과정이 생략됩니다.
서버를 거치지 않기 때문에 사용자 경험이 빠르고 간편한 대신 클라이언트 측에서 토큰을 직접 취급하여 상대적으로 보안 수준이 낮습니다.
👉🏻 보안 문제로 인해 OAuth 2.0 최신 권고에서는 Implicit Grant 사용을 지양합니다.

• 토큰에 대한 처리를 브라우저나 자바스크립트 코드로 처리하므로 탈취 위험이 크고, 악의적 공격에 취약할 수 있습니다.
• URL의 해시 파라미터로 전달되어 노출되는 액세스 토큰은 브라우저 기록에는 남지 않지만, 다른 방법으로 탈취될 위험이 있어 클라이언트 측에서 안전하게 관리해야 합니다.
• 리프레시 토큰을 따로 발급하지 않아, 액세스 토큰 만료시에 사용자가 다시 로그인을 해야합니다. 이때 토크 갱신을 위한 추가적인 보안 절차가 없어 보안 수준이 낮습니다.
• 주로 서버가 없는 클라이언트 애플리케이션에서 사용됩니다.

---

특징	Authorization Code Grant	Implicit Grant
보안성	높음(서버가 토큰을 처리)	낮음(클라이언트가 토큰을 처리)
서버 필요 여부	필요	불필요
액세스 토큰 획득 방식	권한 코드를 받은 후, 서버에서 교환	클라이언트가 곧바로 받음
리프레시 토큰	지원하므로 액세스 토큰 만료시 갱신 가능	미지원
사용사례	서버 기반 애플리케이션	SPA, 모바일 앱, 서버없는 클라이언트
토큰 보안	서버에서 처리하므로 보안수준이 높음	URL 해시에 노출되며, 클라이언트가 관리
OAuth 2.0 권고사항	권장	지양

---

2. Redirect URI

클라이언트와 OAuth 서버 간의 통신 경로로, OAuth 제공자(google, kakao 등)가 로그인 성공 후, 인증 코드를 보낼 URI입니다. 즉, 인증 후 OAuth 서버가 클라이언트 애플리케이션으로 돌아올 때 사용합니다.

따라서, supabase와 OAuth 공급자에 동일하게 설정되어 있어야 합니다. 만약, OAuth 공급자 설정의 Redirect URI와 Supabase의 설정이 일치하지 않으면, OAuth과정이 중단됩니다.

설정 이유

• OAuth 제공자는 인증 결과(인증 코드)를 애플리케이션으로 다시 전송해야 하는데, 미리 등록된 Redirect URI로만 인증코드를 전송함으로써 OAuth 공격을 방지합니다. 안전한 통로역할을 함으로써, 등록되지 않은 URI로 redirect 요청을 하면 인증을 거부함으로써 악의적인 인증 탈취 및 정보 유출을 방지합니다.

• OAuth 2.0 보안 원칙 중 하나인 '인증 과정에서 권한 코드나 액세스 토큰이 미리 등록된 신뢰할 수 있는 경로로만 전달되어야 한다'를 지킵니다.

---

3. Client ID & Client Secret

서버 간 통신에서 OAuth 제공자가 클라이언트 애플리케이션을 식별하고 권한을 부여하는 데 사용하는 자격 증명입니다.

서버 간 통신에서만 사용되며, 클라이언트 측에서 노출되어선 안됩니다. 보관할 때도 환경변수 등의 안전한 방식을 사용해 보관해야 합니다. 노출 시 공격자가 클라이언트 애플리케이션으로 가장하여 OAuth 제공자로부터 액세스 토큰을 요청할 수 있습니다. 따라서 전송시에는 반드시 HTTPS를 사용해야 합니다.

🆚

Implicit Grant 흐름에서는, 브라우저에서 직접 Access Token을 요청하는 방식이기 때문에 Client Secret이 노출될 위험이 있어 사용되지 않습니다.

Client ID

Client ID는 OAuth 제공자가 클라이언트 애플리케이션을 식별하는 데 사용하는 고유한 식별자로 쉽게 말하면, 애플리케이션의 ID에 해당합니다.

OAuth 제공자는 클라이언트 애플리케이션이 신뢰할 수 있는 애플리케이션임을 확인하기 위해 이 ID를 발급합니다. 인증 요청시 파라미터에 필수로 포함되어, 인증을 보낸 애플리케이션이 어떤 애플리케이션인지 파악하고, 등록된 애플리케이션인지 확인합니다.

Client Secret

Client ID만으로는 공격자가 쉽게 클라이언트로 위장할 수 있어 요청을 완전히 신뢰할 수 없습니다. 클라이언트 애플리케이션을 더욱 안전하게 인증하기 위해 OAuth 제공자가 발급하는 비밀 키입니다.

액세스 토큰을 요청할 때 Client ID와 함께 보내어 신뢰할 수 있는 애플리케이션임을 증명하는 데 쓰입니다. 클라이언트 애플리케이션이 허위로 Access Token을 요청하는 것을 방지하는 데 중요한 역할을 합니다.

---

4. Access Token (액세스 토큰) & Refresh Token (리프레시 토큰)

Supabase는 Access Token과 Refresh Token을 자동으로 처리해 사용자가 복잡한 토큰 관리 작업을 하지 않도록 도와줍니다. 사용자의 로그인 상태를 유지하고, 토큰을 갱신하는 과정을 처리합니다.

Access Token (액세스 토큰)

• 클라이언트 애플리케이션이 사용자의 데이터를 보호된 API로부터 접근 할 수 있도록 권한을 부여하는 단기 유효 토큰입니다. 보통 몇 분에서 몇 시간 정도로 유효기간이 짧습니다.

• API 요청을 보낼 때 이 토큰을 사용하여 사용자의 권한을 인증합니다. supabase는 요청시 액세스 토큰을 자동으로 포함시킵니다.

Refresh Token (리프레시 토큰)

• 리프레시 토큰은 액세스 토큰이 만료되었을 때, 새로운 액세스 토큰을 발급받기 위한 장기 유효 토큰입니다. 유효기간이 길며, 사용자가 재로그인하지 않고도 인증을 유지할 수 있게 합니다.

• 보통 클라이언트 측에 저장되며,*Supabase가 자동으로 토큰을 갱신하는 데 사용됩니다.

---

5. State parameter

요청이 외부에서 변조되는 것을 방지하고 안전한 인증 과정을 유지하기 위해 사용되는 임의의 값입니다.

Supabase는 내부적으로 암호화된 방식으로 State 파라미터를 자동 생성하여 OAuth 제공자에게 함께 전송합니다. 개발자는 직접적으로 State 값을 생성하거나 검증할 필요 없어 부담이 적습니다.

State 값은 고유하며 각 OAuth 요청에 대해 새로운 값을 생성하여 요청이 도중에 변조되거나 가로채질 가능성을 차단해 보안 위협을 최소화합니다. 또 인증 과정 중 클라이언트는 여러 요청을 처리하는 데, 같은 사용자가 여러 번 인증 요청을 보내더라도 각 요청은 고유한 State값을 가져 어떤 요청에 대한 응답인지 추적하는 데 사용됩니다.

OAuth 제공자가 리디렉션 요청을 클라이언트에게 다시 보낼 때 포함됩니다. supabase는 반환한 State 값을 내부적으로 확인하여 요청이 변조되지 않았는 지 검증합니다. 이 과정은 자동으로 처리되어 보안 상의 실수를 예방합니다.

특히 State 파라미터는 공격자가 OAuth 인증 흐름을 가로채서 악의적인 요청을 클라이언트에게 보내는 CSRF 공격＊을 방지하기 위해 중요한 보안요소입니다. State 값을 통해 OAuth 제공자가 전송하는 리디렉션이 신뢰할 수 있는 출처에서 온 것임을 확인해 무결성을 보장합니다.

📍 CSRF(Cross-Site Request Forgery) 공격

인증된 사용자 권한을 악용해 사용자가 의도하지 않은 요청을 서버로 보내는 공격입니다. 즉, 사용자 로그인 상태를 이용해 사용자가 인지하지 못한 상태에서 다른 웹사이트에서 사용자 권한으로 서버에 인증된 요청을 보낼 수 있습니다.

• 웹 브라우저가 로그인된 상태에서 요청을 보낼 때 자동으로 해당 도메인의 쿠키를 함께 전송하여 인증을 하는 기능을 악용하는 것입니다.
• 사용자의 중요한 데이터(계좌 이체, 사용자 정보 등)를 공격자가 마음대로 바꿀 수 있습니다.
• 사용자는 요청 사실을 인지하지 못하므로, 공격을 알아차리기 힘듭니다.

---

방어방법
서버 측에서 요청이 진짜 사용자로부터 온 것인지 확인하는 절차를 추가하여 방어할 수 있습니다.

• CSRF 토큰을 사용하는 것이 가장 일반적인 방법입니다. CSRF 토큰은 서버에서 생성한 고유의 난수로, 요청마다 클라이언트에 전달하고, 클라이언트가 다시 서버로 전송함으로써 확인하는 방식입니다.
• 서버는 요청의 Referer 헤더의 출처를 확인하고, 올바른 출처인 경우에만 응답하고, 다른 출처라면 차단할 수 있습니다. 하지만, 브라우저 설정이나 프록시로 Referer 헤더가 제거될 수 있어 신뢰도가 낮을 수 있습니다.
• SamSite 쿠키 속성을 설정해 요청이 동일한 사이트에서 발생한 경우에만 쿠키를 전송하도록 제한할 수 있습니다. 외부 웹사이트에서 발생한 요청에는쿠기가 자동으로 전송되지 않아 방지할 수 있습니다.

  Set-Cookie: sessionid=xyz; SameSite=Strict

---

☀️ Supabase OAuth Authentication Flow

본격적으로 supabase에서 OAuth를 사용해 로그인할 때 처리되는 과정을 알아봅니다. (예시는 Kakao OAuth 인증으로 하였습니다.)

STEP 1. OAuth 인증 서버로 인증 요청

사용자가 OAuth 제공자로 로그인할 때, 애플리케이션은 client_id, redirect_url, response_type=code(인증 코드 요청), scope(요청 권한 범위), state를 포함하여 OAuth 인증 서버로 요청을 보냅니다.

https://kauth.kakao.com/oauth/authorize?
  response_type=code&
  client_id={CLIENT_ID}&
  redirect_uri=https://{application address}/callback&
  scope=profile,email

👇🏻 Kakao OAuth를 요청할 때의 서버 통신 모습을 보면 통신을 하는 OAuth 제공자 서버를 확인할 수 있고, client_id, redirect_uri, response_type=code, scope, state와 같은 정보를 함께 보내는 것을 확인할 수 있습니다.

• OAuth 2.0은 민감한 정보를 주고받기 때문에 HTTPS를 반드시 사용해야 합니다. 그렇지 않으면 액세스 토큰이나 인증 코드가 공격자에게 노출될 위험이 있습니다.

• redirect_uri는 사전 등록된 URI여야 합니다.

• State 값(eyJhb~)은 자동으로 supabase가 임의로 생성하여 포함시킵니다.

애플리케이션은 OAuth 제공자에게 사용자가 인증 페이지로 이동하도록 리디렉션합니다.

STEP 2. 사용자가 권한을 부여 & 인증 코드 발급

사용자가 OAuth 제공자에서 인증을 완료하면, OAuth 서버는 인증 코드(Authorization Code)와 초기 요청시 애플리케이션이 보냈던 state 파라미터를 포함해 등록된 Redirect URI로 리디렉션합니다.

https://{application address}/callback?code={AUTHORIZATION_CODE}&state={STATE_VALUE}

• 애플리케이션은 리디렉션된 URI에서 받은 state값을 처음 생성한 값과 비교 검증해 CSRF 공격과 변조된 요청을 방지합니다. (STEP 1의 예시 사진속 state와 같은 값으로 eyJhb~으로 시작하는 것을 확인할 수 있습니다.)

  • 일치하지 않는 경우, 요청이 변조되었거나 다른 출처에서 발생한 요청일 가능성이 있어 supabase는 해당 요청을 거부하고 처리하지 않습니다.

• 인증 서버가 발급한 인증 코드는 일회용이며, 일정 시간이 지나면 만료됩니다.

STEP 3. 인증 코드를 액세스 토큰으로 교환

• 애플리케이션은 전달받은 인증 코드를 서버(supabase)로 전달하고, 서버는 이 인증 코드를 사용해 OAuth 제공자(kakao)에게 액세스 토큰과 리프레시 토큰을 요청하는 POST 요청을 보냅니다.

POST /token
Host: oauth.provider.com
Content-Type: application/x-www-form-urlencoded
------------------------------
grant_type=authorization_code&
code={AUTHORIZATION_CODE}&
redirect_uri=https://{application address}/callback&
client_id={CLIENT_ID}&
client_secret={CLIENT_SECRET}

• 요청시 Redirect URI를 함께 전달해, OAuth 서버가 최초에 사용한 URI와 일치하는지 확인하는 데 사용합니다. 이 때 동일하지 않으면 요청을 거부함으로써 권한 코드 남용을 방지합니다.

• 토큰 요청 시에는 Client_id와 Client_secret이 함께 사용됩니다. 이를 통해 OAuth 제공자에게 신뢰할 수 있는 애플리케이션임을 증명하고, 등록된 애플리케이션임을 확인하도록 합니다.

• 이 때, 잘못된 Client_id, Client_secret을 사용해 자격 증명이 안되거나, 잘못된 redirect_uri를 설정한 경우, 인증 코드가 잘못되어 인증 오류가 발생한 경우 인증 실패가 발생할 수 있습니다.

SETP 4. 액세스 토큰과 리프레시 토큰 받기

OAuth 제공자는 요청을 검증하고, 유효하다면 액세스 토큰과 리프레시 토큰을 발급합니다.

• expires_at은 토큰의 발급 일시입니다. expires_in은 액세스 토큰의 유효 시간입니다.

• 액세스 토큰은 사용자의 자원에 접근할 수 있는 권한을 부여하고, 리프레시 토큰은 액세스 토큰이 만료되었을 때 새로운 액세스 토큰을 발급받는 데 사용됩니다.

서버(supabase)는 받은 액세스 토큰을 사용해 사용자가 보호된 리소스에 접근할 수 있도록 합니다. OAuth 제공자(kakao)로부터 데이터를 가져와 애플리케이션(client)에 전달해 인증된 세션을 관리합니다.

---

☀️ Post-Authentication (인증 후)

Supabase는 사용자가 로그인한 후, 해당 사용자의 액세스 토큰을 받아 자동으로 관리합니다. 사용자는 토큰의 유효성이나 만료에 대해 신경 쓸 필요가 없으며, 클라이언트 애플리케이션이 별도로 처리할 필요가 없습니다.

토큰 안전 저장

클라이언트 애플리케이션에서 액세스 토큰과 리프레시 토큰을 안전하게 저장하는 것이 중요합니다. 특히 액세스 토큰은 클라이언트에서 API 호출 시 사용되므로 클라이언트 측에서 저장 방식에 주의해야 합니다.

잘못된 저장 방식은 토큰 탈취로 이루어질 수 있고, 토큰이 유출되면 제3자가 사용자의 자원에 접근할 수 있습니다.

따라서, 다음과 같은 안전한 저장 방법을 고려해야 합니다.

(1) Local Storage 또는 Session Storage

• Local Storage는 클라이언트 측에서 사용자가 브라우저를 닫아도 데이터를 유지할 수 있는 공간입니다. Session Storage는 브라우저 세션이 끝날 때까지 데이터를 저장합니다.
• Local Storage는 XSS(크로스 사이트 스크립팅) 공격에 취약할 수 있기 때문에, 액세스 토큰과 같은 민감한 정보를 Local Storage에 저장하는 것은 권장되지 않습니다.

(2) HTTP-Only 쿠키

• HTTP-Only 쿠키는 안전한 저장소로 XSS 공격으로부터 보호할 수 있는 더 안전한 옵션입니다. 이 쿠키는 자바스크립트에서 접근할 수 없으며, 자동으로 서버로 전송됩니다.
• 클라이언트 애플리케이션은 HTTP-Only 쿠키를 사용하여 Access Token과 Refresh Token을 관리할 수 있습니다.

토큰 만료 관리

• 액세스 토큰이 만료된 경우, 리프레시 토큰을 사용해 새로운 액세스 토큰을 요청할 수 있습니다. 이 때, 권한 범위(scope)를 최소한으로 설정하여 필요한 권한만 요청해야 합니다.

• 리프레시 토큰이 만료되거나 네트워크 오류로 갱신 과정에서 문제가 발생할 경우, Supabase는 사용자를 로그아웃 처리하고, 재로그인을 유도할 수 있습니다.

• OAuth 토큰을 주고받을 때는 반드시 HTTPS를 사용하여 네트워크 상에서 토큰이 노출되지 않도록 합니다.

(1) 액세스 토큰 만료

액세스 토큰은 보통 짧은 유효 기간을 가지며, 만료된 후에는 더 이상 사용할 수 없습니다. 액세스 토큰이 만료되면, 사용자가 보호된 리소스에 접근하려 할 때 401 Unauthorized 오류가 발생합니다.

Supabase는 이런 오류가 발생하지 않도록 만료되면 자동으로 리프레시 토큰을 사용해 새로운 액세스 토큰을 발급받습니다.

이 자동화된 과정에서, Supabase가 토큰 만료 시간이 다가오기 전에 미리 재인증 요청을 보내는 것은 아닙니다.

액세스 토큰이 만료된 후, API 요청을 처리하는 도중에 액세스 토큰이 만료된 것을 감지하면, 리프레시 토큰을 사용해 OAuth 제공자에게 새로운 액세스 토큰을 요청하고 새롭게 발급받아 사용자 세션을 갱신해 로그인 상태를 유지합니다.

(2) 리프레시 토큰 만료

리프레시 토큰은 장기적으로 유효하지만, 일정 시간이 지나거나 사용자가 로그아웃하거나 보안상의 이유로 만료될 수 있습니다.

리프레시 토큰이 만료되면 새로운 액세스 토큰을 발급받을 수 없으며, 사용자는 로그아웃 상태로 처리됩니다.

리프레시 토큰이 만료된 상태에서는 세션을 복구할 수 없기 때문에, 클라이언트는 사용자를 로그인 페이지로 리디렉션하여 다시 로그인하도록 해야 합니다.

(3) 자동 로그아웃 처리

만약 Access Token과 Refresh Token 모두 만료된 경우, Supabase는 자동으로 세션을 종료하고, 사용자를 로그아웃 처리합니다. 클라이언트 애플리케이션은 이러한 로그아웃 상황을 감지하고, 로그인 페이지로 리디렉션해야 합니다.

supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'SIGNED_OUT') {
    console.log('사용자가 로그아웃되었습니다.');
    window.location.href = '/login';  // 로그인 페이지로 리디렉션
  }
});

• onAuthStateChange: Supabase는 인증 상태가 변경되었을 때 이벤트를 발생시킵니다. 이 이벤트를 감지하여 사용자가 로그아웃되었을 때 처리할 수 있습니다.

⛓️‍💥

수동 로그아웃

Supabase는 자동으로 토큰 갱신을 처리므로 사용자가 로그아웃하지 않는 한 로그인 세션이 유지됩니다. 따라서 로그아웃할 때는 액세스 토큰과 리프레시 토큰을 모두 삭제해야 합니다.

• Supabase는 auth.signOut() 메서드를 호출하여 세션을 종료하고, 관련 토큰을 무효화하여 사용자가 더 이상 보호된 리소스에 접근할 수 없도록 만듭니다.

await supabase.auth.signOut();

Error handling

OAuth 인증 과정에서 통신 중 인증 실패, 토큰 만료 등의 오류가 발생할 수 있습니다. 이러한 오류는 액세스 토큰의 만료, 리프레시 토큰의 유효성 문제, 네트워크 오류 등 다양한 이유로 발생할 수 있습니다. 이를 올바르게 처리하면 사용자 경험을 향상시키고 보안을 유지하는 데 도움이 됩니다.

Supabase에서 이러한 오류들을 자동으로 처리해주는 경우가 많지만, 클라이언트 애플리케이션에서도 오류를 감지하고 적절히 처리할 수 있는 로직을 추가해야 합니다.

인증 실패 처리

OAuth 인증 과정에서 인증 실패가 발생할 수 있습니다. 잘못된 클라이언트 자격 증명이나 설정 오류가 원인일 수 있으며, 인증 실패 시 사용자에게 오류 메시지를 보여주고, 다시 시도하거나 로그인 페이지로 유도할 수 있습니다.

const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'kakao',
  options: {
    redirectTo: 'https://{application address}/callback',
  }
});

if (error) {
  console.error("인증 실패:", error.message);
  alert("인증에 실패했습니다. 다시 시도해 주세요.");
} else {
  console.log("인증 성공:", data);
}

이 떄, 개발자는 잘못된 Client ID, Client Secret, Redirect URI 설정을 점검할 수 있습니다.

네트워크 오류 처리

네트워크 오류는 일시적인 문제가 될 수 있으므로 재시도 로직을 구현하는 것이 좋습니다. 네트워크 불안정으로 인해 요청이 실패하면, 요청을 다시 시도하거나 일정 시간 후에 다시 시도하도록 처리할 수 있습니다.

👀 추가로, User Agent

supabase에서 log로 OAuth 통신을 살펴볼 수 있습니다. 이 때, 요청 URL 뒤에 있는 부분이 User Agent 입니다.

클라이언트가 서버와 통신할 때, 요청을 보내는 디바이스와 브라우저 등 식별할 수 있는 사용자 소프트웨어의 정보를 말합니다. 임의로 수정될 수 없는 값으로, 요청을 보낸 사용자 환경을 알아보기 위해 사용됩니다. 따라서 개발자 도구의 네트워크에서 Request Headers에서도 확인할 수 있습니다.

• 서버는 User Agent를 통해 클라이언트가 어떤 브라우저나 앱을 사용하고 있는지 파악해, 모바일 기기와 데스크탑을 구분하여 각기 다른 사용자 인터페이스를 제공하고, 특정 브라우저에 최적화된 콘텐츠를 제공하거나 특정 기능을 차단하는 등의 작업을 합니다.

• 로그에 요청마다 User Agent가 기록되므로, 서버 관리자는 클라이언트 종류와 버전 분포를 파악할 수 있습니다.

예 시

보통 Mozilla 정보/버전 + 운영체제 정보 + 렌더링 엔진 정보 + 브라우저 형태로 노출됩니다.

Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Mobile Safari/537.36

• Mozila/5.0: User Agent 문자열의 일반적인 시작 부분입니다. 접속한 브라우저가 Mozila와 호환됨을 표시하는 것으로 대부분의 브라우저에서 호환성을 위해 포함합니다.
• (Linux; Android 6.0; Nexus 5 Build/MRA58N)
  • Linux: 요청을 보낸 장치의 운영 체제가 Linux 기반임을 나타냅니다. Android는 Linux 커널 위에서 실행되므로 이 부분은 Android 운영 체제를 의미합니다.
  • Android 6.0: Android 운영 체제의 버전을 나타냅니다.
  • Nexus 5: 장치의 모델로 Google Nexus 5 스마트폰에서 발생한 요청임을 나타냅니다.
  • Build/MRA58N: 해당 Android 운영 체제의 특정 빌드 번호입니다.
• AppleWebKit/537.36 (KHTML, like Gecko)
  • AppleWebKit/537.36: HTML 및 CSS를 처리하는 데 사용되는 렌더링 엔진인 WebKit을 나타냅니다. Safari와 Chrome 브라우저에서 사용됩니다.
  • (KHTML, like Gecko): 이 문자열은 과거 KHTML과 Gecko 엔진과의 호환성을 위해 사용됩니다. KHTML은 원래 Konqueror 브라우저에서 사용된 엔진이며, Gecko는 Mozilla Firefox의 렌더링 엔진입니다. 이는 WebKit이 Gecko처럼 동작함을 나타냅니다.
• Chrome/128.0.0.0: 사용 중인 웹 브라우저가 Chrome 브라우저임을 나타냅니다. 128.0.0.0은 Chrome 브라우저의 버전으로 일반적으로 최신 버전의 Chrome이 100 이상으로, 128 버전은 최신 버전임을 나타냅니다.
• Mobile Safari/537.36: Safari 브라우저의 모바일 버전과 호환성을 나타냅니다. WebKit 기반의 브라우저는 호환성을 위해 Safari의 User-Agent 문자열을 포함하는 경우가 많습니다.