키 인증 설정

Prev Next

Classic/VPC 환경에서 이용 가능합니다 .

신규로 제공되는 암복호화 API는 기존에 네이버 클라우드 플랫폼 계정 정보를 자격 증명으로 사용하던 암복호화 API와 몇 가지 차이점이 있습니다. Key Management Service(이하 KMS) API 2.0으로 제공되는 신규 API는 기존 API 1.0 대비 다음과 같은 차이점을 가지고 있습니다.

항목 KMS API 1.0 KMS API 2.0
Base URL(도메인) https://kms.apigw.ntruss.com https://ocapi.ncloud.com
API 종류 암복호화 API 6종만 제공 (Encrypt, Decrypt, Create Custom Key, Re-Encrypt, Sign, Verify)
  • 암복호화 API 6종 (Encrypt, Decrypt, Create Custom Key, Re-Encrypt, Sign, Verify)
  • 콘솔로 제공되는 키 관리 기능을 모두 제공
    • 인증 방식 네이버 클라우드 플랫폼 계정 정보를 이용한 사용자 인증
  • 토큰 인증 API : 키 인증 토큰
  • 계정 인증 API : NCP 계정 정보를 이용한 사용자 인증
    • 요청 처리 성능 Encrypt API(AES) 기준 시스템 최대 200 TPS: 모든 키가 200TPS 처리 성능을 공유함 Encrypt API(AES) 기준 키별 최대 300 TPS: 모든 키에 대하여 각각 최대 300TPS의 처리 성능을 개별적으로 보장
    가용성 보장 리전 한정 HA: 네이버 클라우드 플랫폼 리전 장애 시 Cipher API에 영향이 있음 크로스 리전 HA: 암복호화 API는 네이버 클라우드 플랫폼 리전 장애에 영향 없이 무중단 동작 보장
    요청 접근 제어 Sub Account 서비스에서 제공하는 부계정 단위의 IP ACL 기능을 이용
  • Sub Account 서비스에서 제공하는 부계정 단위의 IP ACL 기능
  • 토큰 단위로 설정 가능한 IP ACL
    • 참고

    KMS API 1.0은 계속 제공됩니다.

    키 요청 토큰 개요

    KMS API 2.0의 암복호화 API 요청에 사용되는 토큰은 자체적으로 재정의한 JWT (Jason Web Token) 포맷으로 구성됩니다.

    토큰 구조

    액세스 토큰과 리프레시 토큰은 사용자 인증 및 권한 부여에 사용되는 토큰으로, 보안과 효율성을 고려해 각각의 역할이 다릅니다.

    • 액세스 토큰(Access Token)
      액세스 토큰은 클라이언트가 리소스 서버(API 등)에 접근할 때 사용되는 짧은 수명의 토큰입니다. 사용자 또는 서비스가 인증된 후, 이 토큰을 이용해 권한이 부여된 자원에 접근할 수 있습니다. 액세스 토큰은 보안을 높이기 위한 조치로 보통 짧은 시간 동안만(몇 분 ~ 몇 시간) 유효합니다. 만약 토큰이 유출되더라도 유효 기간이 짧아 손해를 최소화할 수 있기 때문입니다.
      하지만, 인증 토큰이 짧은 유효 기간을 가지게 되면 토큰을 새로 발급 받는 번거로운 사용자 인증 절차가 그만큼 많이 수행됩니다. 이를 보완하기 위해 리프레시 토큰이 사용됩니다.

    • 리프레시 토큰(Refresh Token)
      리프레시 토큰은 액세스 토큰의 유효 기간이 만료되었을 때 새로운 액세스 토큰을 발급 받기 위해 사용됩니다. 이것을 통해 사용자는 다시 사용자 인증(예: 로그인)을 하지 않고도 지속적으로 서비스를 이용할 수 있습니다.
      리프레시 토큰은 액세스 토큰보다 훨씬 긴 유효 기간(며칠 ~ 몇 달)을 가집니다. 그러나 일반적으로 권한을 최소화하기 위해 액세스 토큰처럼 리소스에 접근하는 데는 사용할 수 없습니다.

    JWT (Jason Web Token) 방식

    키 단위로 개별 인증 토큰을 효율적으로 사용하기 위하여 KMS API 2.0에서는 토큰을 자체적으로 관리하는 것이 아닌, JWT (Jason Web Token) 방식을 사용합니다. 토큰 예시는 다음과 같습니다.

    항목 토큰
    리프레시 토큰 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1YjEyNjg5MC1jMDgxLTExZWMtYmE2ZS0yNDZlOTY1OTE1OTQiLCJpYXQiOjE3MjkwNTI4NzYsImV4cCI6MTcyOTA5NjA3NiwiMSI6IlJFRlJFU0giLCIyIjoia2V5dGFnX19hNjg3NmM0NzFhOGJlYmM1NmRjMGQ2NjRkM2M2NGQ0NTNlZTE3ODIwNWE0YWJhZDE4NDk2NTFkZTNmYTY0MDVkIiwiMyI6IkVYVCIsIjQiOlszMywzNCw0LDE0LDI1LDIwLDEwLDExLDEyLDEzLDYsNyw4LDksMjEsMjMsMjQsMjIsMjYsMTYsMTgsMTksMTUsMTcsMzEsMzAsMzIsMjgsMjksMjcsMSwyLDAsMzksMzUsMzYsMzcsMzhdfQ.CUJ6ht53Pmp_Zht6EygvLeUZn1Kb0uqEIK04V_nxHD2J9BYbUk0w2Y8DkU6me0p7tma7jNStrH-duHCFVRgvmao3Mw5Wk0ir8msQnNxB1l8HWOm6CqJPg4TOfSvjhDjEN4mtrONz1ggprJnLs_yFOe-3BF0dTEqkR8w1Ux2q1XevuJ7-LC9gngFcK-4WOzzWwqY7lm8CnZh09Y-aKI591Ry8yNkTlKa9JAneZaA_GI7szVlMs2bBwwUr6NyaJo818jY7o3NHH6l54S3-useml31vBKTQ2I-yMZUmNpTgkHZvc-c9LJfSeeJ16LHLpFrC9yczkoSAYHv-RfqUr45Srw
    액세스 토큰 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1YjEyNjg5MC1jMDgxLTExZWMtYmE2ZS0yNDZlOTY1OTE1OTQiLCJpYXQiOjE3MjkwNTI4NzYsImV4cCI6MTcyOTA2MzY3NiwiMSI6IkFDQ0VTUyIsIjIiOiJrZXl0YWdfX2E2ODc2YzQ3MWE4YmViYzU2ZGMwZDY2NGQzYzY0ZDQ1M2VlMTc4MjA1YTRhYmFkMTg0OTY1MWRlM2ZhNjQwNWQiLCIzIjoiRVhUIiwiNCI6WzMzLDM0LDQsMTQsMjUsMjAsMTAsMTEsMTIsMTMsNiw3LDgsOSwyMSwyMywyNCwyMiwyNiwxNiwxOCwxOSwxNSwxNywzMSwzMCwzMiwyOCwyOSwyNywxLDIsMCwzOSwzNSwzNiwzNywzOF19.HYxASPv_yzjRkxfG3VhDMElJowxC-sAccZWe4ecnIL6YC61uIYPerLIL9paWUqEcBEhTDWGHeJJKe2Qo7RBpwGfGgw7h5dE7JX0blJfSDEiFFr1w92EBN4rpnoQMjEVNwW6EpT3_s6GSgTB6XfeJFIK9rXAuzvy83fCrU3lBBo8Yf3Nfh-1c185AQ_xoSro3hcY_PCaanpUQzOMjqEvEl8L6nYgctBjmDXz3HnSkF3_3IUQOTYR67TRCNNgW1lS9N0oaS_gi6xrbTr7aRzMbexsWyxMipQ1cnY_h4E9iyAK8bkFHUeczEbwUC8W9RMxw3mO3HDqZrCID1wAUcZdj3A
    참고

    JWT 타입의 토큰은 https://jwt.io/ 에서 디코딩된 토큰을 확인할 수 있습니다.

    토큰 기반 인증 흐름(예시)

    1. 키 단위로 토큰을 서명하고 발급하기 위해 키 관리자는 토큰 생성자를 설정합니다.
    2. 토큰 생성자가 설정되면, 콘솔 또는 Create Token Set API를 이용하여 토큰 쌍을 발급합니다. 이때에는 사용자 인증이 필요합니다.
    3. 클라이언트는 액세스 토큰을 이용해 키 암복호화 요청을 하고, 해당 토큰의 유효기간이 만료되어 요청이 거부되면, 리프레시 토큰을 이용해 새로운 액세스 토큰을 요청합니다.
    4. 새로운 액세스 토큰이 발급되면 클라이언트는 다시 키 암복호화 요청을 할 수 있습니다. 만약, 리프레시 토큰이 만료되었을 경우에는 다시 토큰 발급 사용자는 다시 사용자 인증을 거쳐야 합니다.

    인증 설정

    토큰 생성자 활성화/비활성화

    토큰 인증 기능을 사용하기 위해서는 먼저 토큰 생성자를 구성해야 합니다. 토큰 생성자를 활성화하고 비활성화 하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼 콘솔에서 i_menu > Services > Security > Key Management Service > Key 메뉴를 차례대로 클릭해 주십시오.
    2. 키를 선택하고 인증 설정 탭으로 이동한 후, 토큰 생성자 활성화을 클릭하여 토큰 생성자를 구성합니다.
    3. 토큰 생성자가 초기화되면 토큰 생성자의 ID가 부여되고, 이제부터 토큰을 발급할 수 있습니다.
      kms-token_01_ko
    4. 토큰 생성자 비활성화를 클릭하면 토큰 생성자가 폐기되고, 더이상 토큰 인증을 처리하지 않습니다.

    토큰 생성자 교체

    토큰 인증 기능 사용을 유지하면서 토큰 생성자만 교체할 수도 있습니다. 토큰 생성자를 교체하는 방법은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼 콘솔에서 i_menu > Services > Security > Key Management Service > Key 메뉴를 차례대로 클릭해 주십시오.
    2. 키를 선택하고 인증 설정 탭으로 이동한 후, 토큰 생성자 ID를 확인합니다.
    3. 토큰 생성자 옆의 교체 버튼을 클릭하여 토큰 생성자를 교체합니다.
    주의

    토큰 생성자가 폐기 또는 교체되면, 해당 토큰 생성자를 통해 발급된 모든 토큰은 자동으로 만료되며, 이 작업은 되돌릴 수 없습니다. 따라서 토큰이 이미 발급되어 사용 중인 경우에는 운영 영향 범위를 충분히 검토한 후 반드시 필요한 상황에서만 토큰 생성자를 폐기 또는 교체하시기 바랍니다.

    토큰 생성

    토큰 생성자가 설정되어 있는 경우, 토큰을 발급할 수 있습니다.

    1. 네이버 클라우드 플랫폼 콘솔에서 i_menu > Services > Security > Key Management Service > Key 메뉴를 차례대로 클릭해 주십시오.
    2. 키를 선택하고 인증 설정 탭으로 이동한 후, 토큰 생성자 ID를 확인해 주십시오.
    3. 토큰 생성 버튼을 클릭하고, 유효 기간을 입력해 십시오오.
      • 리프레시 토큰 TTL: 시간 단위로 입력하며, 최소 1시간부터 최대 17,520시간(730일)까지 설정이 가능합니다. 입력하지 않는 경우 기본 2,160시간(90일)로 설정됩니다.
      • 액세스 토큰 TTL: 시간 단위로 입력하며, 최소 1시간부터 최대 17,520시간(730일)까지 설정이 가능합니다. 입력하지 않는 경우 기본 72시간(3일)로 설정됩니다.
    4. 확인을 눌러 발급된 토큰을 확인해 시오. 토큰 발급 팝업이 닫히면 발급된 토큰은 유실되니 유의해 주시기 바랍니다.
      kms-token_02_ko

    토큰

    IP ACL 설정

    인가되지 않은 클라이언트로부터의 토큰 오용을 방지하기 위해 토큰 사용이 허가된 요청자의 IP를 지정할 수 있습니다.

    1. 네이버 클라우드 플랫폼 콘솔에서 i_menu > Services > Security > Key Management Service > Key 메뉴를 차례대로 클릭해 주십시오.
    2. 키를 선택하고 인증 설정 탭으로 이동한 후, IP ACL 버튼을 활성화해 주십시오. IP ACL이 활성화된 이후부터 발급되는 토큰은 요청 IP 주소 검증이 수행됩니다.
      주의
      • IP ACL이 활성화 되면, 기본적으로 'All Deny'로 동작합니다. 따라서, IP ACL 기능을 활성화하면 반드시 허용 IP 주소를 등록해야 토큰을 올바르게 사용할 수 있습니다.
      • 또한, IP ACL이 활성화 되기 이전에 발급된 토큰들 역시 요청 IP 주소 검증을 수행합니다. 만약, IP ACL 기능 활성화 이전에 발급된 토큰이 허용된 IP 주소로부터 요청되지 않는 경우에는 검증이 실패하므로 주의해 주십시오.
    3. IP 주소를 입력하고 추가 버튼을 클릭하여 허용 리스트에 등록해 주십시오. IP 주소는 등록 즉시 허용됩니다.
    4. 삭제하고자 하는 IP 주소가 있다면 해당 항목 옆의 삭제 버튼을 클릭하여 허용 리스트에서 제거해 주십시오. IP 주소는 삭제하는 즉시 거부됩니다.
      kms-token_03_ko