No commit activity in last 3 years
No release in over 3 years
This gem is designed to work with Sinatra applications that serve as back-ends for Amazon Alexa skills.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.16
~> 10.0
~> 3.0
~> 0.15
~> 0.9
~> 3.0
~> 3.0
 Project Readme

Alexa Request Verifier

AlexaRequestVerifier is a gem created to verify that requests received within a Rack-based application originate from Amazon's Alexa API.

This gem is framework agnostic and should work with any Rack based application including both Rails and Sinatra.

Gem Version Build Status Code Coverage License

Contents

  • Requirements
  • Installation
  • Usage
    • Methods
    • Disabling checks
      • Examples
        • Globally
        • Instance level
          • With a block
          • Calling #configure
    • Handling errors
  • Getting Started with Development
    • Running the tests
  • Contributing
  • License
  • Code of Conduct

Requirements

AlexaRequestVerifier requires the following:

  • Ruby - version 2.0 or greater

Installation

Add this line to your application's Gemfile:

gem 'alexa_request_verifier'

Usage

This gem's main function is taking an Rack request and verifying that it was sent by Amazon.

Sinatra

# within server.rb (or equivalent)

post '/' do
  AlexaRequestVerifier.valid!(request)
end

Rails

# config/routes.rb

post '/', to: 'alexa#index'
# app/controllers/alexa_controller.rb
class AlexaController < ApplicationController
  skip_before_action :verify_authenticity_token, only: :index

  def index
    AlexaRequestVerifier.valid!(request)
  end
end

Methods

AlexaRequestVerifier has two main entry points, detailsed below:

Method Parameter type Returns
AlexaRequestVerifier.valid!(request) Rack-based request object true on successful verification. Raises an error if unsuccessful.
AlexaRequestVerifier.valid?(request) Rack-based request object true on successful verificatipn. false if unsuccessful.

You are also able to configure AlexaRequestVerifier to disable some checks. This is detailed in the section below.

Disabling checks

If you'd like to disable one (or more) of the checks performed by AlexaRequestVerifier, you can do so by passing a #configure block. Each of the configuration attributes are Boolean values and are detailed below.

It is possible to disable checks either globally, or for a specific instance. This is useful if you want to run multiple instances of the verifier within your application.

Option Default Description
enabled true Enables or disables AlexaRequestVerifier checks. This setting overrides all others i.e. setting config.enabled = false disables all checks even if you set others to true.
verify_uri true Enables or disables checks on the certificate URI. Set to false to allow serving of certificates from non-amazon approved domains.
verify_timeliness true Enables or disables timeliness checks. Set to false to allow requests generated in the past to be executed. Good for serving test requests.
verify_certificate true Enables or disabled checks on whether the certificate is in date, or contains the SAN address we expect.
verify_signature true Enables or disables checks to see if a request was actually signed by a certificate.

Examples

The below is an example of a 'complete' configure block, setting attributes both globally and for an individual instance.

Globally
AlexaRequestVerifier.configure do |config|
  config.enabled            = false # Disables all checks, even though we enable them individually below
  config.verify_uri         = true
  config.verify_timeliness  = true
  config.verify_certificate = true
  config.verify_signature   = true
end
AlexaRequestVerifier.valid!(request)
Instance level
With a block
verifier = AlexaRequestVerifier::Verifier.new do |config|
  config.enabled            = false
  config.verify_uri         = true
  config.verify_timeliness  = true
  config.verify_certificate = true
  config.verify_signature   = true
end
verifier.valid!(request)
Calling #configure
verifier = AlexaRequestVerifier::Verifier.new
verifier.configure do |config|
  config.enabled            = false
  config.verify_uri         = true
  config.verify_timeliness  = true
  config.verify_certificate = true
  config.verify_signature   = true
end
verifier.valid!(request)

Handling errors

AlexaRequestVerifier#valid! will raise one of the following expected errors if verification cannot be performed.

Please note that all errors come with (hopefully) helpful accompanying messages.

Error Description
AlexaRequestVerifier::InvalidCertificateURIError Raised when the certificate URI does not pass validation.
AlexaRequestVerifier::InvalidCertificateError Raised when the certificate itself does not pass validation e.g. out of date, does not contain the requires SAN extension, etc.
AlexaRequestVerifier::InvalidRequestError Raised when the request cannot be verified (not timely, not signed with the certificate, etc.)

Getting Started with Development

To clone the repository and set up the dependencies, run the following:

git clone https://github.com/mattrayner/alexa_request_verifier.git
cd alexa_request_verifier
bundle install

Running the tests

We use RSpec as our testing framework and tests can be run using:

bundle exec rake

Contributing

If you wish to submit a bug fix or feature, you can create a pull request and it will be merged pending a code review.

  1. Fork the repository
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Ensure your changes are tested using Rspec
  6. Create a new Pull Request

License

AlexaRequestVerifier is licensed under the MIT.

Code of Conduct

Everyone interacting in the AlexaRequestVerifier project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.