Facebook login callback hash documentation

Question

I'm using Omniauth with Devise to authenticate users via Facebook for a web app I'm writing using Rails 3.0.4

I modeled it after Ryan Bates' Railscasts:

http://railscasts.com/episodes/235-omniauth-part-1
http://railscasts.com/episodes/236-omniauth-part-2

At this point, I can log into my site with my Facebook account and pull my email out of the callback hash, which looks like this for me:

request.env["omniauth.auth"]  

{"user_info"=>  
  {"name"=>"Eric Hu",  
   "urls"=>  
    {"Facebook"=>"http://www.facebook.com/...", "Website"=>nil},  
   "nickname"=>"...",  
   "last_name"=>"Hu",  
   "first_name"=>"Eric"},  
 "uid"=>"...",  
 "credentials"=>  
  {"token"=> "..."},  
 "extra"=>  
  {"user_hash"=>  
    {"name"=>"Eric Hu",  
     "timezone"=>-8,  
     "gender"=>"male",  
     "id"=>"...",  
     "last_name"=>"Hu",  
     "updated_time"=>"2011-02-21T17:46:19+0000",  
     "verified"=>true,  
     "locale"=>"en_US",  
     "link"=>"http://www.facebook.com/...",  
     "email"=>"...",  
     "first_name"=>"Eric"}},  
 "provider"=>"facebook"}  

(replaced some fields with "..." for my own privacy)

Right now, I use this field to get the user's email address

 request.env["omniauth.auth"]["user_info"]["extra"]["email"]

I don't know if the callback hash varies with the user's settings--I've actually restricted my email display settings on Facebook and it still shows up. To make sure my code handles any possible variations with this hash, I'd like to find some reference on how this Facebook login callback hash looks and how it can vary. So far I haven't found anything on SO or the Facebook developer documentation.

The question: is there an official reference for the Facebook login callback hash? I don't want to assume that all the same hash elements are there for all users. I included as much info as I could here for other people who want to authenticate their rails apps using Facebook and Omniauth.

Answer 1

Take a look at the Facebook permissions reference, this is a list of the permissions that you can request from the user. This allows you to request specific things and if the user grants permission then you can guarantee that the field is present. I would also recommend you read through their authentication docs so you understand the users experience.

Once you know what permissions you want you can update your devise config (config/initializers/devise.rb) so that devise is requesting the permissions you need:

config.omniauth :facebook, FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, {:scope => 'offline_access,email,user_birthday'}