@aws/amazon-location-utilities-auth-helper 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
# Amazon Location Utilities - Authentication Helper for JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
These are utilities to help customers authenticate when making [Amazon Location Service](https://aws.amazon.com/location/) API calls from their JavaScript applications. This specifically helps when using [Amazon Cognito](https://docs.aws.amazon.com/location/latest/developerguide/authenticating-using-cognito.html) or [API keys](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html) as the authentication method.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
7
|
Install this library from NPM for usage with modules:
|
|
8
8
|
|
|
9
|
-
```
|
|
9
|
+
```console
|
|
10
10
|
npm install @aws/amazon-location-utilities-auth-helper
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
Importing in an HTML file for usage directly in the browser.
|
|
14
14
|
|
|
15
15
|
```html
|
|
16
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1
|
|
16
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1"></script>
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
## Usage
|
|
20
20
|
|
|
21
21
|
Import the library and call the utility functions in the top-level namespace as needed. You can find more details about these functions in the [Documentation](#documentation) section.
|
|
22
22
|
|
|
@@ -25,19 +25,17 @@ Import the library and call the utility functions in the top-level namespace as
|
|
|
25
25
|
This example uses the [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3) to make a request that that authenticates using Amazon Cognito.
|
|
26
26
|
|
|
27
27
|
```javascript
|
|
28
|
-
//
|
|
28
|
+
// Import from the AWS JavaScript SDK V3
|
|
29
29
|
import { LocationClient, CalculateRouteCommand } from "@aws-sdk/client-location";
|
|
30
|
-
//
|
|
30
|
+
// Import the utility functions
|
|
31
31
|
import { withIdentityPoolId } from "@aws/amazon-location-utilities-auth-helper";
|
|
32
32
|
|
|
33
|
-
const identityPoolId = "<Identity Pool ID>";
|
|
34
|
-
|
|
35
33
|
// Create an authentication helper instance using credentials from Cognito
|
|
36
|
-
const authHelper = await withIdentityPoolId(
|
|
34
|
+
const authHelper = await withIdentityPoolId("<Identity Pool ID>");
|
|
37
35
|
|
|
38
36
|
const client = new LocationClient({
|
|
39
|
-
region: "<Region>", //
|
|
40
|
-
...authHelper.getLocationClientConfig(), //
|
|
37
|
+
region: "<Region>", // Region containing Amazon Location resources
|
|
38
|
+
...authHelper.getLocationClientConfig(), // Configures the client to use credentials obtained via Amazon Cognito
|
|
41
39
|
});
|
|
42
40
|
const input = { ... };
|
|
43
41
|
const command = new CalculateRouteCommand(input);
|
|
@@ -47,38 +45,36 @@ const response = await client.send(command);
|
|
|
47
45
|
This example uses the [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3) to make a request that that authenticates using API keys.
|
|
48
46
|
|
|
49
47
|
```javascript
|
|
50
|
-
//
|
|
48
|
+
// Import from the AWS JavaScript SDK V3
|
|
51
49
|
import { LocationClient, CalculateRouteCommand } from "@aws-sdk/client-location";
|
|
52
|
-
//
|
|
50
|
+
// Import the utility functions
|
|
53
51
|
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";
|
|
54
52
|
|
|
55
|
-
const apiKey = "<API Key>";
|
|
56
|
-
|
|
57
53
|
// Create an authentication helper instance using an API key
|
|
58
|
-
const authHelper = await withAPIKey(
|
|
54
|
+
const authHelper = await withAPIKey("<API Key>");
|
|
59
55
|
|
|
60
56
|
const client = new LocationClient({
|
|
61
|
-
region: "<Region>", //
|
|
62
|
-
...authHelper.getLocationClientConfig(), //
|
|
57
|
+
region: "<Region>", // Region containing Amazon Location resource
|
|
58
|
+
...authHelper.getLocationClientConfig(), // Configures the client to use API keys when making supported requests
|
|
63
59
|
});
|
|
64
60
|
const input = { ... };
|
|
65
61
|
const command = new CalculateRouteCommand(input);
|
|
66
62
|
const response = await client.send(command);
|
|
67
63
|
```
|
|
68
64
|
|
|
69
|
-
This example uses [MapLibre GL JS](https://maplibre.org/projects/maplibre-gl-js/) to
|
|
65
|
+
This example uses [MapLibre GL JS](https://maplibre.org/projects/maplibre-gl-js/) to render a map that authenticates resource requests using Amazon Cognito.
|
|
70
66
|
|
|
71
|
-
> The authentication helper is not needed
|
|
67
|
+
> The authentication helper is not needed when using MapLibre GL JS to render a map using API keys. The style descriptor URL and API key can be passed into the style endpoint following [this guide](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html#using-apikeys-in-maps).
|
|
72
68
|
|
|
73
69
|
```javascript
|
|
74
|
-
//
|
|
70
|
+
// Import MapLibre GL JS
|
|
75
71
|
import maplibregl from "maplibre-gl";
|
|
76
|
-
//
|
|
72
|
+
// Import the utility function
|
|
77
73
|
import { withIdentityPoolId } from "@aws/amazon-location-utilities-auth-helper";
|
|
78
74
|
|
|
79
75
|
const identityPoolId = "<Identity Pool ID>";
|
|
80
76
|
const mapName = "<Map Name>";
|
|
81
|
-
const region = "<Region>"; //
|
|
77
|
+
const region = "<Region>"; // Region containing Amazon Location resource
|
|
82
78
|
|
|
83
79
|
// Create an authentication helper instance using credentials from Cognito
|
|
84
80
|
const authHelper = await withIdentityPoolId(identityPoolId);
|
|
@@ -93,30 +89,28 @@ const map = new maplibregl.Map({
|
|
|
93
89
|
});
|
|
94
90
|
```
|
|
95
91
|
|
|
96
|
-
### Usage with
|
|
92
|
+
### Usage with a browser
|
|
97
93
|
|
|
98
|
-
Utility functions
|
|
94
|
+
Utility functions are available under the `amazonLocationAuthHelper` global.
|
|
99
95
|
|
|
100
|
-
> Some of these example use the Amazon Location Client. The Amazon Location Client is based on the [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3)
|
|
96
|
+
> Some of these example use the Amazon Location Client. The Amazon Location Client is based on the [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3) and allows for making calls to Amazon Location through a script referenced in an HTML file.
|
|
101
97
|
|
|
102
98
|
This example uses the Amazon Location Client to make a request that that authenticates using Amazon Cognito.
|
|
103
99
|
|
|
104
100
|
```html
|
|
105
|
-
<!--
|
|
106
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-client@1
|
|
107
|
-
<!--
|
|
108
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1
|
|
101
|
+
<!-- Import the Amazon Location Client -->
|
|
102
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-client@1"></script>
|
|
103
|
+
<!-- Import the utility library -->
|
|
104
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1"></script>
|
|
109
105
|
```
|
|
110
106
|
|
|
111
107
|
```javascript
|
|
112
|
-
const identityPoolId = "<Identity Pool ID>";
|
|
113
|
-
|
|
114
108
|
// Create an authentication helper instance using credentials from Cognito
|
|
115
|
-
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(
|
|
109
|
+
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId("<Identity Pool ID>");
|
|
116
110
|
|
|
117
111
|
const client = new amazonLocationClient.LocationClient({
|
|
118
|
-
region: "<Region>", //
|
|
119
|
-
...authHelper.getLocationClientConfig(), //
|
|
112
|
+
region: "<Region>", // Region containing Amazon Location resource
|
|
113
|
+
...authHelper.getLocationClientConfig(), // Configures the client to use credentials obtained via Amazon Cognito
|
|
120
114
|
});
|
|
121
115
|
const input = { ... };
|
|
122
116
|
const command = new amazonLocationClient.CalculateRouteCommand(input);
|
|
@@ -127,35 +121,33 @@ This example uses the Amazon Location Client to make a request that that authent
|
|
|
127
121
|
|
|
128
122
|
```html
|
|
129
123
|
<!-- Importing Amazon Location Client -->
|
|
130
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-client@1
|
|
124
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-client@1"></script>
|
|
131
125
|
<!-- Importing the utility library from an HTML file -->
|
|
132
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1
|
|
126
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1"></script>
|
|
133
127
|
```
|
|
134
128
|
|
|
135
129
|
```javascript
|
|
136
|
-
const apiKey = "<API Key>";
|
|
137
|
-
|
|
138
130
|
// Create an authentication helper instance using an API key
|
|
139
|
-
const authHelper = await amazonLocationAuthHelper.withAPIKey(
|
|
131
|
+
const authHelper = await amazonLocationAuthHelper.withAPIKey("<API Key>");
|
|
140
132
|
|
|
141
133
|
const client = new amazonLocationClient.LocationClient({
|
|
142
|
-
region: "<Region>", //
|
|
143
|
-
...authHelper.getLocationClientConfig(), //
|
|
134
|
+
region: "<Region>", // Region containing Amazon Location resource
|
|
135
|
+
...authHelper.getLocationClientConfig(), // Configures the client to use API keys when making supported requests
|
|
144
136
|
});
|
|
145
137
|
const input = { ... };
|
|
146
138
|
const command = new amazonLocationClient.CalculateRouteCommand(input);
|
|
147
139
|
const response = await client.send(command);
|
|
148
140
|
```
|
|
149
141
|
|
|
150
|
-
This example uses [MapLibre GL JS](https://maplibre.org/projects/maplibre-gl-js/) to
|
|
142
|
+
This example uses [MapLibre GL JS](https://maplibre.org/projects/maplibre-gl-js/) to render a map that authenticates resource requests using Amazon Cognito.
|
|
151
143
|
|
|
152
|
-
> The authentication helper is not needed
|
|
144
|
+
> The authentication helper is not needed when using MapLibre GL JS to render a map using API keys. The style descriptor URL and API key can be passed into the style endpoint following [this guide](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html#using-apikeys-in-maps).
|
|
153
145
|
|
|
154
146
|
```html
|
|
155
147
|
<!-- MapLibre GL JS -->
|
|
156
|
-
<script src="https://www.unpkg.com/maplibre-gl@3
|
|
148
|
+
<script src="https://www.unpkg.com/maplibre-gl@3"></script>
|
|
157
149
|
<!-- Importing the utility library from an HTML file -->
|
|
158
|
-
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1
|
|
150
|
+
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1"></script>
|
|
159
151
|
```
|
|
160
152
|
|
|
161
153
|
```javascript
|
|
@@ -176,15 +168,15 @@ const map = new maplibregl.Map({
|
|
|
176
168
|
});
|
|
177
169
|
```
|
|
178
170
|
|
|
179
|
-
|
|
171
|
+
## Documentation
|
|
180
172
|
|
|
181
|
-
Detailed documentation can be
|
|
173
|
+
Detailed documentation can be generated under `docs/index.html` by running:
|
|
182
174
|
|
|
183
|
-
```
|
|
175
|
+
```console
|
|
184
176
|
npm run typedoc
|
|
185
177
|
```
|
|
186
178
|
|
|
187
|
-
|
|
179
|
+
### `withIdentityPoolId`
|
|
188
180
|
|
|
189
181
|
Creates an auth helper instance using credentials from Cognito.
|
|
190
182
|
|
|
@@ -192,7 +184,7 @@ Creates an auth helper instance using credentials from Cognito.
|
|
|
192
184
|
const authHelper = await withIdentityPoolId(identityPoolId);
|
|
193
185
|
```
|
|
194
186
|
|
|
195
|
-
|
|
187
|
+
### `withAPIKey`
|
|
196
188
|
|
|
197
189
|
Creates an auth helper instance using API key.
|
|
198
190
|
|
|
@@ -200,7 +192,7 @@ Creates an auth helper instance using API key.
|
|
|
200
192
|
const authHelper = await withAPIKey(apiKey);
|
|
201
193
|
```
|
|
202
194
|
|
|
203
|
-
|
|
195
|
+
## Getting Help
|
|
204
196
|
|
|
205
197
|
The best way to interact with our team is through GitHub.
|
|
206
198
|
You can [open an issue](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new/choose) and choose from one of our templates for
|
|
@@ -209,15 +201,15 @@ You can [open an issue](https://github.com/aws-geospatial/amazon-location-utilit
|
|
|
209
201
|
or [guidance](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new?assignees=&labels=guidance%2C+needs-triage&template=---questions---help.md&title=).
|
|
210
202
|
If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
|
|
211
203
|
|
|
212
|
-
Please make sure to check out
|
|
204
|
+
Please make sure to check out the following resources before opening an issue:
|
|
213
205
|
|
|
214
206
|
- Our [Changelog](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/blob/master/CHANGELOG.md) for recent changes.
|
|
215
207
|
|
|
216
|
-
|
|
208
|
+
## Contributing
|
|
217
209
|
|
|
218
210
|
We welcome community contributions and pull requests. See [CONTRIBUTING.md](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/blob/master/CONTRIBUTING.md) for information on how to set up a development environment and submit code.
|
|
219
211
|
|
|
220
|
-
|
|
212
|
+
## License
|
|
221
213
|
|
|
222
214
|
Amazon Location Utilities - Authentication Helper for JavaScript is distributed under the
|
|
223
215
|
[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),
|
|
@@ -453,4 +453,5 @@ if(url.includes("amazonaws.com")){return{url:Signer.signUrl(url,{access_key:cred
|
|
|
453
453
|
*
|
|
454
454
|
* @param apiKey APIKey
|
|
455
455
|
*/async function withAPIKey(apiKey){return{getLocationClientConfig:()=>({signer:{sign:async requestToSign=>{var _a;// APIKey in the command can override the APIKey set by auth helper.
|
|
456
|
-
requestToSign.query=Object.assign({key:apiKey},(_a=requestToSign.query)!==null&&_a!==void 0?_a:{});return requestToSign}}
|
|
456
|
+
requestToSign.query=Object.assign({key:apiKey},(_a=requestToSign.query)!==null&&_a!==void 0?_a:{});return requestToSign}},// Empty value to avoid calling the default credential providers chain
|
|
457
|
+
credentials:async()=>({})})}}});
|
package/dist/cjs/apikey/index.js
CHANGED
package/dist/esm/apikey/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AwsCredentialIdentity,
|
|
1
|
+
import { AwsCredentialIdentity, AwsCredentialIdentityProvider, RequestSigner } from "@aws-sdk/types";
|
|
2
2
|
export interface MapAuthenticationOptions {
|
|
3
3
|
transformRequest: (url: string, resourceType?: string) => {
|
|
4
4
|
url: string;
|
|
@@ -6,7 +6,7 @@ export interface MapAuthenticationOptions {
|
|
|
6
6
|
}
|
|
7
7
|
export interface LocationClientConfig {
|
|
8
8
|
signer?: RequestSigner;
|
|
9
|
-
credentials?:
|
|
9
|
+
credentials?: AwsCredentialIdentityProvider;
|
|
10
10
|
}
|
|
11
11
|
export type getMapAuthenticationOptionsFunc = () => MapAuthenticationOptions;
|
|
12
12
|
export type getLocationClientConfigFunc = () => LocationClientConfig;
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "@aws/amazon-location-utilities-auth-helper",
|
|
3
3
|
"description": "Amazon Location Utilities - Authentication Helper for JavaScript",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
|
-
"version": "1.0.
|
|
5
|
+
"version": "1.0.4",
|
|
6
6
|
"keywords": [],
|
|
7
7
|
"author": {
|
|
8
8
|
"name": "Amazon Web Services",
|
|
@@ -24,8 +24,10 @@
|
|
|
24
24
|
"engines": {
|
|
25
25
|
"node": ">= 16.0.0"
|
|
26
26
|
},
|
|
27
|
+
"browser": "./dist/amazonLocationAuthHelper.js",
|
|
27
28
|
"main": "./dist/cjs/index.js",
|
|
28
29
|
"module": "./dist/esm/index.js",
|
|
30
|
+
"unpkg": "./dist/amazonLocationAuthHelper.js",
|
|
29
31
|
"types": "./dist/types/index.d.ts",
|
|
30
32
|
"files": [
|
|
31
33
|
"./LICENSE.txt",
|