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.

| Property | Type | Description | |----------|------|-------------| | accountSid | string | The SID of the Twilio account. | | authToken | string | The secret that should be used to sign requests. |

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.

| Property | Type | Description | |----------|------|-------------| | event | any | The event object passed to the AWS Lambda |

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.

| Property | Type | Description | |----------|------|-------------| | req | express.Request | The Express Request object |

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.

| Property | Type | Description | |----------|------|-------------| | event | { userToken: string } | The Twilio event object passed to the Function |

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.

| Property | Type | Description | |----------|------|-------------| | url | string | The full URL of the requested resource | | body | { [ key: string ]: any } | If the request has a body, the body of the request |

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.

| Property | Type | Description | |----------|------|-------------| | signature | string | The signature provided in the Twilio auth header | | url | string | The full URL of the requested resource | | body | { [ key: string ]: any } | If the request has a body, the body of the request |

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

| Property | Type | Description | |----------|------|-------------| | token | string | The user auth token generated by Twilio |

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

Fetches the user data attached to the provided token.

| Property | Type | Description | |----------|------|-------------| | token | string | The user auth token generated by Twilio |

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());