@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.
Kind: global class

cognitoClient.getUserInfo(params) ⇒ Promise.<Object>

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)](#EarthdataLoginClient+getUserInfo) ⇒ <code>Promise.<Object></code>
* [.getTokenUsername(params)](#EarthdataLoginClient+getTokenUsername) ⇒ <code>Promise.<string></code>

earthdataLoginClient.getUserInfo(params) ⇒ Promise.<Object>

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
}

earthdataLoginClient.getTokenUsername(params) ⇒ Promise.<string>

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)](#new_OAuthClient_new)
* [.getAuthorizationUrl([state])](#OAuthClient+getAuthorizationUrl) ⇒ <code>string</code>
* [.getAccessToken(authorizationCode)](#OAuthClient+getAccessToken) ⇒ <code>Promise.<Object></code>
* [.postRequest(params)](#OAuthClient+postRequest) ⇒ <code>CancelableRequest.<Response.<unknown>></code>
* [.getRequest(params)](#OAuthClient+getRequest) ⇒ <code>CancelableRequest.<Response.<unknown>></code>
* [.refreshAccessToken(refreshToken)](#OAuthClient+refreshAccessToken) ⇒ <code>Promise.<Object></code>

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'
});

oAuthClient.getAuthorizationUrl(state) ⇒ string

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 |

oAuthClient.getAccessToken(authorizationCode) ⇒ Promise.<Object>

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 |

oAuthClient.postRequest(params) ⇒ CancelableRequest.<Response.<unknown>>

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 |

oAuthClient.getRequest(params) ⇒ CancelableRequest.<Response.<unknown>>

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 |

oAuthClient.refreshAccessToken(refreshToken) ⇒ Promise.<Object>

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.
Cumulus Documentation

Contributing

To make a contribution, please see our contributing guidelines.

---

Generated automatically using npm run build-docs