admin_auth.php 사용 매뉴얼
admin_auth.php 사용 매뉴얼
=================================
개요
----
admin_auth.php는 PHP 웹사이트에 간단하고 안전한 관리자 인증 시스템을
제공하는 범용 라이브러리입니다. 복잡한 설정 없이 한 줄의 코드로
관리자 페이지에 로그인 기능을 추가할 수 있습니다.
주요 특징
---------
- 세션 기반 관리자 인증
- CSRF(Cross-Site Request Forgery) 공격 방지
- 로그인 시도 제한 (무차별 대입 공격 방지)
- IP 변경 감지 및 세션 보안
- Bootstrap 기반 반응형 로그인 UI
- 외부 의존성 최소화 (순수 PHP + Bootstrap CDN)
시스템 요구사항
---------------
- PHP 7.0 이상
- 세션 기능 활성화
- 인터넷 연결 (Bootstrap CDN 사용)
파일 구조
---------
프로젝트 폴더/
├── admin/
│ ├── admin_auth.php (이 파일)
│ ├── index.php (관리자 메인 페이지)
│ ├── products.php (상품 관리 페이지 예시)
│ └── users.php (회원 관리 페이지 예시)
└── config/
└── db_config.php (데이터베이스 설정 - 선택사항)
설치 및 기본 설정
----------------
1단계: 파일 배치
admin_auth.php 파일을 프로젝트의 admin 폴더에 복사합니다.
2단계: 기본 설정 변경
admin_auth.php 파일을 열고 다음 부분을 수정합니다:
$config = [
'admin_password' => 'your_secure_password', // 강력한 비밀번호로 변경
'max_login_attempts' => 5, // 최대 로그인 시도 횟수
'lockout_time' => 900, // 잠금 시간 (초, 기본 15분)
'session_lifetime' => 3600, // 세션 유효 시간 (초, 기본 1시간)
];
보안을 위해 반드시 'your_secure_password'를 강력한 비밀번호로 변경하세요.
사용 방법
---------
기본 사용법:
모든 관리자 페이지 상단에 다음 한 줄을 추가하기만 하면 됩니다:
<?php require_once(__DIR__ . '/admin_auth.php'); ?>
실제 적용 예시:
예시 1: 관리자 메인 페이지 (admin/index.php)
---------------------------------------------
<?php
require_once(__DIR__ . '/admin_auth.php');
?>
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<title>관리자 페이지</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
<div class="container mt-4">
<div class="d-flex justify-content-between align-items-center mb-4">
<h2>관리자 대시보드</h2>
<a href="<?= get_logout_url() ?>" class="btn btn-outline-danger">로그아웃</a>
</div>
<div class="row">
<div class="col-md-6">
<div class="card">
<div class="card-body">
<h5>관리자 정보</h5>
<?php $admin_info = get_admin_info(); ?>
<p>로그인 시간: <?= date('Y-m-d H:i:s', $admin_info['login_time']) ?></p>
<p>세션 남은 시간: <?= gmdate('H:i:s', $admin_info['session_remaining']) ?></p>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
예시 2: 상품 관리 페이지 (admin/products.php)
--------------------------------------------
<?php
require_once(__DIR__ . '/admin_auth.php');
// 데이터베이스 연결 (선택사항)
// require_once(__DIR__ . '/../config/db_config.php');
// 여기에 상품 관리 로직 작성
?>
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<title>상품 관리</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
<div class="container mt-4">
<div class="d-flex justify-content-between align-items-center mb-4">
<h2>상품 관리</h2>
<div>
<a href="index.php" class="btn btn-outline-primary me-2">대시보드</a>
<a href="<?= get_logout_url() ?>" class="btn btn-outline-danger">로그아웃</a>
</div>
</div>
<!-- 여기에 상품 관리 내용 작성 -->
<div class="alert alert-success">
상품 관리 페이지입니다. 관리자 인증이 완료되었습니다.
</div>
</div>
</body>
</html>
제공 함수 목록
--------------
1. is_admin_authenticated()
- 반환값: boolean
- 설명: 현재 사용자가 관리자로 인증되었는지 확인
- 사용법: if (is_admin_authenticated()) { /* 관리자 전용 코드 */ }
2. get_logout_url()
- 반환값: string
- 설명: 로그아웃 URL 생성 (현재 페이지 기준)
- 사용법: <a href="<?= get_logout_url() ?>">로그아웃</a>
3. get_admin_info()
- 반환값: array
- 설명: 관리자 세션 정보 조회
- 반환 배열:
* login_time: 로그인 시간 (timestamp)
* ip: 로그인 IP 주소
* session_remaining: 세션 남은 시간 (초)
보안 기능 상세
--------------
1. CSRF 방지
- 모든 로그인 폼에 자동으로 CSRF 토큰 적용
- 토큰 불일치 시 로그인 거부
2. 로그인 시도 제한
- IP당 최대 5회 시도 (설정 변경 가능)
- 제한 초과 시 15분간 해당 IP 차단
- 성공 로그인 시 카운터 자동 초기화
3. 세션 보안
- 로그인 시 IP 주소 기록
- 세션 중 IP 변경 감지 시 자동 로그아웃
- 세션 만료 시간 체크 (기본 1시간)
4. 기본 보안 헤더
- X-Content-Type-Options: nosniff
- X-Frame-Options: SAMEORIGIN
- X-XSS-Protection: 1; mode=block
고급 설정
---------
1. 비밀번호 보안 강화
기본적으로 평문 비밀번호를 사용하지만, 보안 강화를 원한다면:
$config = [
'admin_password' => password_hash('your_password', PASSWORD_DEFAULT),
// 기타 설정...
];
그리고 로그인 검증 부분을 다음과 같이 수정:
if (password_verify($password, $config['admin_password'])) {
2. 다중 관리자 지원
여러 관리자를 지원하려면:
$config = [
'admin_users' => [
'admin1' => 'password1',
'admin2' => 'password2',
],
// 기타 설정...
];
3. 데이터베이스 연동
사용자 정보를 데이터베이스에 저장하려면 로그인 검증 로직을 수정하여
데이터베이스 쿼리로 인증하도록 변경 가능합니다.
문제 해결
---------
Q: 로그인 페이지가 표시되지 않습니다.
A: 세션이 제대로 시작되었는지 확인하고, PHP 오류 로그를 확인하세요.
Q: 로그인 후 계속 로그인 페이지로 돌아갑니다.
A: 세션 쿠키 설정을 확인하고, 브라우저 쿠키가 활성화되어 있는지 확인하세요.
Q: CSS가 적용되지 않습니다.
A: 인터넷 연결을 확인하고 Bootstrap CDN에 접근 가능한지 확인하세요.
Q: 비밀번호를 잊어버렸습니다.
A: admin_auth.php 파일에서 $config['admin_password'] 값을 새로운 비밀번호로 변경하세요.
Q: 로그인 시도 제한에 걸렸습니다.
A: 15분 기다리거나, admin_auth.php에서 $config['lockout_time'] 값을 줄이세요.
커스터마이징
------------
1. 로그인 페이지 디자인 변경
admin_auth.php 파일 하단의 HTML/CSS 부분을 수정하여
로그인 페이지 디자인을 변경할 수 있습니다.
2. 리다이렉트 경로 변경
로그인 성공 후 특정 페이지로 이동하려면:
header('Location: dashboard.php'); 부분을 수정하세요.
3. 오류 메시지 변경
$error_message 변수에 할당되는 메시지들을 원하는 내용으로 변경 가능합니다.
주의사항
--------
- 프로덕션 환경에서는 반드시 강력한 비밀번호를 사용하세요
- HTTPS 환경에서 사용하는 것을 권장합니다
- 정기적으로 비밀번호를 변경하세요
- 관리자 페이지는 일반 사용자가 접근할 수 없는 경로에 배치하세요
라이선스
--------
이 코드는 자유롭게 사용, 수정, 배포할 수 있습니다.
상업적 용도로도 제한 없이 사용 가능합니다.
버전 정보
---------
Version: 1.0
작성일: 2025-06-07
호환성: PHP 7.0+, Bootstrap 5.3+
문의 및 지원
------------
이 매뉴얼과 함께 제공된 admin_auth.php 파일을 사용하여
안전하고 편리한 관리자 인증 시스템을 구축하시기 바랍니다.
언어: Plain Text