flex-auth v2.0.0

twilio-auth

Service for authenticating requests to/from Twilio.

API

Static Properties

twilioAuthHeaderName: string

The name of the header where the Twilio signature should exist.

twilioUserHeaderName: string

The name of the header where Twilio user tokens should be stored.

constructor(accountSid: string, authToken: string)

Creates a new TwilioAuth instance that will validate requests using authToken as the secret.

Methods

async authenticateAWSRequest(event: { body?: string, path: string, headers: { name: string : string }, queryStringParameters: { name: string : string } }): Promise

Attempts to authenticate the request received by an AWS Lambda behind an ALB.

Returns a Promise that resolves to true if the request can be authenticated or false if it cannot be authenticated.

async authenticateExpressRequest(req: Request): Promise

Attempts to authenticate the request received by an Express server.

Returns a Promise that resolves to true if the request can be authenticated or false if it cannot be authenticated.

async authenticateTwilioRequest({ userToken }: { userToken?: string }): Promise

Authenticates a request to a Twilio Function from an external agent.

Note: Internal requests should be authenticated with the builtin Twilio header check. If HTTP headers are made available, this method may be updated to handle both user- and Twilio-authenticated requests.

Returns a Promise that resolves to true if the user is authenticated and false otherwise.

createToken(url: string, body?: { key: string : any }): Promise

Creates a token that can be included in the Twilio auth header.

Returns a Promise that resolves with the token that should be included in the header.

isSignatureValid(signature: string, url: string, body?: { key: string : any }): Promise

Validates the signature in a Twilio-authenticated request.

Returns a Promise that resolves to true iff the the signature is valid.

async isUserTokenValid(token: string): Promise

Checks if the user token provided is valid.

Returns a Promise that resolves to true if provided token is valid; otherwise resolves to false

async fetchUserData(token: string): Promise<{workerSid: string, roles: string[], isValid: boolean, expiration: Date, identity: string}>

Fetches the user data attached to the provided token.

Express Middleware

Building off the helper method for authenticating an Express request, we also provide middleware that you can just hook into express app.

Usage

For twilio-auth-middleware to work, the request object must have the following fields added to it:

{
  "twilio": {
    "accountSid": "string",
    "authToken": "string"
  }
}

To add this data to the request object, you might define middleware that is executed before twilio-auth-middlware that loads the required data and adds it to the request object. Your express app might look something like:

import { twilioAuthMiddleware, TwilioRequest } from 'twilio-auth';

app.use(async (req: TwilioRequest, _res: Response, next: NextFunction) => {
  req.twilio = {
    accountSid: await loadAccountSid(),
    authToken:  await loadAuthToken(),
  };

  next();
});

app.use(twilioAuthMiddleware());