@byu-oit-sdk/credential-provider

A Credential Provider is a class that exposes a getAccessToken function. It is configured according to an OpenId Configuration.

Supported providers:

• Client Credentials
• Authorization Code
• Api Key
• Chained Credential

Note that any of the credential providers will attempt load configuration options from environment variables with the BYU_OIT_ prefix if they are not passed in the constructor.

For example, process.env.BYU_OIT_CLIENT_ID and process.env.BYU_OIT_CLIENT_SECRET can be set instead of passing clientId and clientSecret into the options object for the ClientCredentialsProvider.

Client Credentials Provider

The ClientCredentialsProvider facilitates fetching an access token using the client credentials grant type.

import {ClientCredentialsProvider} from '@byu-oit-sdk/credential-provider'

const provider = new ClientCredentialsProvider({
    clientId: 'super-id',
    clientSecret: 'super-secret',
    discoveryEndpoint: 'https://api.byu.edu/.well-known/openid-configuration',
    scope: 'my-scope', // Optional
    type: 'Basic ' // Optional
})

const token = await provider.getAccessToken()

Like the OpenIdConfiguration class, there is a from constructor for validating unknown input.

import {ClientCredentialsProvider} from '@byu-oit-sdk/credential-provider'
import {join} from 'node:fs'
import {readFileSync} from 'node:path'

const config = readFileSync(join(__dirname, './config.json'))
const provider = ClientCredentialsProvider.from(config)

You may also load your configuration from environment variables. This can be done on any credential provider except the abstract or base classes (i.e. CredentialProvider, TokenProvider, OauthCredentialProvider).

import {ClientCredentialsProvider} from '@byu-oit-sdk/credential-provider'
const provider = ClientCredentialsProvider.fromEnv() // defaults to 'BYU_OIT_' prefix

Optionally, you can pass in a prefix to use instead of the default BYU_OIT_ prefix.

import {ClientCredentialsProvider} from '@byu-oit-sdk/credential-provider'

const provider = ClientCredentialsProvider.fromEnv('MY_PREFIX_')

Authorization Code Provider

The AuthorizationCodeProvider facilitates fetching an access token using the authorization code grant type. The Authorization Code grant type requires a code exchange to get the token. You must implement the flow to get the code and exchange it for a token. To help implement the flow, the AuthorizationCodeProvider also exposes a few functions for each step.

1. Instantiate the provider.

   import {AuthorizationCodeProvider} from '@byu-oit-sdk/credential-provider'
      
   const provider = new AuthorizationCodeProvider({
       clientId: 'super-id',
       clientSecret: 'super-secret', // OPTIONAL
       redirectUri: 'http://localhost:8080/callback',
       discoveryEndpoint: 'https://api.byu.edu/.well-known/openid-configuration'
   })

2. Redirect a caller to the authorization endpoint formatted by the provider. Optionally pass generate and pass in a code verifier for Proof Key Code Exchange (PKCE). The generator accepts a length parameter and will generate a code of that length. The default length is 32. The state can also be used to pass along the state of the app before the redirect occurred. The state will be checked for sameness in the next step of the authorization flow.

   import {generateCodeVerifier} from '@byu-oit-sdk/credential-provider'
     
   const state = 'some_state'
   const codeVerifier = generateCodeVerifier(48)
   const uri = provider.getAuthorizationUri({ codeVerifier, state })

3. Handle the OAuth callback to your application and extract the authorization code from the url. If no state is provided in the previous step but the authorization issuer provides one, it must be ignored. Otherwise, an error will be thrown.

   const authCode = provider.getAuthCodeFromRedirect(urlFromRedirect, state)

4. Exchange the code for an access token. If you're using Proof Key Code Exchange (PKCE), you must pass in the code verifier.

   const token = provider.getTokenFromAuthCode(authCode, codeVerifier)

API Key Provider

The ApiKeyProvider facilitates fetching resources using API Key authentication. We do not recommend using this credential provider but realize that some authorization servers only support this authorization scheme.

import {ApiKeyProvider} from '@byu-oit-sdk/credential-provider'

const provider = new ApiKeyProvider({
    apiKey: 'my-api-key'
})

const apiKey = await provider.getAccessToken()

Chained Credential Provider

The ChainedCredentialProvider is a function (not a constructor) that facilitates the automatic instantiation of one of credential providers from environment variables with the BYU_OIT_ prefix. The first provider to successfully instantiate is the provider returned. The order of the provider instantiation is based on which provider is anticipated to be most used:

1. Client Credential Provider
2. Authorization Code Provider
3. ApiKey Provider Provider

OpenId Configuration

An OpenIdConfiguration object may be loaded from a remote location by passing a URI into the load constructor.

import {OpenIdConfiguration} from "@byu-oit-sdk/credential-provider";

const openId = await OpenIdConfiguration.load('https://api.byu.edu/.well-known/openid-configuration')

It may also be configured synchronously from a JSON file with the constructor. It is recommended that you use the from constructor which will validate the input to ensure correctness.

import {OpenIdConfiguration} from '@byu-oit-sdk/credential-provider'
import config from './openid-configuration.json'

const openId = OpenIdConfiguration.from(config)