@cumulus/oauth-client
Utilities for OAuth authentication using NASA Earthdata Login and AWS Cognito.
Versioning
Cumulus uses a modified semantic versioning scheme and minor releases likely include breaking changes.
Before upgrade, please read the Cumulus release notes before upgraded.
It is strongly recommended you do not use ^
in your package.json
to
automatically update to new minor versions. Instead, pin the version or use ~
to automatically update to new patch versions.
Installation
$ npm install @cumulus/oauth-client
Class Structure
This package contains a generic, parent class called OAuthClient
. This class has a few common methods
like oAuthClient.getAuthorizationUrl()
which are used by all classes that inherit from OAuthClient
.
The examples below document these common methods as well as methods specific to the child classes, e.g.
cognitoClient.getUserInfo(accessToken)
.
Earthdata Login Usage Example
const { EarthdataLoginClient } = require('@cumulus/oauth-client');
const client = new EarthdataLogin({
clientId: 'my-client-id',
clientPassword: 'my-client-password',
loginUrl: 'https://earthdata.login.nasa.gov',
redirectUri: 'http://my-api.com'
});
Cognito Usage Example
const { CognitoClient } = require('@cumulus/oauth-client');
const client = new CognitoClient({
clientId: 'my-client-id',
clientPassword: 'my-client-password',
loginUrl: 'https://auth.csdap.sit.earthdatacloud.nasa.gov/',
redirectUri: 'http://my-api.com'
});
API
Classes
- CognitoClient
-
A client for the Cognito API. Extents OAuthClient.
- EarthdataLoginClient
-
A client for the Earthdata Login API. Extents OAuthClient.
- OAuthClient
-
A generic authorization client
CognitoClient
A client for the Cognito API. Extents OAuthClient.
Promise.<Object>
cognitoClient.getUserInfo(params) ⇒ Query the API for the user object associated with an access token.
Kind: instance method of CognitoClient
Returns: Promise.<Object>
- The user object (see example)
Param | Type | Description |
---|---|---|
params | Object |
|
params.token | string |
The access token for Authorization header |
[params.xRequestId] | string |
a string to help identify the request |
Example
{
"username": "janedoe",
"given_name": "Jane",
"family_name": "Doe",
"study_area": "Atmospheric Composition",
"organization": "NASA",
"email": "janedoe@example.com"
}
EarthdataLoginClient
A client for the Earthdata Login API. Extents OAuthClient.
Kind: global class
-
EarthdataLoginClient
-
.getUserInfo(params) ⇒
Promise.<Object>
-
.getTokenUsername(params) ⇒
Promise.<string>
-
.getUserInfo(params) ⇒
Promise.<Object>
earthdataLoginClient.getUserInfo(params) ⇒ Query the API for the user object associated with a user.
Kind: instance method of EarthdataLoginClient
Returns: Promise.<Object>
- The user object (see example)
Param | Type | Description |
---|---|---|
params | Object |
|
params.token | string |
The access token for Authorization header |
params.username | string |
The uid of the registered user |
[params.xRequestId] | string |
a string to help identify the request |
Example
{
"uid": "janedoe",
"first_name": "Jane",
"last_name": "Doe",
"registered_date": "15 Sep 2015 12:42:17PM",
"email_address": "janedoe@example.com",
"country": "United States",
"affiliation": "Government",
"authorized_date": "21 Apr 2016 01:13:28AM",
"allow_auth_app_emails": true,
"agreed_to_meris_eula": false,
"agreed_to_sentinel_eula": false,
"app_content": {
"param1": "value1",
"app_groups": {
"test": {
"param2": "value2"
}
}
},
"user_groups": [],
"user_authorized_apps": 3
}
Promise.<string>
earthdataLoginClient.getTokenUsername(params) ⇒ Query the Earthdata Login API for the UID associated with a token
Kind: instance method of EarthdataLoginClient
Returns: Promise.<string>
- the UID associated with the token
Param | Type | Description |
---|---|---|
params | Object |
|
params.onBehalfOf | string |
the Earthdata Login client id of the app requesting the username |
params.token | string |
the Earthdata Login token |
[params.xRequestId] | string |
a string to help identify the request in the Earthdata Login logs |
OAuthClient
A generic authorization client
Kind: global class
-
OAuthClient
- new OAuthClient(params)
-
.getAuthorizationUrl([state]) ⇒
string
-
.getAccessToken(authorizationCode) ⇒
Promise.<Object>
-
.postRequest(params) ⇒
CancelableRequest.<Response.<unknown>>
-
.getRequest(params) ⇒
CancelableRequest.<Response.<unknown>>
-
.refreshAccessToken(refreshToken) ⇒
Promise.<Object>
new OAuthClient(params)
Param | Type | Description |
---|---|---|
params | Object |
|
params.clientId | string |
see example |
params.clientPassword | string |
see example |
params.loginUrl | string |
see example |
params.redirectUri | string |
see example |
Example
const oAuth2Provider = new OAuthClient({
clientId: 'my-client-id',
clientPassword: 'my-client-password',
loginUrl: 'https://earthdata.login.nasa.gov',
redirectUri: 'http://my-api.com'
});
string
oAuthClient.getAuthorizationUrl([state]) ⇒ Get a URL of the Login authorization endpoint
Kind: instance method of OAuthClient
Returns: string
- the Login authorization URL
Param | Type | Description |
---|---|---|
[state] | string |
an optional state to pass to login Client |
Promise.<Object>
oAuthClient.getAccessToken(authorizationCode) ⇒ Given an authorization code, request an access token and associated information from the login service.
Returns an object with the following properties:
- accessToken
- refreshToken
- username (optional, if "endpoint" is provided by client API response)
- expirationTime (in seconds)
Kind: instance method of OAuthClient
Returns: Promise.<Object>
- access token information
Param | Type | Description |
---|---|---|
authorizationCode | string |
an OAuth2 authorization code |
CancelableRequest.<Response.<unknown>>
oAuthClient.postRequest(params) ⇒ Make an HTTP POST request to the login service
Kind: instance method of OAuthClient
Returns: CancelableRequest.<Response.<unknown>>
- The return of the POST call
Param | Type | Description |
---|---|---|
params | Object |
|
params.path | string |
the URL for the request |
params.form | Object |
the body of the POST request |
[params.headers] | Object |
Optional request headers |
CancelableRequest.<Response.<unknown>>
oAuthClient.getRequest(params) ⇒ Make an HTTP GET request to the login service
Kind: instance method of OAuthClient
Returns: CancelableRequest.<Response.<unknown>>
- The return of the GET call
Param | Type | Description |
---|---|---|
params | Object |
|
params.path | string |
the URL for the request |
params.token | string |
Auth bearer token for request |
[params.headers] | Object |
Optional request headers |
[params.searchParams] | Object |
Optional search parameters |
Promise.<Object>
oAuthClient.refreshAccessToken(refreshToken) ⇒ Given a refresh token, request an access token and associated information from the login service.
Returns an object with the following properties:
- accessToken
- refreshToken
- username (optional, if "endpoint" is provided by client API response)
- expirationTime (in seconds)
Kind: instance method of OAuthClient
Returns: Promise.<Object>
- access token information
Param | Type | Description |
---|---|---|
refreshToken | string |
an OAuth2 refresh token |
About Cumulus
Cumulus is a cloud-based data ingest, archive, distribution and management prototype for NASA's future Earth science data streams.
Contributing
To make a contribution, please see our contributing guidelines.
Generated automatically using npm run build-docs