API 키를 사용하여 인증되지 않은 게스트의 애플리케이션 액세스 허용

애플리케이션에서 Amazon Location Service API를 호출할 때에는 일반적으로 API 호출 권한이 있는 인증된 사용자로서 이 호출을 수행합니다. 그러나 경우에 따라 애플리케이션의 모든 사용자를 인증하고 싶지는 않습니다. 예를 들어, 웹 사이트를 사용하는 모든 사람이 로그인 여부에 관계없이 비즈니스 위치를 보여주는 웹 애플리케이션을 사용할 수 있도록 하고 싶을 수 있습니다. 이 경우 한 가지 대안은 API 키를 사용하여 API를 호출하는 것입니다.

API 키는 사용자의 AWS 계정 특정 Amazon Location Service 리소스 및 해당 리소스에서 수행할 수 있는 특정 작업과 관련된 키 값입니다. 애플리케이션의 API 키를 사용하여 해당 리소스에 대해 Amazon Location API를 인증되지 않은 상태로 호출할 수 있습니다. 예를 들어, API 키를 맵 리소스인 MyMap 및 GetMap* 작업에 연결하는 경우, 해당 API 키를 사용하는 애플리케이션은 해당 리소스로 생성된 맵을 볼 수 있게 되며 계정의 다른 사용량과 마찬가지로 사용자 계정에 요금이 부과됩니다. 동일한 API 키는 맵 리소스를 변경하거나 업데이트할 권한을 부여하지 않으며 해당 리소스만 사용할 수 있습니다.

API 키에는 하나 이상의 AWS 계정 리소스에 대한 액세스를 제공하는 일반 텍스트 값이 포함됩니다. 누군가 API 키를 복사해도 동일한 리소스에 액세스할 수 있습니다. 이를 방지하려면 키를 생성할 때 API 키를 사용할 수 있는 도메인을 지정할 수 있습니다. 이러한 도메인을 리퍼러라고 합니다. 필요한 경우 API 키의 만료 시간을 설정하여 단기 API 키를 생성할 수도 있습니다.

Amazon Cognito와 비교한 API 키

API 키와 Amazon Cognito는 유사한 시나리오에서 비슷한 방식으로 사용되는데, 둘 중 하나를 다른 것보다 더 사용하는 이유는 무엇입니까? 다음 표는 이 둘 사이의 차이점 중 일부를 강조합니다.

API 키 생성

API 키를 생성하여 하나 이상의 사용자 AWS 계정 리소스에 연결할 수 있습니다.

Amazon Location Service 콘솔AWS CLI 또는 Amazon Location API를 사용하여 API 키를 생성할 수 있습니다.

Console

Amazon Location Service 콘솔을 사용하여 API 키를 생성하려면

1. Amazon Location 콘솔의 왼쪽 메뉴에서 API 키를 선택합니다.

2. API 키 페이지에서 API 키 생성을 선택합니다.

3. API 키 생성 페이지에서 다음 정보를 입력합니다.

   • 이름 – API 키의 이름(예:MyWebAppKey).

   • 설명 – API 키에 대한 선택적 설명.

   • 리소스 – 드롭다운에서 이 API 키로 액세스 권한을 부여할 Amazon Location 리소스를 선택합니다. 리소스 추가를 선택하여 두 개 이상의 리소스를 추가할 수 있습니다.

   • 작업 – 이 API 키로 승인하려는 작업을 지정합니다. 선택한 각 리소스 유형과 일치하는 작업을 하나 이상 선택해야 합니다. 예를 들어, 장소 리소스를 선택한 경우 장소 작업에 있는 선택 항목 중 하나 이상을 선택해야 합니다.

   • 만료 시간 – 선택적으로 API 키의 만료 날짜 및 시간을 추가할 수 있습니다. 자세한 내용은 API 키 수명 관리 단원을 참조하십시오.

   • 리퍼러 – 선택적으로 API 키를 사용할 수 있는 도메인을 하나 이상 추가할 수 있습니다. 예를 들어example.com, 웹 사이트에서 실행되는 애플리케이션을 허용하는 것이 API 키인 경우 *.example.com/를 허용된 리퍼러로 지정할 수 있습니다.

   • 태그 – 선택적으로 API 키에 태그를 추가할 수 있습니다.

4. API 키 생성을 선택하여 API 키를 생성합니다.

5. API 키의 세부 정보 페이지에서, 생성한 API 키에 대한 정보를 볼 수 있습니다. Amazon 위치 API를 호출할 때 사용하는 키 값을 보려면 API 키 표시를 선택합니다. 키 값의 형식은 v1.public.a1b2c3d4...과 같습니다. API 키를 사용하여 맵을 렌더링하는 방법에 대한 자세한 내용은 API 키를 사용하여 맵 렌더링을 참조하세요.

API

Amazon Location API를 사용하여 API 키를 생성하려면

Amazon Location API에서 CreateKey 작업을 사용합니다.

다음 예는 만료일이 없는 ExampleKey라는 API 키를 생성하고 단일 맵 리소스에 액세스하기 위한 API 요청입니다.

