사내 Works 본인인증 v2 연동 가이드

최종 수정: 2026-05-14  ·  IT Infra팀

signon_v2는 기존 v1.5 인증 서비스를 개선한 중앙 인증 서비스입니다. 대상 사이트에 Works 본인인증 버튼을 붙이는 역할은 동일하지만, 표준 OAuth 2.0 방식을 채택해 구조가 더 명확하고 보안이 강화됐습니다.

대상 사이트는 인증 화면과 Works 메시지 발송을 직접 만들지 않습니다. 사이트 담당자는 등록 정보를 IT팀에 요청하고, IT팀이 발급한 값을 사용해 버튼과 callback만 구현하면 됩니다.

v1.5 대비 개선 사항

• 표준 OAuth 2.0 방식 채택 — Authorization Code Flow 기반으로 구조가 명확하고 다양한 언어·프레임워크에서 연동이 쉽습니다.
• 보안 강화 — client_secret 기반 서버 간 인증, state 파라미터로 CSRF 방지, 인증 코드 2분 유효·1회 사용 제한이 적용됩니다.
• 사이트별 접근 제어 — allowed_users로 사이트마다 허용 사용자를 지정할 수 있습니다.
• 요청 횟수 제한 — 단시간 과도한 인증 요청을 자동 차단합니다.

1. 역할별 준비 사항

1.1. 사이트 담당자가 IT팀에 요청할 정보

본인인증 버튼을 붙일 사이트 담당자는 아래 정보를 IT Infra 팀에 전달합니다.

1.2. IT팀이 생성해서 사이트 담당자에게 전달할 정보

IT팀은 signon_v2에 사이트를 등록한 뒤 아래 값을 사이트 담당자에게 전달합니다.

1.3. IT팀 내부 등록 예시

아래는 IT팀이 signon_v2 운영 서버의 clients.json에 등록하는 값의 예시입니다. 사이트 담당자는 이 파일을 직접 수정하지 않습니다.

{
  "mrtg": {
    "name": "MRTG",
    "client_secret": "replace-with-long-random-secret",
    "redirect_uris": [
      "https://site.example.com/auth/signon/callback"
    ],
    "bot_id": "00000000",
    "allowed_users": ["gildong.hong", "sunhee.kim"],
    "scopes": []
  }
}

2. v2 인증 흐름

1. 사용자가 대상 사이트의 Works 본인인증 버튼을 클릭합니다.
2. 대상 사이트가 사용자를 signon_v2 /authorize로 이동시킵니다.
3. signon_v2가 사용자의 Works 계정을 확인하고, 해당 Works 앱으로 승인 링크가 담긴 인증 메시지를 발송합니다.
4. 사용자가 Works 앱에서 링크를 열어 승인 또는 거부합니다. 5분 안에 응답하지 않으면 자동으로 만료됩니다.
5. signon_v2가 대상 사이트 callback URL로 code(승인) 또는 error(거부/만료)를 전달합니다.
6. 대상 사이트 서버가 /token에 code를 제출해 사용자 정보를 받습니다. code는 2분 안에 1회만 사용 가능합니다.
7. 대상 사이트가 자체 로그인 세션을 만들거나 추가 본인확인을 완료 처리합니다.

3. 엔드포인트 정보

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

4. 대상 사이트 구현 1: 버튼 만들기

사이트 담당자는 IT팀이 전달한 SIGNON_CLIENT_ID, SIGNON_REDIRECT_URI를 사용해 인증 시작 URL을 만듭니다.

4.1. authorize URL 형식

https://sap.mdvplab.com:5010/authorize
  ?client_id=[SIGNON_CLIENT_ID]
  &redirect_uri=[SIGNON_REDIRECT_URI]
  &state=[CSRF 방지용 임의 문자열]
  &scope=[요청할 부가정보, 선택]

• client_id: IT팀이 전달한 SIGNON_CLIENT_ID
• redirect_uri: IT팀이 등록하고 전달한 SIGNON_REDIRECT_URI
• state: 대상 사이트 서버가 매 요청마다 생성하고 세션에 저장하는 임의 문자열
• scope: 부가 정보 요청 범위 (선택). 공백으로 구분. 예: profile, profile sites

4.2. HTML 버튼 예시

<a href="AUTHORIZE_URL">Works 본인인증으로 로그인</a>

4.3. PHP 버튼 생성 예시

<?php
session_start();

$signonBaseUrl = 'https://sap.mdvplab.com:5010';
$clientId      = 'YOUR_CLIENT_ID';    // IT팀이 전달한 값
$redirectUri   = 'YOUR_REDIRECT_URI'; // IT팀에 등록한 callback URL

