2010-10-14 10:55:47 -04:00
< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
< html xmlns = "http://www.w3.org/1999/xhtml" xml:lang = "en" lang = "en" >
< head >
< meta name = "Content-Type" content = "text/html; charset=utf-8" / >
< title > Documentation by YARD 0.6.1< / title >
< link rel = "stylesheet" href = "css/style.css" type = "text/css" media = "screen" charset = "utf-8" / >
< link rel = "stylesheet" href = "css/common.css" type = "text/css" media = "screen" charset = "utf-8" / >
< script type = "text/javascript" charset = "utf-8" >
relpath = '';
if (relpath != '') relpath += '/';
< / script >
< script type = "text/javascript" charset = "utf-8" src = "js/jquery.js" > < / script >
< script type = "text/javascript" charset = "utf-8" src = "js/app.js" > < / script >
< / head >
< body >
< script type = "text/javascript" charset = "utf-8" >
if (window.top.frames.main) document.body.className = 'frames';
< / script >
< div id = "header" >
< div id = "menu" >
< a href = "_index.html" title = "Index" > Index< / a > »
< span class = "title" > File: README< / span >
< div class = "noframes" > < span class = "title" > (< / span > < a href = "." target = "_top" > no frames< / a > < span class = "title" > )< / span > < / div >
< / div >
< div id = "search" >
< a id = "class_list_link" href = "#" > Class List< / a >
< a id = "method_list_link" href = "#" > Method List< / a >
< a id = "file_list_link" href = "#" > File List< / a >
< / div >
< div class = "clear" > < / div >
< / div >
< iframe id = "search_frame" > < / iframe >
< div id = "content" > < div id = 'filecontents' > < h1 id = 'omniauth_standardized_multiprovider_authentication' > OmniAuth: Standardized Multi-Provider Authentication< / h1 >
< p > OmniAuth is a new Rack-based authentication system for multi-provider external authentcation. OmniAuth is built from the ground up on the philosophy that < strong > authentication is not the same as identity< / strong > , and is based on two observations:< / p >
< ol >
< li > The traditional ‘ sign up using a login and password’ model is becoming the exception, not the rule. Modern web applications offer external authentication via OpenID, Facebook, and/or OAuth.< / li >
< li > The interconnectable web is no longer a dream, it is a necessity. It is not unreasonable to expect that one application may need to be able to connect to one, three, or twelve other services. Modern authentication systems should allow a user’ s identity to be associated with many authentications.< / li >
< / ol >
< h2 id = 'installation' > Installation< / h2 >
< p > To install OmniAuth, simply install the gem:< / p >
< pre class = "code" > < span class = 'gem identifier id' > gem< / span > < span class = 'install identifier id' > install< / span > < span class = 'omniauth identifier id' > omniauth< / span >
< / pre >
< h2 id = 'providers' > Providers< / h2 >
< p > OmniAuth currently supports the following external providers:< / p >
< ul >
< li >
< p > via OAuth< / p >
< ul >
< li > Facebook< / li >
< li > Twitter< / li >
< li > 37signals ID< / li >
< li > Foursquare< / li >
< li > LinkedIn< / li >
< li > GitHub< / li >
2010-10-14 17:21:34 -04:00
< li > Identi.ca (credit: < a href = 'http://github.com/dcu' > dcu< / a > )< / li >
2010-10-14 10:55:47 -04:00
2010-10-14 17:21:34 -04:00
< li > Gowalla (credit: < a href = 'http://github.com/kvnsmth' > kvnsmth< / a > )< / li >
2010-10-19 19:02:25 -04:00
< li > Dopplr (credit: < a href = 'http://github.com/flextrip' > flextrip< / a > )< / li >
< li > TripIt (credit: < a href = 'http://github.com/flextrip' > flextrip< / a > )< / li >
2010-10-25 18:24:53 -04:00
< li > Meetup (credit < a href = 'http://github.com/coderoshi' > coderoshi< / a > )< / li >
< li > SoundCloud (credit: < a href = 'http://github.com/leemartin' > leemartin< / a > )< / li >
2010-10-14 10:55:47 -04:00
< / ul >
< / li >
< li >
< p > OpenID< / p >
< / li >
< li >
< p > Google Apps (via OpenID)< / p >
< / li >
< li >
2010-10-14 17:21:34 -04:00
< p > CAS (Central Authentication Service) (credit: < a href = 'http://github.com/jamesarosen' > jamesarosen< / a > )< / p >
2010-10-14 10:55:47 -04:00
< / li >
< li >
2010-10-25 18:24:53 -04:00
< p > LDAP (credit: < a href = 'http://github.com/pyu10055' > pyu10055< / a > )< / p >
2010-10-14 10:55:47 -04:00
< / li >
< / ul >
< h2 id = 'usage' > Usage< / h2 >
< p > OmniAuth is a collection of Rack middleware. To use a single strategy, you simply need to add the middleware:< / p >
< pre class = "code" > < span class = 'require identifier id' > require< / span > < span class = 'string val' > 'oa-oauth'< / span >
< span class = 'use identifier id' > use< / span > < span class = 'OmniAuth constant id' > OmniAuth< / span > < span class = 'colon2 op' > ::< / span > < span class = 'Strategies constant id' > Strategies< / span > < span class = 'colon2 op' > ::< / span > < span class = 'Twitter constant id' > Twitter< / span > < span class = 'comma token' > ,< / span > < span class = 'string val' > 'CONSUMER_KEY'< / span > < span class = 'comma token' > ,< / span > < span class = 'string val' > 'CONSUMER_SECRET'< / span >
< / pre >
< p > Now to initiate authentication you merely need to redirect the user to < code > /auth/twitter< / code > via a link or other means. Once the user has authenticated to Twitter, they will be redirected to < code > /auth/twitter/callback< / code > . You should build an endpoint that handles this URL, at which point you will will have access to the authentication information through the < code > omniauth.auth< / code > parameter of the Rack environment. For example, in Sinatra you would do something like this:< / p >
< pre class = "code" > < span class = 'get identifier id' > get< / span > < span class = 'string val' > '/auth/twitter/callback'< / span > < span class = 'do do kw' > do< / span >
< span class = 'auth_hash identifier id' > auth_hash< / span > < span class = 'assign token' > =< / span > < span class = 'request identifier id' > request< / span > < span class = 'dot token' > .< / span > < span class = 'env identifier id' > env< / span > < span class = 'lbrack token' > [< / span > < span class = 'string val' > 'omniauth.auth'< / span > < span class = 'rbrack token' > ]< / span >
< span class = 'end end kw' > end< / span >
< / pre >
< p > The hash in question will look something like this:< / p >
< pre class = "code" > < span class = 'lbrace token' > {< / span >
< span class = 'string val' > 'uid'< / span > < span class = 'assign token' > =< / span > < span class = 'gt op' > > < / span > < span class = 'string val' > '12356'< / span > < span class = 'comma token' > ,< / span >
< span class = 'string val' > 'provider'< / span > < span class = 'assign token' > =< / span > < span class = 'gt op' > > < / span > < span class = 'string val' > 'twitter'< / span > < span class = 'comma token' > ,< / span >
< span class = 'string val' > 'user_info'< / span > < span class = 'assign token' > =< / span > < span class = 'gt op' > > < / span > < span class = 'lbrace token' > {< / span >
< span class = 'string val' > 'name'< / span > < span class = 'assign token' > =< / span > < span class = 'gt op' > > < / span > < span class = 'string val' > 'User Name'< / span > < span class = 'comma token' > ,< / span >
< span class = 'string val' > 'nickname'< / span > < span class = 'assign token' > =< / span > < span class = 'gt op' > > < / span > < span class = 'string val' > 'username'< / span > < span class = 'comma token' > ,< / span >
< span class = 'comment val' > # ...< / span >
< span class = 'rbrace token' > }< / span >
< span class = 'rbrace token' > }< / span >
< / pre >
< p > The < code > user_info< / code > hash will automatically be populated with as much information about the user as OmniAuth was able to pull from the given API or authentication provider.< / p >
< h2 id = 'resources' > Resources< / h2 >
< p > The best place to find more information is the < a href = 'http://github.com/intridea/omniauth/wiki' > OmniAuth Wiki< / a > . Some specific information you might be interested in:< / p >
< ul >
< li > < a href = 'http://github.com/intridea/omniauth/wiki/Roadmap' > Roadmap< / a > < / li >
< li > < a href = 'http://github.com/intridea/omniauth/wiki/Changelog' > Changelog< / a > < / li >
< li > < a href = 'http://github.com/intridea/omniauth/issues' > Report Issues< / a > < / li >
< li > < a href = 'http://groups.google.com/group/omniauth' > Mailing List< / a > < / li >
2010-10-19 19:02:25 -04:00
< / ul >
< h2 id = 'license' > License< / h2 >
< p > OmniAuth is licensed under the MIT License.< / p > < / div > < / div >
2010-10-14 10:55:47 -04:00
< div id = "footer" >
2010-10-25 18:24:53 -04:00
Generated on Mon Oct 25 17:24:47 2010 by
2010-10-14 10:55:47 -04:00
< a href = "http://yardoc.org" title = "Yay! A Ruby Documentation Tool" target = "_parent" > yard< / a >
0.6.1 (ruby-1.8.7).
< / div >
< / body >
< / html >
