사내 범용 인증 API 사용 가이드(old)

1. API 개요

사용자가 서비스에서 로그인을 시도할 때, Works 앱으로 푸시 알림을 보내 본인임을 증명하는 방식의 인증을 제공합니다. 전체적인 흐름은 다음과 같습니다.

1. 인증 요청: 클라이언트 백엔드가 사용자의 이메일로 인증 서버에 인증을 요청합니다.
2. 상태 확인: 클라이언트 프론트엔드(브라우저)는 주기적으로 인증 상태를 확인합니다. (폴링)
3. 사용자 승인: 사용자는 Works 앱으로 수신한 메시지에서 '승인' 또는 '거부'를 선택합니다.
4. 결과 처리: 상태 확인 시 '승인'이 감지되면, 클라이언트는 로그인 처리 등 후속 작업을 진행합니다.

*인증 서비스이므로 암호화 통신과 인증키 사용 등 보안성을 염두에 두고 설계하였습니다.

*이 API는 네이버 공식 API가 아닙니다. 자체 제작이므로 버그나 오류가 있을(많을) 수 있습니다

2. 엔드포인트 정보

인증 서버 기본 URL: https://sap.mdvplab.com:5003

엔드포인트	HTTP 메서드	설명	API 키
/api/request-auth	POST	새로운 본인 인증 요청 시작	필요
/api/auth/status/<request_id>	GET	특정 인증 요청의 현재 상태 조회	불필요
/api/logs	GET	(관리자용) 인증 로그 조회	필요
/verify/<request_id>	GET	(Works 앱 내부용) 인증 확인 웹페이지	불필요
/api/auth/confirm_form	POST	(Works 앱 내부용) 사용자 응답 처리	불필요...

3. API 키 인증

보안이 필요한 엔드포인트는 사내에서 발급된 API 키를 통한 인증이 필요합니다. API 키는 HTTP 요청 헤더에 X-Api-Key 라는 이름으로 포함하여 전송해야 합니다.

4. 클라이언트 통합 가이드

4.1. Step 1: 인증 요청 시작 (서버 to 서버)

사용자가 인증을 시작할 때, 클라이언트의 백엔드 서버에서 인증 서버의 /api/request-auth로 POST 요청을 보냅니다.

요청 명세:

• URL: https://sap.mdvplab.com:5003/api/request-auth
• 메서드: POST
• 헤더: Content-Type: application/json, X-Api-Key: [API Key]
• 요청 본문 (JSON):

  {
    "email": "user.name@thundersoft.com",
    "target_url": "https://your-service.com/callback"
  }

성공 응답 (HTTP 200 OK):

{
  "request_id": "a1b2c3d4-e5f6-...",
  "verify_url": "https://sap.mdvplab.com:5003/verify/a1b2c3d4-e5f6-..."
}

요청이 성공하면, 클라이언트 백엔드는 응답으로 받은 request_id와 email 정보를 프론트엔드(브라우저)로 전달하여 다음 단계를 준비시킵니다.

명령어 (cURL) 예시:

터미널에서 아래와 같이 cURL 명령어를 사용하여 API를 직접 호출하고 테스트해 볼 수 있습니다. -k 옵션은 SSL 인증서 검증을 건너뛰기 위해 사용됩니다.

curl -k -X POST \
  https://sap.mdvplab.com:5003/api/request-auth \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY_HERE" \
  -d '{
    "email": "YOUR_EMAIL_ADDRESS",
    "target_url": "https://sap.mdvplab.com:1443/signon/auth_demo_client.php"
  }'

4.2. Step 2: 인증 상태 확인 (브라우저 to 서버)

브라우저는 백엔드로부터 전달받은 request_id를 사용하여, 주기적으로 인증 서버에 상태를 직접 확인(폴링)합니다.

요청 명세:

• URL: https://sap.mdvplab.com:5003/api/auth/status/[request_id]
• 메서드: GET

상태별 응답 (JSON):

status 값에 따라 다른 정보가 반환됩니다.

• 대기 중: {"status": "pending"}
• 승인됨:

  {
    "status": "approved",
    "email": "user.name@thundersoft.com",
    "target_url": "https://your-service.com/callback",
    "user_id": "Works 사용자 고유 ID",
    "display_name": "사용자 이름(직책)"
  }

• 그 외 상태: {"status": "rejected"}, {"status": "expired"} 등

폴링은 보통 3~5초 간격으로 호출하며, status가 'pending'이 아닌 다른 값으로 바뀌면 중단합니다.

4.3. Step 3: 인증 성공 후 처리

폴링을 통해 status가 'approved'인 것을 확인하면, 인증이 완료된 것입니다. 클라이언트는 이 시점에서 후속 처리를 진행합니다.

클라이언트의 역할:

1. 로그인 처리: 'approved' 응답에 포함된 email, user_id 등의 정보를 바탕으로 서비스의 로그인 세션을 생성합니다.
2. 권한 확인: 로그인된 사용자가 서비스 내에서 특정 권한(예: 관리자)을 가졌는지 추가로 확인할 수 있습니다.
3. 페이지 이동: 로그인 후 사용자를 서비스의 메인 페이지나 대시보드로 이동시킵니다.

---