/okta-oidc-js

okta-oidc-js

Primary LanguageJavaScriptOtherNOASSERTION

okta-oidc-js

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

build status

Table of Contents

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 npm version Standard pattern for validating configuration passed into Okta JavaScript libraries and SDKs.
jwt-verifier npm version Easily verify JWTs from Okta
okta-angular npm version Angular support for Okta
oidc-middleware npm version Middleware to easily add OpenID Connect to the Node.js framework of your choice
okta-react npm version React support for Okta
okta-react-native npm version React Native support for Okta
okta-vue npm version 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.