@oada/id-client

@oada/id-client

TypeScript/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/id-client

Browser Code Generation

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

yarn bundle

This will create the file bundle.js.

Examples

• On Server Example
• In Browser Example

High-Level Node.JS wrapper Usage

This version of the library wraps the core functionality for easy use in typical Node.JS uses.

It will pop up a window using the default browser to take the user through the needed flows and the return the resulting token(s).

getIDToken(domain, options)

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 containing client metadata, or string of a software_statement JWT
• privateKey a private JWK for use in the JWT bearer client auth (required for code flow)
• params Optional OpenID Connect parameters placed in params as string properties will be used (e.g. display, prompt, login_hint)

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

Usage Example

const options = {
  metadata: {
    /* See spec linked above */
  },
};

const domain = /* Set domain based on text box, dropdown, etc. */;

// Promise will resolve after user completes the flow in the browser
const idToken = await oadaIdClient.getIDToken(domain, options);
console.dir(idToken);

getAccessToken(domain, options)

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 containing client metadata, or string of a software_statement JWT
• scope space separated string of OAuth scopes for the request access token to have.
• privateKey a private JWK for use in the JWT bearer client auth (required for code flow)
• params Optional OpenID Connect parameters placed in params as string properties will be used (e.g. display, prompt, login_hint)

Usage Example

const options = {
  metadata: {
    /* See spec linked above */
  },
  scope: 'some.oada.defined.scope',
};

const domain = /* Set domain based on text box, dropdown, etc. */;

// Promise will resolve after user completes the flow in the browser
const accessToken = await oadaIdClient.getAccessToken(domain, options);
console.dir(accessToken);

Connect Style "Middleware" Wrapper Usage

This version of the library wraps the core functionality for use as connect style "middleware". This can be used in a Node.JS 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 containing client metadata, or string of a software_statement JWT
• privateKey a private JWK for use in the JWT bearer client auth (required for code flow)
• params Optional OpenID Connect parameters placed in params as string properties will be used (e.g. display, prompt, login_hint)

Usage Example

const 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 containing client metadata, or string of a software_statement JWT
• privateKey a private JWK for use in the JWT bearer client auth (required for code flow)
• scope space separated string of OAuth scopes for the request access token to have.
• params Optional OpenID Connect parameters placed in params as string properties will be used (e.g. display, prompt, login_hint)

Usage Example

const 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 cases, 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

This version of the library wraps 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)

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 containing client metadata, or string of a software_statement JWT
• params Optional OpenID Connect parameters placed in params as string properties will be used (e.g. display, prompt, login_hint)

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

Usage Example

const options = {
  metadata: {
    /* See spec linked above */
  },
};

const domain = /* Set domain based on text box, dropdown, etc. */;

const idToken = await oadaIdClient.getIDToken(domain, options);
console.dir(idToken);

getAccessToken(domain, options)

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 containing 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 placed in params as string properties will be used (e.g. display, prompt, login_hint)

Usage Example

const options = {
  metadata: {
    /* See spec linked above */
  },
  scope: 'some.oada.defined.scope',
};

const domain = /* Set domain based on text box, dropdown, etc. */;

const accessToken = await oadaIdClient.getAccessToken(domain, options);
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

• OpenID Connect Core 1.0
• OAuth 2.0 Authorization Framework
• JSON Web Key (JWK) Draft 31
• OAuth 2.0 Dynamic Client Registration Protocol