@byu-oit/okta v1.0.0

Okta NodeJS

A tool for interacting with Okta using JavaScript in either NodeJS or the browser.

• Examples
  • API Development with OpenAPI Enforcer
  • API Development with Express
  • Validate Access Token
  • Validate that Claims Have a Specific Value
• API
  • OktaClient
  • OktaVerifier
• Debug

Examples

API Development with OpenAPI Enforcer

const express = require('express')
const { OktaVerifier, OktaVerifierError } = require('@byu-oit/okta')
const Enforcer = require('openapi-enforcer')
const EnforcerMiddleware = require('openapi-enforcer-middleware')

const verifier = new OktaVerifier({
  issuer: 'https://some-issuer.com', // the accepted issuer
  aud: ['https://audience.com'], // an array of accepted audiences
  clientId: ['client-id-1', 'client-id-2'] // an array of accepted clients
})

const app = express()

// initialize enforcer middleware
const enforcer = EnforcerMiddleware(Enforcer('./openapi.yml'))
app.use(enforcer.init())

// all routes must have these claims (use of an empty array is allowed) 
app.use(verifier.verifyAuthorizationHeader(['claim-1', 'claim-2']))

// add enforcer route handlers
app.use(enforcer.route({
  persons: {
    getPerson (req, res) {
      // check if a claim is set to a specific value
      if (req.jwt.claims['claim-3'] === true) {
        res.send('You have access')
      } else {
        res.enforcer.status(403).send('Forbidden')
      }
    },
    
    updatePerson (req, res) {
      // check if multiple claims exist
      const error = verifier.verifyJwtClaims(req.jwt, ['claim-3', 'claim-4'])
      if (error === null) {
        res.send('You have access')
      } else {
        res.enforcer.status(403).send('Forbidden')
      }
    }
  }
}))

// handle authorization errors
app.use((err, req, res, next) => {
  if (err instanceof OktaVerifierError) {
    // choose how to handle the error
    res.status(err.statusCode).send(err.message)
  } else {
    next(err)
  }
})

API Development with Express

const express = require('express')
const { OktaVerifier, OktaVerifierError } = require('@byu-oit/okta')

const verifier = new OktaVerifier({
  issuer: 'https://some-issuer.com', // the accepted issuer
  aud: ['https://audience.com'], // an array of accepted audiences
  clientId: ['client-id-1', 'client-id-2'] // an array of accepted clients
})

const app = express()

// all routes must have these claims
app.use(verifier.verifyAuthorizationHeader(['claim-1', 'claim-2']))

// route specific claims applying to anything under /persons
app.use('/persons', verifier.verifyAuthorizationHeader(['claim-3']))

// route specific claims appling to GET /persons
app.get('/persons', verifier.verifyAuthorizationHeader(['claim-3']), (req, res) => {
  // check if a claim is set to a specific value
  if (req.jwt.claims['claim-3'] === true) {
    res.send('You have access')
  } else {
    res.status(403).send('Forbidden')
  }
})

// handle authorization errors
app.use((err, req, res, next) => {
  if (err instanceof OktaVerifierError) {
    // choose how to handle the error
    res.status(err.statusCode).send(err.message)
  } else {
    next(err)
  }
})

Validate an Access Token

const { OktaVerifier, OktaVerifierError } = require('@byu-oit/okta')

const verifier = new OktaVerifier({
  issuer: 'https://some-issuer.com', // the accepted issuer
  aud: ['https://audience.com'], // an array of accepted audiences
  clientId: ['client-id-1', 'client-id-2'] // an array of accepted clients
})

// adding claim checks here is optional and will ensure that the JWT also has the listed claims
const requiredClaims = ['claim-1']
verifier.verifyAccessToken('some-access-token-value', requiredClaims)
  .then(([ error, jwt ]) => {
    if (error) {
      console.log(error)
    } else {
      console.log(jwt)
    }
  })

Validate that Claims Have a Specific Value

const { OktaVerifier } = require('@byu-oit/okta')

const verifier = new OktaVerifier({
  issuer: 'https://some-issuer.com', // the accepted issuer
  aud: ['https://audience.com'], // an array of accepted audiences
  clientId: ['client-id-1', 'client-id-2'] // an array of accepted clients
})

// adding claim checks here is optional and will ensure that the JWT also has the listed claims
const requiredClaims = {
  'claim-1': 'confirm' // claim-1 must have value 'confirmed'
}
verifier.verifyAccessToken('some-access-token-value', requiredClaims)
  .then(([ error, jwt ]) => {
    if (error) {
      console.log(error)
    } else {
      console.log(jwt)
    }
  })

API

Exported Types:

• Jwt
• OktaToken
• OktaVerifierConfiguration
• OktaVerifierRequiredClaims
• OktaVerifierResult
• WellKnown

Exported Functions:

• axios
• base64Decode
• decodeJwt
• getWellKnown
• OktaClient
• OktaVerifier
• OktaVerifierError

OktaClient

Constructor

new OktaClient (wellKnowUrl: string, clientId?: string, clientSecret?: string)

Instance Functions

getClientGrantToken (scope?: string): Promise<OktaToken>

getWellKnown (): Promise<WellKnown>

OktaVerifier

new OktaVerifier (configuration: OktaVerifierConfiguration)

Instance Functions

middleware (requiredClaims?: OktaVerifierRequiredClaims): (req, res, next) => void

verifyAccessToken (accessToken: string, requiredClaims?: OktaVerifierRequiredClaims): Promise<OktaVerifierResult>

verifyJwtClaims (jwt: Jwt, requiredClaims?: OktaVerifierRequiredClaims): null | OktaVerifierError

Debug

This library includes the debug package. Debug logs are available by using the environment variable DEBUG set to byu-okta:*.