Laravel에서 'TokenMismatchException' 오류 해결법

Laravel에서 'TokenMismatchException' 오류란?

'TokenMismatchException' 오류는 Laravel에서 CSRF(Cross-Site Request Forgery) 보호 기능과 관련된 오류입니다. 이 오류는 사용자가 폼을 제출할 때 서버에서 예상하는 CSRF 토큰과 클라이언트에서 전송한 토큰이 일치하지 않을 경우 발생합니다. CSRF 공격을 방지하기 위해 Laravel은 기본적으로 모든 폼에 CSRF 토큰을 포함시켜 요청을 검증합니다. 이 오류는 보안상의 이유로 발생하지만, 때때로 정상적인 요청에서도 발생할 수 있습니다. 이번 글에서는 'TokenMismatchException' 오류의 원인과 해결 방법을 다룰 것입니다.

'TokenMismatchException' 오류의 주요 원인

'TokenMismatchException' 오류가 발생하는 주요 원인은 다음과 같습니다:

1. CSRF 토큰의 만료: CSRF 토큰은 일정 시간 동안만 유효합니다. 만약 사용자가 폼을 오래 열어두고 제출하면 토큰이 만료되어 오류가 발생할 수 있습니다.
2. 토큰이 올바르게 전달되지 않음: 폼 데이터에서 CSRF 토큰이 누락되었거나, 잘못된 위치에 포함되어 있을 경우 오류가 발생합니다.
3. 브라우저 캐시 또는 쿠키 문제: 브라우저의 캐시나 쿠키에 오래된 CSRF 토큰이 저장되어 있으면 새로운 토큰과 일치하지 않아 오류가 발생할 수 있습니다.
4. 잘못된 AJAX 요청: AJAX 요청에서 CSRF 토큰을 제대로 전달하지 않으면 'TokenMismatchException' 오류가 발생할 수 있습니다.

'TokenMismatchException' 오류 해결 방법

이제 Laravel에서 'TokenMismatchException' 오류를 해결하는 방법을 살펴보겠습니다. 이 오류는 대부분 CSRF 토큰 관리와 관련이 있으므로, 적절한 방법으로 문제를 해결할 수 있습니다.

1. CSRF 토큰을 폼에 포함시키기

Laravel에서는 CSRF 보호를 위해 모든 HTML 폼에 CSRF 토큰을 포함시켜야 합니다. 이를 위해, 폼에 @csrf 디렉티브를 사용해야 합니다. 이 디렉티브는 자동으로 CSRF 토큰을 생성하고 폼에 숨겨진 필드로 추가해줍니다.

예를 들어, 아래와 같이 폼을 작성할 때:

위 코드에서 @csrf는 CSRF 토큰을 자동으로 삽입합니다. 이 방법을 사용하면 CSRF 토큰이 올바르게 포함되어 'TokenMismatchException' 오류를 방지할 수 있습니다.

2. CSRF 토큰 유효성 검사 시간 연장

CSRF 토큰은 일정 시간이 지나면 만료되기 때문에, 폼 제출 시 토큰이 만료된 경우 오류가 발생할 수 있습니다. 이 문제를 해결하려면 CSRF 토큰의 유효 기간을 늘릴 수 있습니다. Laravel에서는 config/session.php 파일을 수정하여 세션 시간과 함께 CSRF 토큰의 유효 시간을 조정할 수 있습니다.

config/session.php 파일에서 lifetime 값을 수정하여 세션의 유효 시간을 연장할 수 있습니다:

'lifetime' => 120, // 세션 유효 시간을 120분으로 설정

세션 시간이 길어지면 CSRF 토큰이 더 오래 유효하므로, 폼 제출 시 만료되지 않도록 할 수 있습니다.

3. AJAX 요청에서 CSRF 토큰 전달

AJAX 요청을 통해 서버와 상호작용할 때도 CSRF 토큰을 전달해야 합니다. Laravel에서는 AJAX 요청 시 CSRF 토큰을 헤더에 포함시켜야 합니다. jQuery를 사용하는 경우, 다음과 같이 CSRF 토큰을 자동으로 AJAX 요청에 추가할 수 있습니다:

$(document).ready(function() {
    $.ajaxSetup({
        headers: {
            'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
        }
    });
});

위 코드에서는 meta 태그에서 CSRF 토큰을 가져와 AJAX 요청의 헤더에 추가합니다. 이렇게 하면 Laravel에서 CSRF 토큰을 제대로 인식하고 'TokenMismatchException' 오류를 방지할 수 있습니다.

4. 브라우저 캐시 및 쿠키 문제 해결

브라우저의 캐시나 쿠키에 오래된 CSRF 토큰이 저장되어 있으면 새로운 토큰과 일치하지 않아 오류가 발생할 수 있습니다. 이 경우, 브라우저 캐시를 지우고 쿠키를 삭제한 후 다시 시도해 보세요. 또한, 웹 브라우저의 시크릿 모드(Incognito Mode)에서 테스트를 진행해보는 것도 좋은 방법입니다.

브라우저 캐시나 쿠키를 지우는 방법은 각 브라우저에 따라 다르므로, 사용하는 브라우저의 설정에서 캐시와 쿠키를 삭제하는 옵션을 찾아 이를 제거하세요.

5. CSRF 예외 처리

Laravel은 기본적으로 CSRF 보호 기능을 모든 POST 요청에 적용하지만, 특정 요청에서는 CSRF 보호를 비활성화해야 할 경우도 있을 수 있습니다. 예를 들어, 웹훅(Webhook) 요청 등에서는 CSRF 보호가 필요하지 않습니다.

이 경우, VerifyCsrfToken 미들웨어를 수정하여 예외를 설정할 수 있습니다. app/Http/Middleware/VerifyCsrfToken.php 파일을 열고, $except 배열에 CSRF 보호에서 제외할 URL을 추가하세요:

protected $except = [
    'webhook/*',
];

위와 같이 설정하면 '/webhook/*' 경로로 들어오는 요청은 CSRF 보호에서 제외됩니다.

6. 서버의 세션 설정 점검

서버의 세션 설정이 잘못되어 'TokenMismatchException' 오류가 발생할 수도 있습니다. 세션 드라이버 설정이 잘못되었거나 세션 저장소가 제대로 작동하지 않으면 CSRF 토큰을 유지할 수 없습니다. config/session.php 파일에서 세션 드라이버를 확인하고, 디스크 또는 데이터베이스 세션을 사용하고 있다면 해당 설정이 올바른지 확인해보세요.

예를 들어, 디스크 세션을 사용하는 경우, SESSION_DRIVER가 'file'로 설정되어 있어야 하며, 세션 저장소가 정확히 지정되어야 합니다:

SESSION_DRIVER=file
SESSION_LIFETIME=120

결론

'TokenMismatchException' 오류는 주로 CSRF 보호와 관련된 문제로 발생하며, Laravel에서 보안을 강화하기 위해 CSRF 토큰을 자동으로 처리하고 있습니다. 이 오류를 해결하려면 폼에 올바른 CSRF 토큰을 포함시키고, AJAX 요청에서도 토큰을 적절히 전달해야 합니다. 또한, CSRF 토큰의 유효 시간을 조정하거나 브라우저 캐시 및 쿠키 문제를 해결하는 방법을 고려할 수 있습니다. 이러한 방법들을 통해 'TokenMismatchException' 오류를 예방하고, 안정적인 Laravel 애플리케이션을 운영할 수 있습니다.

blogfine 님의 블로그