Granting access to Amazon Location Service - Amazon Location Service

Granting access to Amazon Location Service

To use Amazon Location Service, your AWS account must be granted access to the resources and APIs that make up Amazon Location. To grant access to an AWS account, use AWS Identity and Access Management (IAM), and create a policy that grants access to the resources that you want. For more information about IAM and Amazon Location, see Identity and Access Management for Amazon Location Service.

You can also use Amazon Cognito to grant anonymous access, or to use your own separate authentication with Amazon Location Service.

Allowing unauthenticated guest access to your application using Amazon Cognito

You can use Amazon Cognito authentication as an alternative to directly using AWS Identity and Access Management (IAM) with both frontend SDKs and direct HTTPS requests.

You may want to use this form of authentication for the following reasons:

  • Unauthenticated users – If you have a website with anonymous users, you can use Amazon Cognito identity pools. For more information, see the section on Allowing unauthenticated guest access to your application using Amazon Cognito.

  • Your own authentication – If you would like to use your own authentication process, or combine multiple authentication methods, you can use Amazon Cognito Federated Identities. For more information, see Getting Started with Federated Identities in the Amazon Cognito Developer Guide.

Amazon Cognito provides authentication, authorization, and user management for web and mobile apps. You can use Amazon Cognito unauthenticated identity pools with Amazon Location as a way for applications to retrieve temporary, scoped-down AWS credentials.

For more information, see Getting Started with User Pools in the Amazon Cognito Developer Guide.

Create an Amazon Cognito identity pool

You can create Amazon Cognito identity pools to allow unauthenticated guest access to your application through the Amazon Cognito console, the AWS CLI, or the Amazon Cognito APIs.

Important

The pool that you create must be in the same AWS account and AWS Region as the Amazon Location Service resources that you're using.

You can use IAM policies associated with unauthenticated identity roles with the following actions:

  • geo:GetMap*

  • geo:SearchPlaceIndex*

  • geo:CalculateRoute*

  • geo:GetGeofence

  • geo:ListGeofences

  • geo:PutGeofence

  • geo:BatchDeleteGeofence

  • geo:BatchPutGeofence

  • geo:BatchEvaluateGeofences

  • geo:GetDevicePosition*

  • geo:ListDevicePositions

  • geo:BatchDeleteDevicePositionHistory

  • geo:BatchGetDevicePosition

  • geo:BatchUpdateDevicePosition

Including other Amazon Location actions will have no effect, and unauthenticated identities will be unable to call them.

