API キーを使用してアプリケーションへの認証されていないゲストアクセスを許可する

アプリケーションで Amazon Location Service API を呼び出すときは、通常、API 呼び出しを行う権限を持つ認証済みユーザーとしてこの呼び出しを行います。ただし、アプリケーションのすべてのユーザーを認証したくないケースも場合もあるでしょう。例えば、会社の所在地を表示する Web アプリケーションを、ログインしているかどうかに関係なく、Web サイトを使用するすべてのユーザーが利用できるようにしたい場合があります。この場合API キーを使ってAPI 呼び出しを行うという方法もあります。

API キーは、AWS アカウント内の特定の Amazon Location Service リソースと、それらのリソースに対して実行できる特定のアクションに関連付けられたキー値です。アプリケーションの API キーを使用して、それらのリソースの Amazon Location API を認証なしで呼び出すことができます。例えば、API キーをマップリソース MyMap とGetMap* アクションに関連付けると、その API キーを使用するアプリケーションはそのリソースで作成されたマップを表示できるようになり、アカウントの他の使用量と同様にアカウントに請求されます。同じ API キーを使用しても、マップリソースの変更または更新の権限は付与されません。リソースの使用のみが許可されます。

API キーには、AWS アカウント 内の 1 つ以上のリソースへのアクセスを許可するプレーンテキストの値が含まれています。API キーをコピーしたユーザーは、同じリソースにアクセスできます。これを回避するには、API キーを作成するときに API キーの使用ができるドメインを指定することができます。これらのドメインはリファラーと呼ばれます。必要に応じて、API キーの有効期限を設定して短期間の API キーを作成することもできます。

API キーと Amazon Cognito の比較

API キーと Amazon Cognito は、似たようなシナリオでも同じような方法で使用されます。では、なぜ一方を他方よりも優先して使用するのでしょうか。以下のリストでは、その 2 つの違いをいくつか紹介します。

API キーを作成する

API キーを作成し、AWS アカウントの 1 つまたは複数のリソースに関連付けることができます。

API キーは、Amazon Location Service コンソール、AWS CLI、または Amazon Location API を使用して作成することができます。

Console

Amazon Location Service コンソールを使用して API キーを作成する

1. Amazon Location コンソールで、左側のメニューから API キーを選択します。

2. [API キー] ページで、[API キーの作成] を選択します。

3. API キーの作成ページで、次の情報を入力します。

   • 名前— API キーの名前、例えば MyWebAppKey。

   • 説明 — API キーのオプションの説明。

   • リソース — この API キーを使用してアクセスを許可する Amazon Location リソースをドロップダウンから選択します。リソースの追加を選択すると、複数のリソースを追加できます。

   • アクション — この API キーを利用して、承認したアクションを指定します。選択した各リソースタイプと一致するアクションを少なくとも 1 つ選択する必要があります。例えば、Place リソースを選択した場合は、Places Actions の下にある選択肢を少なくとも 1 つ選択する必要があります。

   • 有効期限 — API キーの有効期限を任意で追加することができます。詳細については、「API キーの有効期間を管理する」を参照してください。

   • リファラー — API キーの使用ができるドメインを 1 つ以上追加することもできます。例えば、API キーがウェブサイトexample.comで実行されるアプリケーションを許可するものであれば、許可されるリファラーとして*.example.com/を置くことができます。

   • タグ — オプションで API キーにタグを追加します。

4. API キーを作成を選択して API キーを作成します。

5. API キーの詳細ページには、作成した API キーに関する情報が表示されます。API キーを表示を選択すると、Amazon Location API を呼び出すときに使用するキーバリューが表示されます。キー値は次のフォーマットになりますv1.public.a1b2c3d4...。API キーを使用してマップをレンダリングする方法の詳細については、API キーを使用してマップをレンダリングする をご参照ください。

API

Amazon Location API を使用して API キーを作成するには

Amazon Location API CreateKey のオペレーションを使用してください。

次の例は、ExampleKey という名前の API キーを作成し、有効期限なしで 1 つのマップリソースにアクセスする 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 キーを使用してマップをレンダリングする」をご参照ください。

DescribeKeyAPI を使用してキーのキー値を後で検索することもできます。

AWS CLI

AWS CLI コマンドを使用して API キーを作成するには

create-key コマンドを実行します。

次の例では、有効期限なしで ExampleKey という名前の API キーを作成し、1 つのマップリソースにアクセスします。

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 Mobile Authentication SDK を使用できます。

AWS CLIユーザーの場合、Sig v4 での署名を避けるため、--keyパラメータを使用する場合は--no-sign-requestパラメータも使用する必要があります。

API キーを使用してマップをレンダリングする

API キー値を使用すると、MapLibre を使用してアプリケーションでマップをレンダリングすることができます。これは、ユーザーが直接呼び出す他の Amazon Location API の API キーを使用する場合とは少し異なります。MapLibre がこれらの呼び出しを自動的に行うからです。

次のサンプルコードは、API キーを使用して MapLibre GL JS マップコントロールを使用して単純なウェブページにマップをレンダリングする方法を示しています。このコードが正しく動作するためには、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 キーの有効期限を設定することができます。