JavaScript Authentication helper
The Amazon Location JavaScript authentication helper makes it simpler to authenticate when
making Amazon Location API calls from your JavaScript application. This authentication
helper specifically help you when using Amazon Cognito or API keys as your authentication
method. This is an open source library that is available on GitHub, here: https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js
Note
The Amazon Cognito support in the authentication helper does not support the federated identities feature of Amazon Cognito.
Installation
You can use the libraries with a local install, if you use a build system
like webpack, or by including pre-built JavaScript bundles with
<script>
tags in your html.
-
Use the following command to install the library, using NPM:
npm install @aws/amazon-location-utilities-auth-helper
-
Use the following command in your HTML file to load the script:
<script src="https://unpkg.com/@aws/amazon-location-utilities-auth-helper@1.x/dist/amazonLocationAuthHelper.js"></script>
Import
To use a specific function in your JavaScript application, you must import
that function. The following code is used to import the function
withIdentityPoolId
into your application.
import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper';
Authentication functions
The Amazon Location authentication helpers include the following functions
that return an AuthHelper
object:
-
async withIdentityPoolId( identityPoolId: string): AuthHelper
– This function returns an AuthHelper object, initialized to work with Amazon Cognito -
async withAPIKey( API_KEY: string): AuthHelper
– This function returns an AuthHelper object, initialized to work with API Keys.
The AuthHelper
object provides the following functions:
-
AuthHelper.getMapAuthenticationOptions()
– This function of the AuthHelper object returns a JavaScript object with thetransformRequest
that can be used with the map options in MapLibre JS. Only provided when initialized with an identity pool. -
AuthHelper.getLocationClientConfig()
– This function of the AuthHelper object returns a JavaScript object with thecredentials
that can be used to initialize a LocationClient. -
AuthHelper.getCredentials()
– This function of the AuthHelper object returns the internal credentials from Amazon Cognito. Only provided when initialized with an identity pool.
Example: Initializing MapLibre map object with Amazon Cognito, using an AuthHelper
import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper'; const authHelper = await withIdentityPoolId("
identity-pool-id
"); // use Cognito pool id for credentials const map = new maplibregl.Map({ container: "map
", // HTML element ID of map element center: [-123.1187, 49.2819], // initial map center point zoom: 16, // initial map zoom style: https://maps.geo.region
.amazonaws.com/maps/v0/maps/mapName
/style-descriptor', // Defines the appearance of the map ...authHelper.getMapAuthenticationOptions(), // Provides credential options required for requests to Amazon Location });
Example: Initializing MapLibre map
object with an API key (AuthHelper
is not needed in this
case)
const map = new maplibregl.Map({ container: "
map
", // HTML element ID of map element center: [-123.1187, 49.2819], // initial map center point zoom: 16, // initial map zoom style: https://maps.geo.region
.amazonaws.com/maps/v0/maps/${mapName
}/style-descriptor?key=api-key-id
', });
Example: Initialize the Location client from the AWS SDK for JS, using Amazon Cognito and AuthHelper
This example uses AWS SDK for JavaScript v3.
import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper'; const authHelper = await withIdentityPoolId("
identity-pool-id
"); // use Cognito pool id for credentials //initialize the Location client: const client = new LocationClient({ region: "region
", ...authHelper.getLocationClientConfig() // sets up the Location client to use the Cognito pool defined above }); //call a search function with the location client: const result = await client.send(new SearchPlaceIndexForPositionCommand({ IndexName: "place-index
", // Place index resource to use Position: [-123.1187, 49.2819], // position to search near MaxResults: 10 // number of results to return });
Example: Initialize the Location client from the AWS SDK for JS, using an API key and AuthHelper
This example uses AWS SDK for JavaScript v3.
import { withAPIKey } from '@aws/amazon-location-utilities-auth-helper'; const authHelper = await withAPIKey("
api-key-id
"); // use API Key id for credentials //initialize the Location client: const client = new LocationClient({ region: "region
", ...authHelper.getLocationClientConfig() // sets up the Location client to use the API Key defined above }); //call a search function with the location client: const result = await client.send(new SearchPlaceIndexForPositionCommand({ IndexName: "place-index
", // Place index resource to use Position: [-123.1187, 49.2819], // position to search near MaxResults: 10 // number of results to return });