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

| Parameter | Type | Required | Description | |------------------|------------------|----------|------------------------------------------------------------------------------------------------------------------------------| | clientId | string | Yes | The client ID or consumer key | | clientSecret | string | Yes | The client secret or consumer secret | | options | ByuJWT.Options | No | The ByuJWT Options |

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

| Parameter | Type | Required | Description | |-----------------|----------|----------|------------------------------------------------------------------------------------------------------------| | redirectUri | string | Yes | The URL that the API manager will redirect to after the user has authorized the application. | | state | string | No | State information to add to the URL. You can read this state information when the redirectUri is called. |

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

| Parameter | Type | Required | Description | |-----------------|----------|----------|---------------------------------------------------------------------------------------------------| | code | string | Yes | The code grant code that signifies authorization | | redirectUri | string | Yes | The original URI specified when calling the getAuthorizationUrl function. |

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

| Parameter | Type | Required | Description | |------------------|----------|-----------|-------------------------------| | accessToken | string | Yes | The access token to refresh. | | refreshToken | string | Yes | The associated refresh token. |

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

| Parameter | Type | Required | Default | Description | |-----------------|----------|----------|---------|----------------------------------------------| | accessToken | string | Yes | N/A | The access token to revoke. | | refreshToken | string | No | N/A | The associated refresh token to also revoke. |

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