POST /metadata/v0/keys HTTP/1.1
Content-type: application/json

{
   "KeyName": "ExampleKey"
   "Restrictions": { 
      "AllowActions": [
         "geo:GetMap*"
      ],
      "AllowResources": [
         "arn:aws:geo:region:map/mapname"
      ]
   },
   "NoExpiry": true
   }
}

응답에는 애플리케이션의 리소스에 액세스할 때 사용할 API 키 값이 포함됩니다. 키 값의 형식은 v1.public.a1b2c3d4...과 같습니다. API 키를 사용하여 맵을 렌더링하는 방법에 대한 자세한 내용은 API 키를 사용하여 맵 렌더링을 참조하세요.

DescribeKey API를 사용하여 나중에 키의 키 값을 찾을 수도 있습니다.

AWS CLI

AWS CLI 명령을 사용하여 API 키를 만들려면

create-key 명령을 사용합니다.

다음 예에서는 만료일이 없고 단일 맵 리소스에 액세스할 수 있는 ExampleKey라는 API 키를 생성합니다.

aws location \
  create-key \
  --key-name ExampleKey \
  --restrictions '{"AllowActions":["geo:GetMap*"],"AllowResources":["arn:aws:geo:region:map/mapname"]}' \
  --no-expiry

응답에는 애플리케이션의 리소스에 액세스할 때 사용할 API 키 값이 포함됩니다. 키 값의 형식은 v1.public.a1b2c3d4...과 같습니다. API 키를 사용하여 맵을 렌더링하는 방법에 대한 자세한 내용은 API 키를 사용하여 맵 렌더링을 참조하세요. create-key에 대한 응답은 다음과 같습니다.

{
    "Key": "v1.public.a1b2c3d4...",
    "KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
    "KeyName": "ExampleKey",
    "CreateTime": "2023-02-06T22:33:15.693Z"
}

describe-key을 사용하여 나중에 키 값을 찾을 수도 있습니다. 다음 예는 ExampleKey라는 API 키를 describe-key 호출하는 방법을 보여줍니다.

aws location describe-key \
    --key-name ExampleKey

API 키를 사용하여 Amazon Location API를 직접적으로 호출합니다.

API 키를 생성한 후 키 값을 사용하여 애플리케이션의 Amazon Location API를 호출할 수 있습니다.

API 키를 지원하는 API에는 API 키 값을 취하는 추가 파라미터가 있습니다. 예를 들어, GetPlace API를 호출하는 경우 다음과 같이 키 파라미터를 입력할 수 있습니다.

GET /places/v0/indexes/IndexName/places/PlaceId?key=KeyValue

이 값을 입력하면 평소처럼 AWS Sig v4로 API 호출을 인증할 필요가 없습니다.

JavaScript 개발자의 경우, Amazon Location JavaScript 인증 도우미을 사용하여 API 키로 API 작업을 인증하는 데 도움을 받을 수 있습니다.

모바일 개발자의 경우 다음 Amazon Location 모바일 인증 SDK를 사용할 수 있습니다.

AWS CLI 사용자의 경우, --key 파라미터를 사용할 때 Sig v4로 서명하지 않도록 --no-sign-request 파라미터도 사용해야 합니다.

API 키를 사용하여 맵 렌더링

API 키 값을 사용하여 MapLibre를 사용하여 애플리케이션에서 맵을 렌더링할 수 있습니다. 직접 호출하는 다른 Amazon Location API의 API 키를 사용하는 것과는 약간 다릅니다. MapLibre가 대신 호출하기 때문입니다.

다음 샘플 코드는 MapLibre GL JS 맵 컨트롤을 사용하여 API 키를 사용하여 간단한 웹 페이지에 맵을 렌더링하는 방법을 보여줍니다. 이 코드가 제대로 작동하도록 하려면 v1.public.your-api-key-value, us-east-1 및 exampleMap 문자열을 AWS 계정와 일치하는 값으로 바꾸세요.

<!-- index.html -->
<html>
  <head>
    <link href="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body { margin: 0; }
      #map { height: 100vh; }
    </style>
  </head>
  <body>
    <!-- Map container -->
    <div id="map" />
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.js"></script>
    <script>
      const apiKey = "v1.public.your-api-key-value"; // API key
      const region = "us-east-1"; // Region
      const mapName = "ExampleMap"; // Map name
      // URL for style descriptor
      const styleUrl = `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=${apiKey}`;
      // Initialize the map
      const map = new maplibregl.Map({
        container: "map",
        style: styleUrl,
        center: [-123.1187, 49.2819],
        zoom: 11,
      });
      map.addControl(new maplibregl.NavigationControl(), "top-left");
    </script>
  </body>
</html>

API 키 수명 관리

무기한으로 작동하는 API 키를 생성할 수 있습니다. 하지만 임시 API 키를 생성하거나 정기적으로 API 키를 교체하거나 기존 API 키를 취소하려는 경우에는 API 키 만료를 사용할 수 있습니다.

새 API 키를 만들거나 기존 API 키를 업데이트할 때 해당 API 키의 만료 시간을 설정할 수 있습니다.