Nearly Perfect Mediocracy

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

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

    Keywords

    Install

    npm i @cumulus/oauth-client

    DownloadsWeekly Downloads

    166

    Version

    13.4.0

    License

    Apache-2.0

    Unpacked Size

    50.5 kB

    Total Files

    17

    Last publish

    Collaborators

    • botanical
    • aortega527
    • cumuluspublisher
    • mboyd
    • lfrederick
    • kkelly51
    • nsidc_kovarik
    • flamingbear
    • jennyhliu
    • npauzenga
    • dopeters