@oada/oada-id-client

    1.1.3 • Public • Published

    Build Status Coverage Status Dependency Status License

    oada-id-client

    JavaScript client library for OADA identity. Can be used both in NodeJS and in the browser.

    Getting Started

    Installation

    For use in NodeJS or with something like webpack:

    yarn add OADA/oada-id-client-js

    You can also get it from a CDN in browser:

    <script src="https://unpkg.com/@oada/oada-id-client"></script>

    Browser Code Generation

    The code to use in the browser can be generated with the following command:

    $ npm run bundle

    This will create the file dist/bundle.js.

    Examples

    Connect Style "Middleware" Wrapper Usage

    Version of the library functions which wrap the core functionality for use as connect style "middleware". This can be used in a NodeJS server using a compatible web development framework, such as express.

    For a working example of using this wrapper, see the on server example.

    getIDToken(domain, options)

    Middleware for generating an ID token request against an OADA identity provider.

    Parameters

    domain string of domain with which to log in the user. The value passed to the function can be overridden by a query or form parameter with a name of domain.

    options object containing at least the following properties:

    • [metadata][] object containg client metadata, or string of a [software_statement][] JWT
    • privateKey
      • pem string or buffer containing your client's PEM encoded private RSA key
      • [kid][] string containing the key ID parameter, for finding the corresponding public key where your client is registered
    • params [Optional OpenID Connect parameters][oidparams] placed in params as string properties will be used (e.g. display, prompt, login_hint)

    Usage Example

    var options = {
      metadata: {
        /* See spec linked above */
      },
      privateKey: {
        pem: fs.readFileSync('/path/to/key.pem'),
        kid: 'key_id_corresponding_to_pem',
      },
    };
    
    app.use(
      '/getIdToken',
      oadaIdClient.getIDToken('some.oada-identity-provider.com', options)
    );

    getAccessToken(domain, options)

    Middleware for generating an access token request against an OADA compliant API.

    Parameters

    domain string of domain from which to get an OADA API access token. The value passed to the function can be overridden by a query or form parameter with a name of domain.

    options object containing at least the following properties:

    • [metadata][] object containg client metadata, or string of a [software_statement][] JWT
    • privateKey
      • pem string or buffer containing your client's PEM encoded private RSA key
      • [kid][] string containing the key ID parameter, for finding the corresponding public key where your client is registered
    • [scope][] space separated string of OAuth scopes for the request access token to have.
    • params [Optional OpenID Connect parameters][oidparams] placed in params as string properties will be used (e.g. display, prompt, login_hint)

    Usage Example

    var options = {
      metadata: {
        /* See spec linked above */
      },
      privateKey: {
        pem: fs.readFileSync('/path/to/key.pem'),
        kid: 'key_id_corresponding_to_pem',
      },
      scope: 'some.oada.defined.scope',
    };
    
    app.use(
      '/getAccessToken',
      oadaIdClient.getAccessToken('some.oada-cloud-provider.com', options)
    );

    handleRedirect()

    Middleware for handling redirects from getIDToken or getAccessToken middlewares. In most case you will apply this middleware in two locations, one to receive getIDToken redirects and another to receive getAccessToken redirects.

    Usage Example

    // Handle ID token redirects
    app.use(
      '/url/referenced/by/getIDToken/redirect_uri',
      oadaIdClient.handleRedirect()
    );
    app.use(
      '/url/referenced/by/getIDToken/redirect_uri',
      function (req, res, next) {
        // ID token is in req.token
        console.dir(req.token);
      }
    );
    
    // Handle access token redirects
    app.use(
      '/url/referenced/by/getAccessToken/redirect_uri',
      oadaIdClient.handleRedirect()
    );
    app.use(
      '/url/referenced/by/getAccessToken/redirect_uri',
      function (req, res, next) {
        // Access token is in req.token
        console.dir(req.token);
      }
    );

    Browser Wrapper Usage

    Version of the library functions which wrap the core functionality for easy use in the browser.

    For a working example of using this wrapper, see the in browser example.

    getIDToken(domain, options, callback)

    Asynchronous function for generating an ID token request against an OADA identity provider.

    Parameters

    domain string of domain with which to log in the user.

    options object containing at least the following properties:

    • [metadata][] object containg client metadata, or string of a [software_statement][] JWT
    • params [Optional OpenID Connect parameters][oidparams] placed in params as string properties will be used (e.g. display, prompt, login_hint)

    [Optional OpenID Connect parameters][oidparams] placed in options as string properties will be used (e.g. display, prompt, login_hint).

    callback function of the form function(err, idToken).

    Usage Example

    var options = {
      metadata: {
        /* See spec linked above */
      },
    };
    
    var domain; // Set domain based on text box, dropdown, etc.
    
    oadaIdClient.getIDToken(domain, options, function (err, idToken) {
      if (err) {
        return console.dir(err);
      } // Soemthing went wrong
    
      console.dir(idToken);
    });

    getAccessToken(domain, options, callback)

    Asynchronous function for generating an access token request against an OADA compliant API.

    Parameters

    domain string of domain from which to get an OADA API access token. The value passed to the function can be overridden by a query or form parameter with a name of domain.

    options object containing at least the following properties:

    • [metadata][] object containg client metadata, or string of a [software_statement][] JWT
    • [scope][] space separated string of OAuth scopes for the request access token to have.
    • params [Optional OpenID Connect parameters][oidparams] placed in params as string properties will be used (e.g. display, prompt, login_hint)

    callback function of the form function(err, accessToken).

    Usage Example

    var options = {
      metadata: {
        /* See spec linked above */
      },
      scope: 'some.oada.defined.scope',
    };
    
    var domain; // Set domain based on text box, dropdown, etc.
    
    oadaIdClient.getAccessToken(domain, options, function (err, accessToken) {
      if (err) {
        return console.dir(err);
      } // Soemthing went wrong
    
      console.dir(accessToken);
    });

    handleRedirect()

    Function for handling redirects generated by getIDToken or getAccessToken function. Simply needs to be called by the page served from the URL corresponding to [redirect_uri][].

    Usage Example

    <!-- Page served at redirect_uri for getIDToken and/or getAccessToken -->
    <html>
      <head>
        <script src="path/to/library/browser/code.js"></script>
        <script>
          oadaIdClient.handleRedirect();
        </script>
      </head>
    </html>

    Base Library Usage

    Not yet documented.

    References

    1. OpenID Connect Core 1.0 [oidparams]: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest "OpenID Connect Core 1.0 Section 3.1.2.1"
    2. OAuth 2.0 Authorization Framework [client_id]: http://tools.ietf.org/html/rfc6749#section-2.2 "RFC6794 Section 2.2" [redirect_uri]: http://tools.ietf.org/html/rfc6749#section-3.1.2 "RFC6794 Section 3.1.2" [scope]: http://tools.ietf.org/html/rfc6749#section-3.3 "RFC6794 Section 3.3"
    3. JSON Web Key (JWK) Draft 31 [kid]: https://tools.ietf.org/html/draft-ietf-jose-json-web-key-31#section-4.5 "JWK Section 4.5"
    4. OAuth 2.0 Dynamic Client Registration Protocol [metadata]: https://tools.ietf.org/html/draft-ietf-oauth-dyn-reg#section-2 "oauth-dyn-reg Section 2" [software_statement]: https://tools.ietf.org/html/draft-ietf-oauth-dyn-reg#section-2.3 "oauth-dyn-reg Section 2.3"

    Install

    npm i @oada/oada-id-client

    DownloadsWeekly Downloads

    2

    Version

    1.1.3

    License

    Apache-2.0

    Unpacked Size

    2.36 MB

    Total Files

    19

    Last publish

    Collaborators

    • sanoel
    • serviopalacios
    • aultac
    • awlayton
    • oadao
    • tarakawa
    • cyrusbowman
    • abalmos