Skip to content

Convenience library to handle oauth requests specific to BYU's well-known configuration data

License

Notifications You must be signed in to change notification settings

byu-oit/byu-wabs-oauth

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

byu-wabs-oauth

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

Table of Contents

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
  1. 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        = ""
  1. Copy and paste the values from the parameter store into this file.
  2. Update the values you want to change.
  3. Set the AWS_PROFILE environment variable.
export AWS_PROFILE=byu-oit-devx-prd
  1. Login to the BYU DevX AWS Account.
aws sso login --profile $AWS_PROFILE
  1. 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

About

Convenience library to handle oauth requests specific to BYU's well-known configuration data

Resources

License

Stars

Watchers

Forks

Packages

No packages published