사내 범용 인증 API 사용 가이드 (v1.5)

Works 메신저는 사용자 본인 외 사용이 불가능하다는 전제를 기반으로 한 2단계 인증(MFA) 서버를 구축했습니다. bot 알림 연동을 제외한 모든 기능은 IT Infra 팀에서 개발하였으며, 사내 시스템에 API로 쉽게 연동이 가능하도록 하였습니다.

---

1. 인증 연동 방식 선택

서비스의 요구사항에 따라 아래 두 가지 방식 중 하나를 선택하여 인증을 연동할 수 있습니다.

• 방법 1: 통합 인증 페이지 연동 (권장)
  • 가장 간단하고 빠른 방법입니다. 로그인 UI나 인증 절차를 직접 구현할 필요 없이, 사내 서버에서 제공되는 중앙 로그인 페이지로 사용자를 보내기만 하면 됩니다.
• 방법 2: 클라이언트 직접 구현
  • 내부 인증 서버를 거치지만 서비스에 맞는 커스텀 로그인 UI가 필요하거나, 인증 과정을 더 세밀하게 제어하고 싶을 때 사용합니다. 직접 UI와 인증 요청/상태 확인 로직을 구현해야 합니다.

---

2. 엔드포인트 정보

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

엔드포인트	HTTP 메서드	설명	API 키
/api/request-auth	POST	새로운 인증 요청 시작 (직접 구현 시)	필요
/api/auth/status/<request_id>	GET	인증 요청 상태 조회 (직접 구현 시)	불필요
/signon/universal_login.php	GET	통합 인증 페이지 (통합 인증 시)	불필요
/signon/token_exchange.php	POST	임시 코드를 사용자 정보로 교환 (통합 인증 시)	불필요
/api/logs	GET	(관리자용) 인증 로그 조회	필요

3. API 키 인증

API 키가 필요한 엔드포인트는 HTTP 요청 헤더에 X-Api-Key: [API Key] 를 포함하여 전송해야 합니다.

---

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

4.1. 방법 1: 통합 인증 페이지 연동 (권장)

가장 간단한 연동 방식입니다. 클라이언트는 사용자를 통합 로그인 페이지로 보내고, 인증이 완료된 후 콜백으로 넘어온 임시 코드를 처리하기만 하면 됩니다.

Step 1: 사용자를 통합 인증 페이지로 리다이렉트

클라이언트 서비스에서 로그인 버튼 클릭 시, 아래와 같이 파라미터를 구성하여 universal_login.php로 이동시킵니다.

https://sap.mdvplab.com:1443/signon/universal_login.php
  ?client_id=[클라이언트 ID]
  &redirect_uri=[등록된 콜백 URL]
  &state=[CSRF 방지용 임의 문자열]

• client_id: IT Infra 팀에서 발급한 클라이언트의 고유 ID
• redirect_uri: 인증 후 돌아올 클라이언트의 URL (사전에 등록된 값과 일치해야 함)
• state: 요청과 콜백이 동일한 세션에서 발생했는지 확인하기 위한 값 (권장)

Step 2: 인증 콜백 처리

사용자가 인증을 성공적으로 마치면, 통합 인증 페이지는 클라이언트의 redirect_uri로 아래와 같이 임시 코드를 포함하여 리다이렉트합니다.

https://your-service.com/callback?code=[임시 인증 코드]&state=[처음 보냈던 state 값]

Step 3: 코드를 사용자 정보로 교환

클라이언트의 **백엔드 서버**는 받은 code를 token_exchange.php API로 보내 실제 사용자 정보를 받아옵니다.

• URL: https://sap.mdvplab.com:1443/signon/token_exchange.php
• 메서드: POST
• 요청 본문 (JSON):

  {
    "client_id": "[클라이언트 ID]",
    "code": "[콜백으로 받은 임시 인증 코드]"
  }

• 성공 응답 (JSON):

  { "email": "user.name@thundersoft.com" }

이메일을 성공적으로 받으면, 클라이언트는 자체 로그인 세션을 생성하고 서비스를 제공합니다. 이 때, 해당 이메일이 서비스에 접근할 권한이 있는지 최종 확인하는 로직을 반드시 포함해야 합니다.

4.2. 방법 2: 클라이언트 직접 구현

로그인 UI/UX를 직접 디자인하고 싶을 때 사용하는 방식입니다. 인증 과정의 모든 단계를 직접 구현해야 합니다.

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

클라이언트 백엔드에서 /api/request-auth로 POST 요청을 보내 인증을 시작하고, 응답으로 받은 request_id를 프론트엔드로 전달합니다.

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

프론트엔드(JavaScript)는 request_id를 이용해 /api/auth/status/[request_id]를 주기적으로(3~5초 간격) 호출하여 상태를 확인합니다.

Step 3: 인증 성공 후 처리

상태가 'approved'로 변경되면, 응답에 포함된 사용자 정보를 바탕으로 클라이언트가 자체적으로 로그인 세션을 생성하고 페이지를 이동시키는 등 후속 작업을 처리합니다.

참고: 이 방식의 더 자세한 구현 예시는 auth_public_old.html (기존 버전 가이드)를 참고하여 주시기 바랍니다.

---

5. 관리자 페이지

인증 시스템의 모든 요청 기록은 관리자 페이지에서 확인할 수 있습니다. 접근 시 관리자 인증이 필요합니다.

인증 로그 확인 페이지로 이동