5분 만에 붙이기

서비스 등록부터 첫 로그인 성공까지 8단계로 안내합니다. 처음이라면 여기서 시작하세요.

놀아 계정 로그인을 붙이는 전체 과정입니다. 위에서부터 순서대로 따라오시면 됩니다. 막히는 곳이 있으면 에러 코드 사전을 먼저 보세요.

먼저 알아둘 것 — PKCE는 선택이 아니라 필수입니다. 놀아 계정은 code_challenge 없는 인증 요청을 거부합니다(pkce_required). 방식은 S256만 받습니다. 아래 STEP 5가 그 준비입니다.

STEP 1

서비스 등록

마이페이지 ▸ 서비스 등록에서 서비스 이름과 서비스 주소를 입력합니다. 서비스 주소는 실제로 운영 중인 도메인이어야 합니다.

STEP 2

도메인 소유 확인

둘 중 하나를 선택합니다.

방식	해야 할 일
HTML 파일	마이페이지에서 인증 파일을 내려받아 `https://내도메인/nolaa-member-verification.html` 위치에 그대로 올립니다.
DNS TXT	`_nolaa-member-verification.내도메인` 에 발급된 토큰 값을 TXT 레코드로 등록합니다.

DNS 방식은 전파에 시간이 걸립니다. 바로 안 되면 몇 분 뒤 다시 «인증하기»를 누르세요.

STEP 3

콜백 주소 등록

로그인이 끝난 뒤 사용자가 돌아올 주소입니다. 예: https://내도메인/oauth/callback

콜백 주소는 서비스 주소와 같은 호스트여야 하고, 서비스 주소의 하위 경로여야 합니다. 그리고 인증 요청에 넣는 redirect_uri는 여기 등록한 값과 문자 하나까지 정확히 같아야 합니다. 끝의 슬래시 하나만 달라도 invalid_redirect_uri로 거부됩니다.

STEP 4

client_id · client_secret 확인

도메인 인증과 콜백 등록이 모두 끝나면 마이페이지 서비스 카드에 두 값이 나타납니다.

client_secret은 서버에서만 쓰세요. 브라우저로 내려가는 코드(프론트엔드 JS, 모바일 앱 번들)에 넣으면 누구나 꺼내 볼 수 있습니다. 토큰 교환은 반드시 서버에서 하세요.

재발급하면 이전 시크릿은 즉시 무효가 됩니다. 마이페이지에서 «재발급»을 누르면 새 시크릿이 딱 한 번만 화면에 표시되고, 그 순간부터 이전 시크릿으로는 토큰 요청이 invalid_client로 거부됩니다. 서비스가 이미 운영 중이라면 재발급 전에 서버 설정부터 새 값으로 바꿀 준비를 마치세요.

STEP 5

PKCE 값 만들기

사용자를 보내기 전에 서버에서 code_verifier를 만들고 세션에 저장합니다. code_challenge는 그것의 SHA-256 해시를 base64url로 인코딩한 값입니다.

// PHP
$verifier  = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$state     = bin2hex(random_bytes(16));
$_SESSION['nolaa_verifier'] = $verifier;
$_SESSION['nolaa_state']    = $state;

STEP 6

로그인 버튼 붙이기

버튼 코드와 아이콘은 로그인 버튼 만들기에서 복사할 수 있습니다. 버튼의 링크 주소는 아래 형식입니다.

https://account.nola.kr/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=profile.basic%20profile.avatar
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

state도 필수입니다. 빠지면 invalid_request로 거부됩니다.

STEP 7

콜백에서 코드를 토큰으로 바꾸기

사용자가 동의하면 콜백 주소로 code와 state가 붙어 돌아옵니다. 먼저 state가 저장해 둔 값과 같은지 확인한 다음 토큰을 교환하세요.

curl -X POST https://account.nola.kr/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=RECEIVED_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=SAVED_VERIFIER"

인증 코드는 10분 동안 유효하고 한 번만 쓸 수 있습니다.

STEP 8

사용자 정보 받기

curl https://account.nola.kr/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

돌아오는 값과 각 스코프가 무엇을 주는지는 스코프 레퍼런스에 정리돼 있습니다.

sub는 서비스마다 다른 값입니다(pairwise). 같은 사용자라도 다른 서비스에서는 다른 sub가 나갑니다. 사용자를 식별하는 키로는 sub를 쓰되, 다른 서비스와 대조할 수 있는 값으로 착각하지 마세요.

다음으로

OAuth 2.0 연동 가이드 — 전체 흐름과 토큰 갱신
보안 체크리스트 — 배포 전 확인
에러 코드 사전 — 막혔을 때