basic_auth 지시문

원문 보기 위키 갱신 2026.10.03

basic_auth 지시문 (HTTP 기본 인증)

basic_auth 지시문은 HTTP 기본 인증을 활성화해서, 사용자 이름과 해시된 비밀번호로 디렉터리와 파일을 보호할 수 있게 해줘요.

출처: Caddy 공식 문서

본문

HTTP 기본 인증을 활성화하는데, 사용자 이름과 해시된 비밀번호로 디렉터리와 파일을 보호하는 데 사용할 수 있어요.

기본 인증은 평문 HTTP에서는 안전하지 않다는 점을 주의해요. HTTP 기본 인증으로 무엇을 보호할지 결정할 때 신중하게 판단해요.

사용자가 보호되는 리소스를 요청할 때 아직 사용자 이름과 비밀번호를 제공하지 않았다면 브라우저가 사용자에게 입력을 요구해요. Authorization 헤더에 올바른 자격 증명이 있으면 서버가 리소스 접근을 허용해요. 헤더가 없거나 자격 증명이 틀리면 서버는 HTTP 401 Unauthorized로 응답해요.

Caddy 설정은 평문 비밀번호를 받지 않아요. 설정에 넣기 전에 반드시 해시해야 해요. caddy hash-password 명령이 도움이 돼요.

인증에 성공하면 {http.auth.user.id} placeholder를 사용할 수 있는데, 여기에 인증된 사용자 이름이 들어가요.

v2.8.0 이전에는 이 지시문 이름이 basicauth였는데, 다른 지시문들과 일관성을 맞추기 위해 basic_auth으로 바뀌었어요.

문법 (Syntax)

basic_auth [<matcher>] [<hash_algorithm> [<realm>]] {
	<username> <hashed_password>
	...
}

**<hash_algorithm>**은 이 설정의 해시에 사용되는 비밀번호 해싱 알고리즘(또는 키 유도 함수)을 지정해요. 사용 가능한 옵션에는 argon2id가 있고, 기본값은 bcrypt예요.
****은 커스텀 realm 이름이에요.
****은 사용자 이름 또는 사용자 ID예요.
**<hashed_password>**는 비밀번호 해시예요.

사용자 이름과 해시된 비밀번호는 {env.*} 같은 전역 placeholder를 사용할 수 있으며, config를 로드할 때 대체돼요. 중괄호 안의 다른 텍스트는 그대로 유지돼요.

예시 (Examples)

example.com의 모든 요청에 인증을 요구해요:

example.com {
	basic_auth {
		# 사용자 이름 "Bob", 비밀번호 "hiccup"
		Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
	}
	respond "Welcome, {http.auth.user.id}" 200
}

/secret/의 파일을 Bob만 접근할 수 있게 보호해요(다른 경로는 누구나 볼 수 있음):

example.com {
	root /srv

	basic_auth /secret/* {
		# 사용자 이름 "Bob", 비밀번호 "hiccup"
		Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
	}

	file_server
}

argon2id 예시:

example.com {
	root /srv

	basic_auth /secret/* argon2id {
		# 사용자 이름 "Bob", 비밀번호 "hiccup"
		Bob $argon2id$v=19$m=47104,t=1,p=1$zJPvVe48N64JUa9MFlVhiw$b5Tznu0PxnA4TciY6qYe2BFPxncF1ePQaeNukHhH1cU
	}

	file_server
}

더 알아보기 (Learn more)

Caddy 공식 문서