@cumulus/oauth-client v18.2.1

@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.

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)

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>

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)

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

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)

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

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

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

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

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

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