byu-wabs-oauth v4.0.7

byu-wabs-oauth

Manage OAuth client grant and auth code grant access tokens for BYU's implementation of WSO2.

Table of Contents

• Installation
• Examples
  • Client Grant Token
  • Code Grant Token
• Create a BYU OAuth object
• BYU OAuth Object
  • getAuthorizationUrl
  • getClientGrantToken
  • getAuthCodeGrantToken
  • refreshToken
  • revokeToken
• BYU OAuth Token
• Testing

Installation

$ npm install byu-wabs-oauth

Examples

Client Grant Token

Use this grant type for communicating from one server to another where a specific user’s permission to access data is not required.

const byuOAuth = require('byu-wabs-oauth')

;(async function () {
  const oauth = await byuOAuth('<client_id>', '<client_secret>')
  const token = await oauth.getClientGrantToken()
})()

Auth Code Grant Token

Use this grant type if you need the user's authorization to access data. Getting this grant type is a two step process.

1. Direct the user to the authorization URL
2. Get the token using the authorization code that comes in a follow up request

const byuOAuth = require('byu-wabs-oauth')
const querystring = require('querystring')
const redirectUrl = 'http://localhost:3000/'

// start a server that will listen for the OAuth code grant redirect
const server = http.createServer(async (req, res) => {
  const oauth = await byuOAuth('<client_id>', '<client_secret>')
  const qs = querystring.parse(req.url.split('?')[1] || '')

  // if there is no code then redirect browser to authorization url
  if (!qs.code) {
    const url = await oauth.getAuthorizationUrl(redirectUrl)
    res.setHeader('Location', url)
    res.end()

    // if there is a code then use the code to get the code grant token
  } else {
    const token = await oauth.getCodeGrantToken(qs.code, redirectUrl)
    res.write(token.accessToken)
    res.end()
  }
});

const listener = server.listen(3000)

Create a BYU OAuth object

byuWabsOAuth (clientId: string, clientSecret: string, options: ByuJWT.Options) : Promise<ByuOAuth>

Parameters

Returns a Promise that resolves to an object with the following methods and properties:

Methods:

• getAuthorizationUrl - Get the URL that will provide an OAuth code grant code.
• getClientGrantToken - Get a client grant token. Use this grant type for communicating from one server to another where a specific user’s permission to access data is not required.
• getAuthCodeGrantToken - Get a code grant token. Use this grant type if you need the user's authorization to access data.
• refreshToken - Use a refresh token to get a new token object.
• revokeToken - Use to revoke an access token and / or refresh token.

Properties:

• authorizationEndpoint
• idTokenSigningAlgorithmValuesSupported
• issuer
• jwksUri
• responseTypesSupported
• revocationEndpoint
• scopesSupported
• subjectTypesSupported
• tokenEndpoint
• userInfoEndpoint

Example

const byuOAuth = require('byu-wabs-oauth')
const oauth = await byuOauth('<client_id>', '<client_secret>')

getAuthorizationUrl

getAuthorizationUrl ( redirectUri: string [, state: string ] ): Promise<string>

Get the URL that needs to be visited to acquire an auth code grant code.

Parameters

Returns a Promise that resolves to the URL.

Example

;(async () => {
  const byuOAuth = require('byu-wabs-oauth')
  const oauth = await byuOauth('<client_id>', '<client_secret>')

  const url = await oauth.getAuthorizationUrl('https://my-server.com', 'state info')
})()

getClientGrantToken

getClientGrantToken (): Promise<Token>

Get a client grant token.

Parameters

None

Returns a Promise that resolves to a token.

Example

;(async () => {
  const byuOAuth = require('byu-wabs-oauth')
  const oauth = await byuOauth('<client_id>', '<client_secret>')

  const token = await oauth.getClientGrantToken()
})()

getAuthCodeGrantToken

getAuthCodeGrantToken ( code: string, redirectUri: string): Promise<Token>

Get a code grant token.

Parameters

Returns a Promise that resolves to a token.

Example

See the Code Grant Token example.

refreshToken

refreshToken ( refreshToken: string ): Promise<Token>

Get a new access token using a refresh token.

Parameters

Returns a Promise that resolves to a token.

Example

;(async () => {
  const byuOAuth = require('byu-wabs-oauth')
  const oauth = await byuOauth('<client_id>', '<client_secret>')

  const token = await oauth.refreshToken('<access_token>', '<refresh_token>')
})()

revokeToken

revokeToken ( accessToken: string [, refreshToken: string ] ): Promise<void>

Revoke an access token and / or a refresh token.

Parameters

Returns a Promise that resolves to undefined.

Example

;(async () => {
  const byuOAuth = require('byu-wabs-oauth')
  const oauth = await byuOauth('<client_id>', '<client_secret>')
  await oauth.revokeToken('<access_token>', '<refresh_token>')
})()

BYU OAuth Token

This object has information about the current token as well as methods for managing the token. These are the properties:

• accessToken - A string that has the most recent access token. This value will be undefined if the token has been revoked.
• expiresAt - A Date object that represents when the token will expire.
• expiresIn - The number of milliseconds until the token expires.
• refreshToken - A string representing the refresh token. This value will be undefined for client grant tokens, although client grant tokens can still be refreshed using the refresh function on this object.
• resourceOwner - Only valid for code grant tokens, this object contains the resource owner's properties:
  • atHash: string
  • aud: Array
  • authTime: number
  • azp: string
  • byuId: string
  • exp: number
  • iat: number
  • iss: string
  • jwt: string
  • netId: string
  • personId: string
  • preferredFirstName: string
  • prefix: string
  • restOfName: string
  • sortName: string
  • sub: string
  • suffix: string
  • surname: string
  • surnamePosition: string
• scope - A string representing the scopes associated with this token.
• type - A string of the token type.

Testing

Run the tests

1. In the terminal, log into the BYU DevX AWS Account

   aws sso login --profile byu-oit-devx-prd

2. In this root of this project, run:

   npm install
   npm test

Update environment variables used in the tests

1. Create the file ./iac/vars.tfvars.

2. Copy this template into that file.

   consumer_key  = ""
   consumer_secret = ""
   callback_url    = ""
   net_id          = ""
   password        = ""

3. Copy and paste the values from the parameter store into this file.

4. Update the values you want to change.

5. Set the AWS_PROFILE environment variable.

   export AWS_PROFILE=byu-oit-devx-prd

6. Login to the BYU DevX AWS Account.

   aws sso login --profile $AWS_PROFILE

7. From within the ./iac directory, apply the changes in Terraform.

Ensure you use same version of terraform (as of right now v1.2.2 is latest).

terraform init
terraform apply --var-file vars.tfvars