$state = bin2hex(random_bytes(16));
$_SESSION['signon_state'] = $state;

$loginUrl = $signonBaseUrl . '/authorize?' . http_build_query([
    'client_id'    => $clientId,
    'redirect_uri' => $redirectUri,
    'state'        => $state,
]);
?>
<a href="<?php echo htmlspecialchars($loginUrl); ?>">Works 본인인증으로 로그인</a>

5. 대상 사이트 구현 2: callback 처리

callback URL은 IT팀에 요청한 URL과 정확히 같아야 합니다. 경로, 도메인, 포트, https 여부가 다르면 차단됩니다.

5.1. 성공 callback

https://site.example.com/auth/signon/callback?code=[임시 코드]&state=[처음 보낸 state]

5.2. 실패 callback

https://site.example.com/auth/signon/callback?error=rejected&state=[처음 보낸 state]
https://site.example.com/auth/signon/callback?error=expired&state=[처음 보낸 state]

• rejected: 사용자가 Works 인증을 거부했습니다.
• expired: 5분 안에 인증이 완료되지 않아 요청이 만료되었습니다.

5.3. PHP callback 기본 구조

<?php
session_start();

// signon_v2는 성공(code)과 실패(error) 모두 state를 포함해 돌아옴
// → state 유무로 진입하고, 검증 후 error/code 분기 처리
if (isset($_GET['state'])) {
    if (!isset($_SESSION['signon_state']) || !hash_equals($_SESSION['signon_state'], $_GET['state'])) {
        die('인증 세션이 유효하지 않습니다. <a href="index.php">다시 시도</a>');
    }
    unset($_SESSION['signon_state']);

    if (isset($_GET['error'])) {
        $msg = ['rejected' => '인증이 거부되었습니다.', 'expired' => '인증 시간이 만료되었습니다.'][$_GET['error']] ?? '인증에 실패했습니다.';
        die(htmlspecialchars($msg) . ' <a href="index.php">다시 시도</a>');
    }

    if (isset($_GET['code'])) {
        // 6장: /token으로 code를 교환해 사용자 정보 획득
    }
}

6. 대상 사이트 구현 3: code를 사용자 정보로 교환

callback으로 받은 code는 반드시 대상 사이트 서버에서 /token으로 검증해야 합니다. code는 발급 후 2분간 유효하고 1회만 사용할 수 있습니다.

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

6.1. 요청

POST https://sap.mdvplab.com:5010/token
Content-Type: application/json

{
  "client_id": "mrtg",
  "client_secret": "IT팀이 전달한 SIGNON_CLIENT_SECRET",
  "redirect_uri": "https://site.example.com/auth/signon/callback",
  "code": "CALLBACK_CODE"
}

6.2. 성공 응답 (HTTP 200)

기본 응답 (scope 없음 — 항상 반환):

{
  "active": true,
  "client_id": "mrtg",
  "email": "user@works-domain.com",
  "username": "user",
  "user_id": "75672d66-68c3-4217-17b0-03d5cdfa5106"
}

scope=profile 추가 시:

{
  "active": true,
  "client_id": "mrtg",
  "email": "user@works-domain.com",
  "username": "user",
  "user_id": "75672d66-68c3-4217-17b0-03d5cdfa5106",
  "display_name": "홍길동(Gildong)",
  "department": "IT Infra"
}

대상 사이트는 응답의 email 또는 user_id로 사용자를 식별하고 자체 세션을 생성합니다.

6.3. 오류 응답

/token 요청이 실패하면 HTTP 4xx와 함께 아래 형식의 JSON이 반환됩니다.

{ "error": "오류_코드" }

7. 구현 시 자주 틀리는 부분

8. 운영 보안 체크리스트

• 필수 callback URL은 HTTPS를 사용합니다.
• 필수 SIGNON_CLIENT_SECRET은 서버에서만 보관합니다.
• 필수 state는 매 요청마다 새로 생성하고 callback에서 검증합니다.
• 필수 redirect_uri는 IT팀에 등록한 값과 정확히 일치시킵니다.
• 필수 /token 호출은 브라우저가 아닌 서버에서 수행합니다.
• 권장 인증 성공 후에도 사이트 자체 접근 권한을 별도로 확인합니다.

9. 표준 구현 사례: MRTG

사내 MRTG 모니터링 사이트가 v2 표준 구현 사례입니다. 이 가이드의 모든 예시 코드는 MRTG 구현을 기준으로 작성됐습니다.