To create an identity pool using the Amazon Cognito console

  1. Go to the Amazon Cognito console.

  2. Choose Manage Identity Pools.

  3. Choose Create new identity pool, then enter a name for your identity pool.

  4. From the Unauthenticated identities collapsible section, choose Enable access to unauthenticated identities.

  5. Choose Create Pool.

  6. Choose which IAM roles you want to use with your identity pool.

  7. Expand View Details.

  8. Under Unauthenticated identities, enter a role name.

  9. Expand the View Policy Document section, then choose Edit to add your policy.

  10. Add your policy to grant access to your resources.

    The following are policy examples for Maps, Places, Trackers, and Routes. To use the examples for your own policy, replace the region and accountID placeholders:

    Maps policy example

    The following policy grants read-only access to a map resource named ExampleMap.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "MapsReadOnly", "Effect": "Allow", "Action": [ "geo:GetMapStyleDescriptor", "geo:GetMapGlyphs", "geo:GetMapSprites", "geo:GetMapTile" ], "Resource": "arn:aws:geo:region:accountID:map/ExampleMap" } ] }

    Adding an IAM condition that matches aws:referer lets you limit browser access to your resources to a list of URLs or URL prefixes. The following example denies access to a map resource named RasterEsriImagery from all referring websites except example.com:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "geo:GetMap*", "Resource": "arn:aws:geo:us-west-2:111122223333:map/RasterEsriImagery", "Condition": { "StringLike": { "aws:referer": [ "https://example.com/*", "https://www.example.com/*" ] } } } ] }

    If you're using Tangram to display a map, it doesn't use the style descriptors, glyphs, or sprites returned by the Maps API. Instead, it's configured by pointing to a .zip file that contains style rules and necessary assets. The following policy grants read-only access to a map resource named ExampleMap for the GetMapTile operation.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "MapsReadOnly", "Effect": "Allow", "Action": [ "geo:GetMapTile" ], "Resource": "arn:aws:geo:region:accountID:map/ExampleMap" } ] }
    Places policy example

    The following policy grants read-only access to a place index resource named ExamplePlaceIndex to search for places by text or positions.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "PlacesReadOnly", "Effect": "Allow", "Action": "geo:SearchPlaceIndex*", "Resource": "arn:aws:geo:region:accountID:place-index/ExamplePlaceIndex" } ] }

    Adding an IAM condition that matches aws:referer lets you limit browser access to your resources to a list of URLs or URL prefixes. The following example denies access to a place index resource named ExamplePlaceIndex from all referring websites, except example.com.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "geo:*", "Resource": "arn:aws:geo:us-west-2:111122223333:place-index/ExamplePlaceIndex", "Condition": { "StringLike": { "aws:referer": [ "https://example.com/*", "https://www.example.com/*" ] } } } ] }
    Trackers policy example

    The following policy grants access to a tracker resource named ExampleTracker to update device positions.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "UpdateDevicePosition", "Effect": "Allow", "Action": [ "geo:BatchUpdateDevicePosition" ], "Resource": "arn:aws:geo:region:accountID:tracker/ExampleTracker" } ] }

    Adding an IAM condition that matches aws:referer lets you limit browser access to your resources to a list of URLs or URL prefixes. The following example denies access to a tracker resource named ExampleTracker from all referring websites, except example.com.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "geo:GetDevice*", "Resource": "arn:aws:geo:us-west-2:111122223333:tracker/ExampleTracker", "Condition": { "StringLike": { "aws:referer": [ "https://example.com/*", "https://www.example.com/*" ] } } } ] }
    Routes policy example

    The following policy grants access to a route calculator resource named ExampleCalculator to calculate a route.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "RoutesReadOnly", "Effect": "Allow", "Action": [ "geo:CalculateRoute" ], "Resource": "arn:aws:geo:region:accountID:route-calculator/ExampleCalculator" } ] }

    Adding an IAM condition that matches aws:referer lets you limit browser access to your resources to a list of URLs or URL prefixes. The following example denies access to a route calculator named ExampleCalculator from all referring websites, except example.com.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "geo:*", "Resource": "arn:aws:geo:us-west-2:111122223333:route-calculator/ExampleCalculator", "Condition": { "StringLike": { "aws:referer": [ "https://example.com/*", "https://www.example.com/*" ] } } } ] }
    Note

    While unauthenticated identity pools are intended for exposure on unsecured internet sites, note that they will be exchanged for standard, time-limited AWS credentials.

    It's important to scope the IAM roles associated with unauthenticated identity pools appropriately.

    Using an aws:referer condition adds security by limiting browser access to a list of URLs or URL prefixes. Adding an aws:referer condition may also limit testing when using localhost: URLs.

  11. Choose Allow to create your identity pools.

The resulting identity pool follows the syntax <region>:<GUID>.

For example:

us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd

For more policy examples specific to Amazon Location, see Amazon Location Service identity-based policy examples.

Using the Amazon Cognito identity pools in JavaScript

The following example exchanges the unauthenticated identity pool that you've created for credentials that are then used to fetch the style descriptor for your map resource ExampleMap.

const AWS = require("aws-sdk"); const credentials = new AWS.CognitoIdentityCredentials({ IdentityPoolId: "<identity pool ID>" // e.g., us-east-1:d40a3a95-a6b5-4816-a15c-a15ac4f0930d }); const client = new AWS.Location({ credentials, region: AWS.config.region || "<region>" }); console.log(await client.getMapStyleDescriptor("ExampleMap").promise());
Note

Retrieved credentials from unauthenticated identities are valid for one hour.

The following is an example of a function that automatically renews credentials before they expire.

async function refreshCredentials() { await credentials.refreshPromise(); // schedule the next credential refresh when they're about to expire setTimeout(refreshCredentials, credentials.expireTime - new Date()); }

Next steps