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:
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:
; app.use; app.usetwilioAuthMiddleware;