nice-api-node

NICE API 서비스를 Node.js에서 사용하기 위한 라이브러리 구현체 입니다.
현재 NICE 본인 확인 (통합형, API를 통한 NICE 표준창 호출) 서비스가 구현되어 있습니다.
추후 필요에 따라 다른 서비스도 추가할 예정입니다.
PR은 언제나 환영합니다.

📌 NICE 본인 확인 (통합형, API를 통한 NICE 표준창 호출)

NICE에서 제공된 흐름도를 참고하여 다음 기능이 내부적으로 구현되어 있고

• 인증 기관 토큰 (AccessToken) 발급
• 암호화 토큰 (CryptoToken) 발급
• 대칭키 생성
• 인증 요청 데이터 암호화 (AES128/CBC/PKCS7)
• 인증 결과 데이터 복호화

다음 기능을 외부로 제공합니다.

• 표준창 서비스 호출시 필요한 요청 데이터 생성 ( generateRequestData )
• 본인 인증 결과로 받은 암호화된 데이터 복호화 ( decryptResultData )

📦 설치방법

$ npm install nice-auth-node
or
$ yarn add nice-auth-node

🚀 사용 방법

라이브러리 초기화

// import
const { NiceAuth, NiceAuthError } = require('nice-api-node')

// NICE에서 제공된 clientId, clientSecret, productId로 NiceAuth 인스턴스 생성
const niceAuth = new NiceAuth({
    clientId: '<client id>',
    clientSecret: '<client secret>',
    productId: '<product id>'
})

NICE 표준창을 호출하기 위한 요청데이터 생성

try {
    const requestData = await niceAuth.generateRequestData({
        requestno: '123456789', // 최대 30자
        returnurl: 'http://localhost:3000/test',
        authtype: 'M',
        methodtype: 'post',
        popupyn: 'Y',
        receivedata: JSON.stringify({ foo: 'var' }),
    });
    console.log(requestData);
} catch (e) {
    // 오류 처리
    if (e instanceof NiceAuthError.AccessTokenError) {
        console.log('액세스 토큰 발급 실패!');
    } else if (e instanceof NiceAuthError.CryptoTokenError) {
        console.log('암호화 토큰 발급 실패!');
    } else if (e instanceof NiceAuthError.SymmetricKeyError) {
        console.log('대칭키 생성 실패!');
    } else if (e instanceof NiceAuthError.EncryptDataError) {
        console.log('요청 데이터 암호화 실패!');
    } else if (e instanceof NiceAuthError.IntegrityValueError) {
        console.log('무결성 검증 값 생성 실패!');
    } else {
        console.log('기타 오류')
    }
}

generateRequestData 함수 호출 파라미터

항목	필수	타입	길이	고정값	설명
requestno	Y	String	30		서비스 요청 고유 번호
returnurl	Y	String	250		인증 결과를 받을 URL
authtype	N	String	1		인증수단 고정 (M:휴대폰인증,C:카드본인확인인증,X:인증서인증,U:공동인증서인증,F:금융인증서인증,S:PASS인증서인증)
mobilceco	N	String	1		이통사 우선 선택(S : SKT, K : KT, L : LGU+)
businessno	N	String	10		사업자번호(법인인증인증에 한함)
methodtype	N	String	3~4	post,get	결과 URL 전달시 http method타입
popupyn	N	String	1	Y, N	팝업
receivedata	N	String	-		인증 후 전달받을 데이터 세팅 (요청값 그대로 리턴)

generateRequestData 호출 결과

{
  symmetricKey: 'symmetric key value', // symmetricKey는 노출이 안되도록 서버 어딘가에 저장
  formData: {
    tokenVersionId: 'tokenVersionId value',
    encData: 'encData value',
    integrityValue: 'integrityValue value',
  }
}

generateRequestData의 결과를 사용하여 다음과 같은 형태로 form을 생성하고 submit하여 사용자 본인 인증 시작

<form name="form" id="form" action="https://nice.checkplus.co.kr/CheckPlusSafeModel/service.cb">
  <input type="hidden" id="m" name="m" value="service" />
  <input type="hidden" id="token_version_id" name="token_version_id" value="tokenVersionId" />
  <input type="hidden" id="enc_data" name="enc_data" value="encData" />
  <input type="hidden" id="integrity_value" name="integrity_value" value="integrityValue" />
</form>

사용자가 본인 인증을 완료하면 generateRequestData 호출 시 넘겼던 returnurl로 다음 데이터가 넘어옴

{
  "token_version_id": "value",
  "enc_data": "value",
  "integrity_value": "value"
}

사용자 본인 인증 결과로 받은 암호화된 데이터를 복호화 하기 위해 decryptResultData 호출

try {
    // 서버 어딘가에 저장된 symmetricKey
    const symmetricKey = keyStorage.get('requestNo');

    // 사용자 본인 인증 결과
    const authResultData = {
        token_version_id: 'value',
        enc_data: 'value',
        integrity_value: 'value',
    };

    const decryptedData = niceAuth.decryptResultData({
        symmetricKey: symmetricKey,
        integrityValue: authResultData.integrity_value,
        cipherData: authResultData.enc_data,
    });

    console.log(decryptedData);
} catch (e) {
    if (e instanceof NiceAuthError.DecryptDataError) {
        console.log('데이터 복호화 실패');
    } else {
        console.log('another');
    }
}

인증결과 데이터

항목	필수	타입	길이	설명
resultcode	Y	String	4	결과코드
requestno	Y	String	30	요청 고유 번호(회원사에서 전달보낸 값)
enctime	Y	String	14	암호화 일시(YYYYMMDDHH24MISS)
sitecode	Y	String	16	사이트코드
responseno	Y	String	24	응답고유번호
authtype	Y	String	1	인증수단
name	N	String	100	이름
utf8_name	N	String		UTF8로 URLEncoding된 이름 값
birthdate	N	String	8	생년월일 8자리
gender	N	String	1	성별
nationalinfo	N	String	1	내외국인
mobile_co	N	String	1	이통사 구분(휴대폰 인증 시)
mobile_no	N	String	1	휴대폰 번호(휴대폰 인증 시)
ci	N	String	88	개인 식별 코드(CI)
di	N	String	64	개인 식별 코드(DI)
businessno	N	String	10	사업자번호(법인인증서 인증시)
receivedata	N	String		요청 시 전달 받은 RECEIVEDATA

서비스 키 확인 방법