활용방법

OpenAPI API 인증

ScienceON API Gateway에서는 인증토큰(Access Token)을 발급받아야 API를 활용할 수 있습니다.
발급된 인증토큰을 이용해 데이터를 요청하고 이용할 수 있으며, 토큰 사용기간이 만료시에는 재발급을 받아 사용하실 수 있습니다.

인증키 및 토큰 안내

인증키(API Key)란?
인증키(API Key)는 ScienceON API에 접근하기 위한 기본적인 인증 수단입니다. API를 사용하여 데이터를 요청할 때, 이 인증키를 통해 ScienceON 서버는 허가된 사용자인지 확인합니다.
  • 주요 역할 : ScienceON API에 접근할 수 있는 기본 자격을 증명
  • 사용 예시 : 일반적인 데이터 조회, 비민감한 정보 접근
인증키는 애플리케이션이 ScienceON API에 연결될 수 있도록 도와주는 첫 번째 단계입니다.
토큰(Token)이란?
토큰(Token)은 특정 작업을 수행하거나 민감한 데이터에 접근할 때 필요한 추가적인 보안 수단입니다. 토큰은 로그인이나 특정 인증 절차를 거친 후 발급되며(자동으로 발급), 일정 시간이 지나면 만료됩니다(재로그인 시 자동 재발급). ScienceON API에서는 토큰을 두 가지로 구분하여 사용합니다
  • Access Token : 사용자가 로그인한 후 발급받는 단기 유효 토큰으로, API 요청 시마다 함께 전송됩니다. Access Token은 특정 리소스나 기능에 접근할 수 있도록 허가합니다. 그러나 이 토큰은 보통 짧은 유효 기간을 가지며, 만료되면 더 이상 사용할 수 없습니다.
    • 주요 역할 : 인증된 사용자의 API 요청을 처리
    • 사용 예시 : 사용자 개인화 서비스, 민감한 데이터 접근
  • Refresh Token : Access Token이 만료되었을 때, 새로운 Access Token을 발급받기 위해 사용되는 장기 유효 토큰입니다. 사용자가 다시 로그인할 필요 없이, 이 Refresh Token을 통해 새로운 Access Token을 발급받아 API 사용을 지속할 수 있습니다.
    • 주요 역할 : Access Token이 만료되었을 때 새로운 토큰 발급
    • 사용 예시 : 장기 세션 유지, 재인증 없이 API 사용 지속

토큰발급 전체 흐름도

1. 인증(토큰 발급)

1.Token 발급 요청URL(Request URL) 형식
https://apigateway.kisti.re.kr/tokenrequest.do?accounts=[신청기관식별정보의 암호화 스트링]&client_id=[클라이언트 ID]

  • Token 발급 요청 예시

    https://apigateway.kisti.re.kr/tokenrequest.do?accounts=
    URIEncoding(
        AES256(
            {
                mac_address : B4-2E-99-AD-48-7D,
                datetime: 20210430011540
            }
        )
    )
    &client_id=2300BD0DD3DCC8D01E59AAEBD2BDFD398147E59B40C1F32E548FDC51D7C99708
     https://apigateway.kisti.re.kr/tokenrequest.do?accounts=m05G3Thk9yD7%2BTLsb2VyS5SCg5JLVDB6%2FpggbVlkROEw1DkX1MdlevFM2LZzmuAeWrMKxzrpTg2Cuc2tpbILc8bBKKdXxUJhK09uM3vHCls%3D&client_id=2300BD0DD3DCC8D01E59AAEBD2BDFD398147E59B40C1F32E548FDC51D7C99708

  • Parameter accounts 값 생성 방법

    1) Client(이용기관)에서 이용신청 시 제출한 맥주소와 현재일시 값을 json data로 변환
    2) JSON data를 발급받은 인증키(32자리 영문/숫자로 구성)를 암호화키로 이용하여 AES256 암호화 및 URIEncoding 실행
    3) Token 발급 요청 URL 생성 및 API Gateway 서버로 전달함
2.신청기관 정보 확인
  • 신청기관 정보 확인 방법
1) API Gateway는 client_id 값으로 신청기관 식별
2) 신청기관에 발급된 인증키를 암호화키로 이용하여 parameter accounts의 값을 AES256 복호화 실행
3) JSON data에서 mac_address 값을 추출 후 신청기관에서 제출한 맥주소 값과 비교
4) 모든 정보가 일치하면 정상적으로 token 값을 발급
3.Access Token, Refresh Token 생성
  • 신청기관 정상적으로 인증완료 후 64Byte의 Access Token, Refresh Token 발행
  • Access Token : 데이터 요청시 사용, 사용기한 2시간
  • Refresh Token : Access Token 만료시 신규 발급용으로 사용, 사용기한 2주
