Auth Hash Schema

nileshtrivedi edited this page Dec 12, 2014 · 11 revisions

OmniAuth will always return a hash of information after authenticating with an external provider in the Rack environment under the key omniauth.auth. This information is meant to be as normalized as possible, so the schema below will be filled to the greatest degree available given the provider upon authentication. Fields marked required will always be present. Note that this guide may also be useful to developers implementing custom strategies to know how to provide results.

Schema (1.0 and Later)

  • provider (required) - The provider with which the user authenticated (e.g. 'twitter' or 'facebook')
  • uid (required) - An identifier unique to the given provider, such as a Twitter user ID. Should be stored as a string.
  • info (required) - A hash containing information about the user
    • name (required) - The best display name known to the strategy. Usually a concatenation of first and last name, but may also be an arbitrary designator or nickname for some strategies
    • email - The e-mail of the authenticating user. Should be provided if at all possible (but some sites such as Twitter do not provide this information)
    • nickname - The username of an authenticating user (such as your @-name from Twitter or GitHub account name)
    • first_name
    • last_name
    • location - The general location of the user, usually a city and state.
    • description - A short description of the authenticating user.
    • image - A URL representing a profile image of the authenticating user. Where possible, should be specified to a square, roughly 50x50 pixel image.
    • phone - The telephone number of the authenticating user (no formatting is enforced).
    • urls - A hash containing key value pairs of an identifier for the website and its URL. For instance, an entry could be "Blog" => "http://intridea.com/blog"
  • credentials - If the authenticating service provides some kind of access token or other credentials upon authentication, these are passed through here.
    • token - Supplied by OAuth and OAuth 2.0 providers, the access token.
    • secret - Supplied by OAuth providers, the access token secret.
    • expires - Boolean indicating whether the access token has an expiry date
    • expires_at - Timestamp of the expiry time. Facebook and Google Plus return this. Twitter, LinkedIn don't.
  • extra - Contains extra information returned from the authentication provider. May be in provider-specific formats.
    • raw_info - A hash of all information gathered about a user in the format it was gathered. For example, for Twitter users this is a hash representing the JSON hash returned from the Twitter API.

Schema (0.3 and Prior)

  • provider (required) - The provider with which the user authenticated (e.g. 'twitter' or 'facebook')
  • uid (required) - An identifier unique to the given provider, such as a Twitter user ID. Should be stored as a string.
  • user_info (required) - A hash containing information about the user
    • name (required) - The best display name known to the strategy. Usually a concatenation of first and last name, but may also be an arbitrary designator or nickname from some systems
    • email - The e-mail of the authenticating user. Should be provided if at all possible (but some sites such as Twitter do not provide this information)
    • nickname - The username of an authenticating user (such as your @-name from Twitter or GitHub account name)
    • first_name
    • last_name
    • location - The general location of the user, usually a city and state.
    • description - A short description of the authenticating user.
    • image - A URL representing a profile image of the authenticating user. Where possible, should be specified to a square, roughly 50x50 pixel image.
    • phone - The telephone number of the authenticating user (no formatting is enforced).
    • urls - A hash containing key value pairs of an identifier for the website and its URL. For instance, an entry could be "Blog" => "http://intridea.com/blog"
  • credentials - If the authenticating service provides some kind of access token or other credentials upon authentication, these are passed through here.
    • token - Supplied by OAuth and OAuth 2.0 providers, the access token.
    • secret - Supplied by OAuth providers, the access token secret.
  • extra - Contains extra information returned from the authentication provider. May be in provider-specific formats.
    • user_hash - A hash of all information gathered about a user in the format it was gathered. For example, for Twitter users this is a hash representing the JSON hash returned from the Twitter API.