본문으로 건너뛰기

Key Authentication (Key Auth)

개요​

Key Authentication (key-auth) 정책은 API 소비자가 요청 헤더에 유효한 API Key을 포함하도록 요구함으로써 API 보안을 강화합니다. 이 메커니즘은 승인된 사용자나 애플리케이션만 API에 접근할 수 있도록 보장합니다.

키 인증 작동 방식​

  • API 소비자는 요청 헤더에 valid API Key를 제공해야 합니다.
  • API 게이트웨이는 요청을 처리하기 전에 API 키를 검증합니다.
  • API 키가 missing이거나 invalid인 경우, 요청은 인증 오류와 함께 거부됩니다.

키 인증을 사용할 때​

  • API 접근을 authorized clients로 제한하기 위해.
  • API consumer identification 메커니즘이 필요할 때.
  • combining multiple authentication methods (예: key-auth + JWT)일 때.

Note: key-auth와 JWT authentication이 모두 활성화된 경우, both 인증 방법이 성공적인 요청을 위해 전달되어야 합니다.

구성 세부정보​

API 키 생성​

Key Authentication 정책을 적용하기 전에 API 키를 생성해야 합니다. 다음 단계를 따르세요:

Step 1: Open the API Key Management Page
  • APIM 콘솔의 APIM Management 메뉴로 이동합니다.
  • API 키를 생성할 프로젝트를 선택합니다.
Step 2: Generate a New API Key
  • Create API Key 버튼을 클릭합니다.
  • API 키에 대한 description을 입력합니다 (예: "모바일 앱 접근을 위한 키").
  • 시스템이 automatically generate a unique API Key합니다.

Step 3: Check and view the API Key stored in management screen:
  • 생성된 후, API 키는 API 키 관리 화면에 표시됩니다.
  • 사용자는 API 키를 찾아 다시 복사할 수 있습니다.

구성 필드​

Key Authentication 정책에는 다음 설정이 포함됩니다:

Field NameDescriptionData Input
헤더 이름요청에 API 키가 포함되어야 하는 HTTP header입니다. 기본 헤더 이름은 x-apim-key입니다. Kubernetes 배포 'apim-dff'에서 환경 변수를 통해 헤더 이름을 변경할 수 있습니다. 이러한 변수를 수정하면 APIM 콘솔이 재시작되며 잠시 서비스 중단이 발생할 수 있습니다.환경 변수를 통해 구성할 수 있습니다 (K8s 전용).
API 키 검증시스템은 제공된 API 키가 등록되어 있고 유효한지 확인한 후 API 접근을 허용합니다.
참고: API 키는 일반적으로 32자 알phanumeric 문자열입니다.		자동 검증
오류 처리유효한 API 키가 제공되지 않으면 요청이 HTTP 401 Unauthorized 응답으로 거부됩니다.자동 응답

키 인증을 통한 예제 API 호출​

인증된 API 요청을 하려면 요청 헤더에 API Key을 포함하십시오:

GET /api/resource HTTP/1.1
Host: api.example.com
headers: { "x-apim-key": "202cb962ac59075b964b07152d234b70" }


API 키가 유효하면 요청이 성공적으로 처리됩니다. 그렇지 않으면 응답은 다음과 같이 반환됩니다:

{
    "message": "유효하지 않은 인증 자격 증명",
    "status": 401
}