4.Token 발급 (Access Token, Refresh Token)
  • Client(이용기관)는 발급받은 Access Token, Refresh Token 정보 관리 필요

  • 발급 데이터 예제 (JSON Data 형식)

    {
        "access_token": "181e66514b67567673acbd0c3595baa45a1b977f667ee7e13b01c7115764b40d",
        "access_token_expire": "2020-11-20 17:14:53.213",
        "refresh_token": "6aace89eba340af8235fa422f6fe5704d40847fe3121a83c53d2d8b3fc446bb4",
        "refresh_token_expire": "2020-12-03 13:48:50.38",
        "client_id": "2300BD0DD3DCC8D01E59AAEBD2BDFD398147E59B40C1F32E548FDC51D7C99708",
        "issued_at": "2020-11-20 15:14:53.000"
    }
    • access_token : access_token 값
    • access_token_expire : access_token 만료일시 (발행일시로부터 2시간)
    • refresh_token : refresh_token 값
    • refresh_token_expire : refresh_token 만료일시 (발행일시로부터 2주)
    • client_id : token 요청한 신청기관 식별ID
    • issued_at : token 발행일시

2. 데이터 요청

5.데이터 요청(Access Token 이용)

  • 데이터 요청 URL(Request URL) 형식

    https://apigateway.kisti.re.kr/openapicall.do?client_id=[클라이언트 ID]&token=[ACCESS_TOKEN 값]&version=1.0&action=[API action 구분]&target=[콘텐츠 약어]&searchQuery=[{"검색필드항목":"검색어"}]&sortField=[정렬 필드]&curPage=[현재 페이지번호]&rowCount=[디스플레이 건수]&session_id=[사용자 세션 ID]
6.Access Token 검증

  • Access Token 검증방법

    1) Client에서 요청 받은 클라이언트 ID, Access Token 값과 API Gateway DB에 저장된 Access Token을 비교하고 만료일 체크
    2) Access Token 값이 일치하고 만료일 이전이면, API Gateway 서버에서 요청 받은 API 기능 수행
7.응답(요청데이터 XML Return)
  • 정상적으로 데이터 검색이 완료되면 XML 형태로 Client에게 응답
  • 오류 발생 시, 오류코드 및 메시지 응답(오류코드/메시지 메뉴 참조)

3. 토큰 재발급

10. Access Token 만료 확인

  • Access Token 검증방법

    1) Client에서 요청 받은 클라이언트ID, Access Token 값과 API Gateway DB에 저장된 Access Token을 비교하고 만료일 체크
    2) 데이터 요청일시가 Access Token의 만료일시를 넘어가면 Client에게 Access Token 만료 에러메시지 XML 리턴
11. 응답(Access Token 기한 만료)

  • 예시(XML Data 형식)

    <?xml version="1.0" encoding="UTF-8"?>
    <MetaData>
    <resultSummary>
        <statusCode>401</statusCode>
    </resultSummary>
    <errorDetail>
        <statusMessage>Unauthorized</statusCode>
        <errorCode>E4103</errorCode>
        <errorMessage>Access Token 값 오류</errorMessage>
    </errorDetail>
    </MetaData>
12. Access Token 발급요청(Refresh Token 이용)

  • Token 발급 요청 URL(Request URL) 형식

    https://apigateway.kisti.re.kr/tokenrequest.do?refresh_token=[발급받은 Refresh Token]&client_id=[클라이언트 ID]

  • Token 발급 요청 URL 예시

    https://apigateway.kisti.re.kr/tokenrequest.do?refresh_token=6aace89eba340af8235fa422f6fe5704d40847fe3121a83c53d2d8b3fc446bb4&client_id=2300BD0DD3DCC8D01E59AAEBD2BDFD398147E59B40C1F32E548FDC51D7C99708
13. Refresh Token 확인 후 새로운 Access Token 발급
1) Client에서 요청 받은 클라이언트 ID, Access Token 값과 API Gateway DB에 저장된 Access Token을 비교하고 만료일 체크
2) Refresh Token값이 일치하고 만료일 이전이면, 신규 Access Token 발급
3) 신규 Access Token 발급정보 및 만료일시 정보를 API Gateway DB(신청기관 발급 토큰 정보)에 저장
4) Client(이용기관)는 반드시 발급받은 Access Token 정보 관리 필요
14. 응답(신규 Access Token)

  • 예시(JSON Data 형식)

    {
        "access_token": "4bb216aa08d537746384f2a0bee69c4167f6250ccab7086d1b64375390add2c7",
        "access_token_expire": "2020-11-25 23:31:32.168",
        "refresh_token": "6aace89eba340af8235fa422f6fe5704d40847fe3121a83c53d2d8b3fc446bb4",
        "refresh_token_expire": "2020-12-03 13:48:50.38",
        "client_id": "2300BD0DD3DCC8D01E59AAEBD2BDFD398147E59B40C1F32E548FDC51D7C99708",
        "issued_at": "2020-11-25 21:31:32.000“
    }