kdstew/okta-oidc-js

okta-oidc-js

okta-oidc-js

This is a monorepo that contains Okta's OpenID Connect JavaScript resources.

Table of Contents

• Getting Started
• Packages
  • Monorepo
  • Versioning
  • Public packages
• Configuration Reference
• Testing
  • Prerequisites
    • Create a SPA
    • Create a Web App
  • Test an individual package
  • Test all packages
• Contributing

Getting Started

We use Yarn as our node package manager. To install Yarn, check out their install documentation.

# Clone the repo and navigate to it
git clone git@github.com:okta/okta-oidc-js.git
cd okta-oidc-js

# Install dependencies
yarn install

Packages

Monorepo

The okta-oidc-js repo is managed as a monorepo using Yarn Workspaces for managing dependencies and Lerna for everything else. You can think of each package as a separate npm module - each must list out its own dependencies, have its own package name, and be versioned.

Packages are parsed from the workspaces property in package.json, and adhere to this structure:

packages/
  configuration-validation
  jwt-verifier
  oidc-middleware
  okta-angular
  okta-react
  okta-react-native
  okta-vue

Versioning

We've configured Lerna with independent mode, which means that each package is required to manage its own version number.

Public packages

Package	Status	Description
configuration-validation		Standard pattern for validating configuration passed into Okta JavaScript libraries and SDKs.
jwt-verifier		Easily verify JWTs from Okta
okta-angular		Angular support for Okta
oidc-middleware		Middleware to easily add OpenID Connect to the Node.js framework of your choice
okta-react		React support for Okta
okta-react-native		React Native support for Okta
okta-vue		Vue.js support for Okta

Configuration Reference

Each package is configured to look for environment variables based on the application type.

# Navigate into a specific package
cd packages/${packageName}

# Set the following environment variables
#
# ISSUER        - your authorization server
# CLIENT_ID     - the client ID of your app
# CLIENT_SECRET - the client secret of your app, required for the oidc-middleware package
# USERNAME      - username of app user, required for tests
# PASSWORD      - password of app user, required for tests
export ISSUER=https://{yourOktaDomain}/oauth2/default
...

Testing

Since the workspace contains libraries for Single-Page and Web Applications, you will need to have created a SPA and Web App in your Okta org.

Prerequisites

Create a SPA

1. Applications > Add Application
2. Select SPA
3. Add the following login redirect URI:
   • http://localhost:8080/implicit/callback
   • http://localhost:3000/implicit/callback
4. Click Done
5. Users > Add Person
6. Create and activate user

Create a Web App

1. Applications > Add Application
2. Select Web
3. Add the following login redirect URI:
   • http://localhost:8080/authorization-code/callback
4. Click Done
5. Users > Add Person
6. Create and activate user

Test an individual package

# Navigate into a specific package
cd packages/${packageName}

# Run the test suite
yarn test

Test all packages

Define the following environment variables at the project root and run the tests:

# Perform exports at the root of the repository
[okta-oidc-js]$ export ISSUER=https://{yourOktaDomain}/oauth2/default
[okta-oidc-js]$ export SPA_CLIENT_ID={SPAClientID}
[okta-oidc-js]$ export WEB_CLIENT_ID={webAppClientID}
[okta-oidc-js]$ export CLIENT_SECRET={webAppClientSecret}
[okta-oidc-js]$ export USERNAME={username}
[okta-oidc-js]$ export PASSWORD={password}

# Run all tests
[okta-oidc-js]$ yarn test

Contributing

We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.