@cumulus/oauth-client
TypeScript icon, indicating that this package has built-in type declarations

18.2.0 • Public • Published

@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) ⇒ 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

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

Readme

Keywords

Package Sidebar

Install

npm i @cumulus/oauth-client

Weekly Downloads

86

Version

18.2.0

License

Apache-2.0

Unpacked Size

50.6 kB

Total Files

17

Last publish

Collaborators

  • cumuluspublisher
  • nsidc_kovarik
  • jennyhliu
  • npauzenga