개발 서버의 API 문서에 "Basic 인증을 사용합니다"라고만 적혀 있고, Postman 헤더 칸에 무엇을 넣어야 할지 막막한 순간이 있죠. 정답은 한 줄이에요. Authorization: Basic 다음에 아이디:비밀번호를 UTF-8 바이트로 바꿔 Base64로 인코딩한 값을 붙이면 돼요. 아이디 admin, 비밀번호 secret이면 Authorization: Basic YWRtaW46c2VjcmV0이 완성돼요.
만드는 건 쉬운데 막히는 건 대개 그다음이에요. 같은 헤더인데 어떤 서버는 401을 돌려주고, 한글 비밀번호는 깨지고, 터미널에서 만든 값을 붙였더니 안 되기도 해요. 이 글은 규격(RFC 7617)이 정한 규칙과 직접 계산한 예시로 어디서 틀어지는지 짚는 순서를 정리했어요.
Basic 인증은 무엇이고 어떻게 오가나요
Basic 인증은 HTTP가 기본으로 제공하는 가장 단순한 인증 방식이에요. 흐름은 세 번의 왕복이면 끝나요.
- 클라이언트가 인증 없이 주소를 요청해요.
- 서버가
401 Unauthorized와 함께WWW-Authenticate: Basic realm="admin"헤더로 "Basic 방식으로 인증하세요"라고 알려 줘요. - 클라이언트가
Authorization: Basic …헤더를 붙여 다시 요청하고, 맞으면200을 받아요.
API 호출은 처음부터 Authorization 헤더를 붙여 보내는 경우가 많아서 1~2단계가 생략돼요. 브라우저는 2단계에서 아이디·비밀번호 입력창을 띄우고, 입력한 값을 기억해 같은 사이트 요청에 헤더를 자동으로 붙여요.
헤더를 만드는 4단계
규격이 정한 순서는 이게 전부예요. admin / secret으로 따라가 볼게요.
| 단계 | 하는 일 | 결과 |
|---|---|---|
| 1 | 아이디와 비밀번호를 콜론으로 잇기 | admin:secret |
| 2 | UTF-8 바이트로 바꾸기 | 12바이트 |
| 3 | Base64 인코딩 | YWRtaW46c2VjcmV0 |
| 4 | 앞에 Basic 붙이기 | Basic YWRtaW46c2VjcmV0 |
터미널에서는 echo -n 'admin:secret' | base64가 같은 값을 줘요. 여기서 -n을 빼먹으면 끝에 줄바꿈이 함께 인코딩돼서 YWRtaW46c2VjcmV0Cg==처럼 전혀 다른 값이 나와요. 이 실수가 가장 흔해서 아래에서 다시 다뤄요.
curl은 이 과정을 알아서 해 줘요. curl -u admin:secret https://example.com/api라고 쓰면 같은 Authorization 헤더를 만들어 보내요. 다른 요청 도구의 설정을 curl 형태로 바꾸고 싶다면 cURL 변환기가 도움이 돼요.
직접 계산한 길이표: 헤더가 얼마나 길어지나요
Base64는 3바이트를 4글자로 바꿔서 원본보다 약 33% 커지고, 3의 배수가 아니면 =로 길이를 맞춰요. 공식으로는 4 × ⌈바이트 ÷ 3⌉예요. 몇 가지를 직접 계산했어요.
| 입력 | 바이트 수 | Base64 글자 수 | 값 |
|---|---|---|---|
api:a:b | 7 | 12 | YXBpOmE6Yg== |
user:pass123 | 12 | 16 | dXNlcjpwYXNzMTIz |
admin:secret | 12 | 16 | YWRtaW46c2VjcmV0 |
홍길동:비번 | 16 | 24 | 7ZmN6ri464+ZOuu5hOuyiA== |
한글 홍길동:비번은 글자 수로는 6글자인데 UTF-8로는 16바이트(한글 5글자 × 3 + 콜론 1)예요. 영문 비밀번호보다 헤더가 길어진다는 뜻이고, 헤더 길이를 제한하는 프록시가 있다면 염두에 둘 만해요.
콜론이 문제가 되는 이유
서버는 풀린 문자열에서 첫 번째 콜론을 찾아 앞쪽을 아이디, 뒤쪽을 비밀번호로 읽어요. 그래서 비밀번호에는 콜론이 있어도 되지만 아이디에는 쓸 수 없어요.
api:a:b를 풀면 아이디는 api, 비밀번호는 a:b예요. 만약 아이디가 a:b이고 비밀번호가 c인 계정을 만들려고 a:b:c로 보내면 서버는 아이디 a, 비밀번호 b:c로 읽어서 로그인에 실패해요. 이메일 형식 아이디(user@example.com)는 콜론이 없으니 문제없어요.
한글·특수문자 비밀번호는 안전한가요
규격은 문자셋을 UTF-8로 쓰라고 권하고, 서버가 WWW-Authenticate: Basic realm="x", charset="UTF-8"처럼 알려 줄 수 있게 해 뒀어요. 그런데 예전 시스템은 ISO-8859-1 등으로 읽는 경우가 있어서, UTF-8로 보낸 한글이 서버에서 다른 글자로 해석돼 로그인이 안 될 수 있어요. 이런 이유로 API 용도라면 영문·숫자로 된 키나 토큰을 쓰는 쪽이 문제가 적어요.
특수문자는 Base64 단계에서는 문제없어요. 다만 셸에서 curl -u 'admin:p@ss!word'처럼 쓸 땐 !나 $ 같은 기호를 셸이 먼저 해석하지 않게 작은따옴표로 감싸야 해요. 이건 Basic 인증이 아니라 셸의 규칙이에요.
Base64는 암호화가 아니에요
YWRtaW46c2VjcmV0를 Base64 디코더에 넣으면 admin:secret이 그대로 나와요. 열쇠 없이 누구나 되돌릴 수 있다는 뜻이에요. 그래서 Basic 인증에는 몇 가지 약속이 따라와요.
- HTTPS에서만 써요. HTTP로 보내면 중간에서 헤더를 읽는 순간 비밀번호가 노출돼요.
- 로그에 헤더를 남기지 않아요. 접근 로그나 오류 보고 도구가
Authorization헤더를 그대로 저장하지 않는지 확인하세요. - 화면 공유·스크린샷 주의. 헤더 칸이 보이는 Postman 화면을 캡처해 올리면 계정이 공개된 것과 같아요.
- URL 안에 넣지 않아요.
https://아이디:비밀번호@서버/형태는 주소가 기록·공유되기 쉽고, URL 표준 문서도 비밀번호를 주소에 넣는 걸 권하지 않아요.
더 안전한 방식이 필요하면 만료 시간이 있는 토큰 방식을 검토하세요. 토큰 구조는 JWT 디코더로 열어 볼 수 있지만, 이 역시 서명이 있을 뿐 안의 내용은 읽을 수 있어요.
401이 나올 때 확인 순서
Basic뒤에 공백이 한 칸 있나요.BasicYWRt…처럼 붙으면 서버가 인증 방식을 못 알아봐요. 반대로 공백이 두 칸이어도 거부하는 서버가 있어요.- 콜론이 아이디와 비밀번호 사이에 있나요. Base64로 만들기 전 문자열이
admin secret이나admin;secret이면 안 돼요. Basic 인증 헤더 만들기·풀기의 '풀기'로 값을 되돌려 보면 한눈에 보여요(테스트 값만 붙여넣으세요). - 줄바꿈·공백이 섞이지 않았나요.
echo에-n을 빼면YWRtaW46c2VjcmV0Cg==가 돼요. 직접 만든 헤더가YWRtaW46c2VjcmV0와 다르다면 이 경우예요. - 인증 방식이 Basic이 맞나요. 서버가
Bearer토큰을 기대하면 Base64로 감싸지 않고 토큰을 그대로Authorization: Bearer …에 넣어야 해요. 응답의WWW-Authenticate헤더가 어떤 방식을 요구하는지 알려 줘요. - 계정 자체가 맞나요. 비밀번호 만료·계정 잠금·IP 제한은 헤더가 정상이어도 401이나 403을 만들어요. 두 상태 코드의 차이는 HTTP 상태 코드 사전에서 확인하세요.
참고로 401은 "인증 정보가 없거나 틀림", 403은 "누구인지는 알지만 권한이 없음"에 가까워요. 헤더를 아무리 고쳐도 403이면 서버 쪽 권한 설정을 봐야 해요.
언어별로 헤더 붙이는 방법
직접 Base64를 만들기보다 라이브러리의 옵션을 쓰면 줄바꿈 실수가 줄어요.
| 환경 | 방법 |
|---|---|
| curl | curl -u 아이디:비밀번호 URL |
| JavaScript(fetch) | headers: { Authorization: 'Basic ' + btoa('admin:secret') } — 한글은 btoa가 바로 못 받으니 UTF-8 바이트 변환이 필요해요 |
| Python(requests) | requests.get(url, auth=('admin', 'secret')) |
| Postman·Insomnia | Authorization 탭에서 Basic Auth를 고르면 자동으로 헤더 생성 |
fetch의 btoa는 영문·숫자 기준 문자열만 안전해요. btoa('홍길동')처럼 한글을 넣으면 오류가 나는데, 이때는 TextEncoder로 바이트를 만든 뒤 인코딩해야 해요. 헤더 만들기·풀기 도구는 이 UTF-8 처리를 이미 해 둬서 한글 값도 그대로 시험해 볼 수 있어요.
자주 묻는 질문
Basic 헤더 값은 매 요청마다 새로 만들어야 하나요?
아니요. 아이디와 비밀번호가 같으면 값도 항상 같아요. 한 번 만든 값을 환경 변수나 비밀 관리 도구에 두고 쓰세요. 코드에 직접 박아 두면 저장소에 비밀번호가 남아요.
비밀번호가 바뀌면 헤더도 바뀌나요?
네, 비밀번호가 한 글자만 달라도 Base64 전체가 달라져요. 로그인이 갑자기 안 될 때는 이전 값이 설정 파일에 남아 있는지 확인하세요.
개발자 도구 Network 탭에서 헤더를 볼 수 있나요?
볼 수 있어요. 그래서 화면 공유나 캡처 전에 Authorization 줄을 가리는 습관이 필요해요. 이 도구의 '풀기'로 확인하더라도 운영 계정은 붙여넣지 마세요.
아이디나 비밀번호 앞뒤 공백도 포함되나요?
네, 공백도 글자로 함께 인코딩돼요. 복사하면서 끝에 공백이 따라왔다면 서버에는 다른 비밀번호로 전달돼요. 값을 붙여넣은 뒤 앞뒤 공백을 한 번 지워 보세요.
정리
Basic 헤더는 Basic + Base64(아이디:비밀번호)로 끝나는 단순한 방식이지만, 단순한 만큼 공백 한 칸·콜론·줄바꿈 같은 사소한 차이로 401이 나요. 의심스러울 때는 헤더를 풀어서 아이디와 비밀번호가 의도대로 나뉘는지 먼저 보세요. 보안 측면에서는 HTTPS와 로그 관리가 전부이고, 장기적으로는 만료되는 토큰 방식이 더 안전해요.
헤더 확인은 Basic 인증 헤더 만들기·풀기, 일반 문자열 인코딩은 Base64 인코더·디코더에서 해 보세요. 규격 원문은 RFC 7617과 MDN HTTP 인증 문서에 있어요.