Authenticating

For APIs that require authentication, grifter provides various levels of support to ensure that any kind of authentication can be done.

Overview

Authentication for REST APIs virtually always involves setting a header field to some secret value by which the server identifies your requests. In some cases this secret value can be calculated client side (HTTP Basic Authentication is an example of this). In other cases, some series of requests to the server must be made (OAuth authentication is an example of this).

Setting Headers

Grifter provides a way to set headers both permanently for all subsequent requests, and temporarily for only a single request. Knowing how to do both is important for understanding how to authenticate with your API.

This following bit of code shows how to set a header permanently for a service named 'my_api':

def authenticate_my_api
  my_api.headers['Authorization'] = "super_secret_value"
end

Here we see how we can control the headers for only a single request using the additional_headers option:

def request_with_custom_header
  my_api.get '/a-uri', additional_headers: { 'custom_header1' => 'abc', 'custom_header2', 'xyz'}
end

HTTP Basic Authentication

HTTP Basic authentication involves calculating an Authotization Header per RFC2617, and then plugging that token into the "Authorization" header. This is a good example of authentication that can be done purely with client side code (no requests to the server needed).

The steps are roughly defined as:

• Know your username & password, which is setup on your server
• Make a string by concatenating username + a single colon + password. For example, if my username is 'rschultheis' and my password is 'abc123', the string would be 'rschultheis:abc123'
• encode the string into base64
• set the Authorization header field to 'Basic ' + your encoded string. Using the example username/password above, we get 'Basic cnNjaHVsdGhlaXM6YWJjMTIzCg=='

We can now define a simple grift method that does this for us like:

require 'base64'   #this library is part of Ruby standard library
def authenticate username, password
  encoded_token = Base64.strict_encode64(username + ':' + password)
  my_api.headers['Authorization'] = 'Basic ' + encoded_token
end

And then in our grift code we merely call the following to permamnently authenticate

authenticate 'rschultheis', 'abc123'

More complex authentication flows like oauth follow a similar pattern, see below for an example.

Automatic Authentication

Grifter supports the ability to automatically authenticate. This is perhaps most useful in scenarios of using the grifter cmd line tool to make authenticated requests.
More generally though, it is possible to have this automatic authentication done when a Grifter object is created by passing in options that tell it to do so.

Any method that ends in 'grifter_authenticate' will be called first thing when a Grifter object is instantiated, if the authenticate option is set to true.

To carry on with our example above, lets rename the method to end in grifter_autheticate:

require 'base64'   #this library is part of Ruby standard library
def my_api_grifter_authenticate
  username = 'rschultheis'
  password = 'abc123'
  encoded_token = Base64.strict_encode64(username + ':' + password)
  my_api.headers['Authorization'] = 'Basic ' + encoded_token
end

And suppose we have some other grift method we want to call that requires an authenticated user, such as:

def protected_call
  my_api.post '/create-sprocket', { 'name' => 'new_sprocket' }
end

When we call it from the cmd line, authentication will be automatically done:

grift -v protected_call

Use -v to see all request / responses.