{"id":2168,"date":"2015-09-11T15:51:09","date_gmt":"2015-09-11T10:21:09","guid":{"rendered":"http:\/\/codetheory.in\/?p=2168"},"modified":"2015-09-23T21:43:51","modified_gmt":"2015-09-23T16:13:51","slug":"rails-devise-omniauth-sso","status":"publish","type":"post","link":"https:\/\/codetheory.in\/rails-devise-omniauth-sso\/","title":{"rendered":"Single Sign On (SSO) for Multiple Applications with Devise, OmniAuth and Custom OAuth2 Implementation in Rails"},"content":{"rendered":"<p>Recently I had to implement <a href=\"https:\/\/en.wikipedia.org\/wiki\/Single_sign-on\" target=\"_blank\" rel=\"noopener\">Single Sign On<\/a> (SSO) for one of the Rails app I&#8217;d been working on. Since Devise is already fairly popular to integrate an authentication system in Rails app, I was more inclined towards using it to achieve SSO. So essentially what was required is a single user manager app that can act as a <strong>Provider<\/strong> (OAuth2 ?) and different applications (or <strong>Clients<\/strong>) that can authenticate themselves using this same user manager. An important part of SSO is, once you sign in to one of the client, you should automatically be authorized to access all the other clients (their login-protected sections\/modules). Similarly, logging out from one service should log out from all other services.<\/p>\n<p><!--more--><\/p>\n<p>To accomplish this, I found an excellent article by <a href=\"http:\/\/blog.joshsoftware.com\/2010\/12\/16\/multiple-applications-with-devise-omniauth-and-single-sign-on\/\" target=\"_blank\" rel=\"noopener\">JoshSoftware<\/a> that solved my problem. Although I&#8217;d to change a lot of the code to make it Rails 4 compatible (from Rails 3). I&#8217;ve even uploaded the source code on Github:<\/p>\n<ul>\n<li>Provider &#8211; <a href=\"https:\/\/github.com\/rishabhp\/sso-rails-provider\" target=\"_blank\" rel=\"noopener\">https:\/\/github.com\/rishabhp\/sso-rails-provider<\/a><\/li>\n<li>Client &#8211; <a href=\"https:\/\/github.com\/rishabhp\/sso-rails-client\" target=\"_blank\" rel=\"noopener\">https:\/\/github.com\/rishabhp\/sso-rails-client<\/a><\/li>\n<\/ul>\n<p>Basically, OmniAuth on the client-side and some custom code on the provider-side is used to turn the provider into an OAuth2 provider, eventually accomplishing SSO. A lot of magic happens under the hood, so I decided to document the entire flow (even inside the gems) of the authentication process.<\/p>\n<h2>Authentication by Client<\/h2>\n<p>When a request is sent to the <code>Client<\/code> which is supposed to require authentication, it&#8217;ll check whether the user is logged in or not. If yes (<code>session<\/code> has data) then that&#8217;s fine otherwise the <code>Client<\/code> will redirect the user to a specific URL (of the <strong>Provider<\/strong>) where he can authenticate himself.<\/p>\n<p>Implementation of this starts off by creating a custom OAuth2 Strategy which extends from <code>OmniAuth::Strategies::OAuth2<\/code> (<a href=\"https:\/\/github.com\/intridea\/omniauth-oauth2\" target=\"_blank\" rel=\"noopener\">omniauth-oauth2<\/a>). The omniauth-oauth2 gem is basically a generic OAuth2 strategy for OmniAuth which basically means that it can serve as a building block for custom providers like omniauth-facebook (FB auth), omniauth-twitter (Twitter auth) and so on. So if we decide to call our provider <strong>Sso<\/strong> then we&#8217;ll have to create a custom strategy that&#8217;ll extend the same class, so something like this <code>class Sso < OmniAuth::Strategies::OAuth2<\/code>. The <code>Provider<\/code> must also be specified in <code>initializers\/omniauth.rb<\/code> so that it can be mounted as a Rack middleware.<\/p>\n<p>If the user is not signed in then he's redirected to the Client's <code>\/auth\/sso<\/code> URI. This is important because it triggers further authentication process. So this is a single entry point for all non-authenticated requests to a Client for authentications's sake as it'll trigger the entire chain of events further, required for authentication.<\/p>\n<p>The request to <code>\/auth\/sso<\/code> basically triggers the <code>request_phase<\/code> method of the custom strategy which calls the <code>request_phase<\/code> of <code>OmniAuth::Strategies::OAuth2<\/code> (parent class). How does this all happen ? So when the <code>OmniAuth::Builder<\/code> middleware was mounted (in <code>initializers\/omniauth.rb<\/code>), the call to <code>provider<\/code> mounted <code>OmniAuth::Strategies::Sso<\/code> which extends <code>OmniAuth::Strategies::OAuth2<\/code>. The initializer code looks something like this (for more context):<\/p>\n<pre class=\"brush: ruby; title: ; notranslate\" title=\"\">\r\nAPP_ID = 'key'\r\nAPP_SECRET = 'secret'\r\n\r\nCUSTOM_PROVIDER_URL = 'http:\/\/localhost:3000'\r\n\r\nRails.application.config.middleware.use OmniAuth::Builder do\r\n  provider :sso, APP_ID, APP_SECRET\r\nend\r\n<\/pre>\n<p>To get the <code>key<\/code> and <code>secret<\/code>, a <strong>Client<\/strong> has to be registered first in the <strong>Provider<\/strong>. So basically the DB has a <code>clients<\/code> table with these columns (to maintain all the registered clients):<\/p>\n<pre class=\"brush: plain; title: ; notranslate\" title=\"\">\r\nid | name | app_id | app_secret | created_at | updated_at\r\n<\/pre>\n<p>So the <code>request_phase<\/code> of <code>OmniAuth::Strategies::OAuth2<\/code> (parent class) redirects the user to the <code>authorize_url<\/code> (on the <strong>Provider<\/strong>) specified in the custom strategy with certain parameters (looks something like <code>\/auth\/sso\/authorize?get_params<\/code>). Here\u2019s a sample URL:<\/p>\n<pre class=\"brush: plain; title: ; notranslate\" title=\"\">\r\nhttp:\/\/localhost:3000\/auth\/sso\/authorize?client_id=key&redirect_uri=http%3A%2F%2Flocalhost%3A3001%2Fauth%2Fsso%2Fcallback&response_type=code&state=f73bd089efa7722364d10ed36625502bd19783e27b628fdb\r\n<\/pre>\n<p>The <code>redirect_uri<\/code> (<code>http:\/\/localhost:3001\/auth\/sso\/callback<\/code> in this case) is generated by the <code>callback_path<\/code> method of <code>OmniAuth::Strategy<\/code> module (omniauth gem) which is included in the <code>OmniAuth::Strategies::OAuth2<\/code> class (omniauth-oauth2 gem). The callback path is something like <code>#{path_prefix}\/#{name}\/callback<\/code> (evaluates to <code>auth\/sso\/callback<\/code>) by default (should be configurable).<\/p>\n<h2>Authentication by Provider<\/h2>\n<p>At this stage the User has been redirected from the <strong>Client<\/strong> to <strong>Provider<\/strong> for authentication with the help of <code>authorize_url<\/code>. As already mentioned this URL looks something like this <code>\/auth\/sso\/authorize?get_params<\/code> and is protected by Devise. So if the user is not logged into the <strong>Provider<\/strong> he'll be taken to the signin\/signup flow\/page (<code>http:\/\/provider\/user\/sign_in<\/code> for instance) which once completed redirects the user back to this <code>authorize_url<\/code>. This post-signin\/signup redirection happens via Devise automagically since it maintains the previous URL requested (that led to the sign in page) in <code>session['user_return_to']<\/code>. Once the user is authenticated (or if he was already authenticated by the <strong>Provider<\/strong>) then the action mapped to the <code>\/auth\/sso\/authorize<\/code> route is executed.<\/p>\n<p>The <code>authorize<\/code> action gets a param called <code>state<\/code> (if you notice the URL above) which is generated inside <code>OmniAuth::Strategies::OAuth2<\/code> (in omniauth-oauth2 of <strong>Client<\/strong>) like this <code>options.authorize_params[:state] = SecureRandom.hex(24)<\/code>. The <code>state<\/code> value is be later used in the <code>callback_phase<\/code> of omniauth-oauth2 for a CSRF check (protection). Basically the action creates an entry in a table called <code>access_grants<\/code> with these fields:<\/p>\n<pre class=\"brush: plain; title: ; notranslate\" title=\"\">\r\ncode | access_token | refresh_token | access_token_expires_at | user_id | client_id | state | created_at\r\n<\/pre>\n<p>The <code>code<\/code>, <code>access_token<\/code>, <code>refresh_token<\/code> fields are generated using <code>SecureRandom.hex(16)<\/code>. After creating an access grant, the user is redirected to the callback URL with the same <code>state<\/code> param that was sent while authentication redirection and the newly generated <code>code<\/code> param. So then new redirection URL will be something like this -  <code>redirect_uri + \"?code=#{code}&response_type=code&state=#{state}\"<\/code> where the <code>redirect_uri<\/code> is the same callback URL as above retrieved via <code>params['redirect_uri']<\/code>.<\/p>\n<h2>Client Callback Processing<\/h2>\n<p>After authorization that creates a secret <code>code<\/code>, the user is redirected to the callback URL which is on the <strong>Client<\/strong>. The callback URL looks something like this <code>\/auth\/sso\/callback?code=xxx&response_type=code&state=xxx<\/code>. It is intercepted by <code>OmniAuth::Strategies::Sso < OmniAuth::Strategies::OAuth2<\/code> (custom OAuth2 strategy) which was setup as a middleware by <code>OmniAuth::Builder<\/code>'s <code>provider<\/code> method call. To recap, <code>OmniAuth::Strategies::OAuth2<\/code> includes <code>OmniAuth::Strategies<\/code> and <code>OmniAuth::Builder<\/code> loads <code>OmniAuth::Strategies::Sso<\/code> as a middleware. On interception, the <code>call<\/code> method on <code>OmniAuth::Strategies<\/code> is called (because it is included by <code>OmniAuth::Strategies::OAuth2<\/code> and it's a rack middleware) which triggers the <code>callback_call<\/code> method which in turn calls the <code>callback_phase<\/code> method whose job is to basically set <code>omniauth.auth<\/code> env variable (<code>env['omniauth.auth']<\/code>) to an <code>AuthHash<\/code>. While setting this AuthHash a couple of methods are called that should be defined in the custom strategy implementation like <code>uid<\/code>, <code>info<\/code>, <code>credentials<\/code> and <code>extra<\/code>.<\/p>\n<p>It is very important to note that <strong>before<\/strong> the <code>callback_phase<\/code> of <code>OmniAuth::Strategies<\/code> module, the same of <code>OmniAuth::Strategies::OAuth2<\/code> is called (since it includes <code>OmniAuth::Strategies<\/code> and its <code>callback_phase<\/code> calls <code>super<\/code>). This method does a couple of interesting things. It triggers <code>build_access_token<\/code> which basically makes a request to the Provider with the <code>code<\/code> that had been received. What this method does is, it uses the <code>oauth2<\/code> library to get the access token from the <code>token_url<\/code> specified in the custom strategy (otherwise default is <code>\/oauth\/token<\/code>). So it hits the <code>token_url<\/code> with the <code>code<\/code>, <code>client_id<\/code>, <code>client_secret<\/code> to receive the access token. Feel free to check the rails developments logs while you try to login for all other params\/info. Once the Provider gets this request, it checks if a client record exists in its DB with the <code>client_id<\/code> and <code>client_secret<\/code> and whether the <code>code<\/code> actually is associated with any <code>AccessGrant<\/code> which is associated to a User. In the end it will return a JSON object:<\/p>\n<pre class=\"brush: jscript; title: ; notranslate\" title=\"\">\r\n{&quot;access_token&quot;: &quot;access_token&quot;, &quot;refresh_token&quot; =&gt; &quot;refresh_token&quot;, &quot;expires_in&quot;: Devise.timeout_in.to_i}\r\n<\/pre>\n<p>Out of the object returned above, oauth2 gem creates an <code>AccessToken<\/code> object (accessed as <code>access_token<\/code> across codebase) which sets instance variable for each key and renames <code>access_token<\/code> to <code>token<\/code> - so it's accessed as <code>access_token_ob.token<\/code>.<\/p>\n<p>Finally the <code>token_url<\/code> will hit the action mapped to it in <code>routes.rb<\/code> which has to be a custom implementation. There <code>env['omniauth.auth']<\/code> will contain an object of the <a href=\"https:\/\/github.com\/intridea\/omniauth\/wiki\/Auth-Hash-Schema\" target=\"_blank\" rel=\"noopener\">AuthHash<\/a> type (because of that call to <code>callback_phase<\/code> of <code>OmniAuth::Strategies<\/code> module). Here's a sample dump of it to show how it'll look like:<\/p>\n<pre class=\"brush: jscript; title: ; notranslate\" title=\"\">\r\n{&quot;provider&quot;=&gt;&quot;sso&quot;,\r\n &quot;uid&quot;=&gt;&quot;2&quot;,\r\n &quot;info&quot;=&gt;{&quot;email&quot;=&gt;&quot;rishabh.pugalia@gmail.com&quot;},\r\n &quot;credentials&quot;=&gt;\r\n  {&quot;token&quot;=&gt;&quot;7c21854636f5d71c3dde2bde2cc93e16&quot;,\r\n   &quot;refresh_token&quot;=&gt;&quot;5f5770f7028eefae6e775cba8aef7a5a&quot;,\r\n   &quot;expires_at&quot;=&gt;1441737106,\r\n   &quot;expires&quot;=&gt;true},\r\n &quot;extra&quot;=&gt;{&quot;first_name&quot;=&gt;&quot;&quot;, &quot;last_name&quot;=&gt;&quot;&quot;}}\r\n<\/pre>\n<p>These info are fetched by executing the blocks passed to the respective methods (uid, info, extra, etc.). These methods will be defined in your custom strategy. The <code>credentials<\/code> is specified in <code>OmniAuth::Strategies::OAuth2<\/code> (omniauth-oauth2).<\/p>\n<h2>Using the Access Token<\/h2>\n<p>Now that we have the access token object with us, we can start making HTTP requests to the <strong>Provider<\/strong> from <strong>Client<\/strong> and pass the access token with it which can be checked against the DB in Provider for authorization. We can even do a Devise <a href=\"https:\/\/github.com\/rishabhp\/sso-rails-provider\/blob\/master\/app\/controllers\/auth_controller.rb\" target=\"_blank\" rel=\"noopener\"><code>sign_in<\/code><\/a> call on the user object if one is found via the <code>access_token<\/code>.<\/p>\n<p>The oauth2 gem's <code>AccessToken<\/code> object has a concept of refreshing tokens too. Right after the <code>build_access_token<\/code> is called and the access token is fetched, a call is made to <code>access_token.refresh!<\/code> if the access token has expired. So if the response of access token has <code>expires_at<\/code> which is less than current time (<code>expires_at &lt; Time.now.to_i<\/code>) then the gem will make a new request to get the access token (same flow as above) but this time the token sent for verification will be a <code>refresh_token<\/code> which was generated the first time when access was granted and it should be used to return the old access token (might want to regenerate that). The other difference will be in the <code>grant_type<\/code> param which will be <code>refresh_token<\/code> this time compared to <code>authorization_code<\/code> earlier. This call should also re-set (update) the expiry time of the access token.<\/p>\n<p>In the existing code (hosted on Github, linked above), on the client-side, if the user is logged in successfully and the relevant session expires after sometime (or destroyed), the user will be redirected to the Provider where he'll be logged in. In this case the Provider will create a new access token and redirect the user to the Client which will again make an internal call to the Provider to obtain the access token. The code (hosted on Github above) can be modified (<a href=\"https:\/\/github.com\/rishabhp\/sso-rails-provider\/blob\/master\/app\/controllers\/auth_controller.rb\" target=\"_blank\" rel=\"noopener\"><code>AuthController#authorize<\/code><\/a>) in a way where if the user is already logged in to the Provider and has a **recently used** access token, in the case the expiry of that token can be re-set to a future date and re-used.<\/p>\n<h2>Overall Conceptual Flow<\/h2>\n<ul>\n<li>Client redirects the user to the Provider for Authentication.<\/li>\n<li>User logs into the Provider.<\/li>\n<li>Provider redirects the user to Client with a special random code.<\/li>\n<li>Client uses the special random code to make an API call to the Provider along with its ID and Secret keys to obtain the Access Token.<\/li>\n<li>Further requests (for any operation like getting user details, making payment, etc.) are made with the Access Token which authorizes the User against the DB.<\/li>\n<li>Logout clears the Session on Client as well as Provider and Database.<\/li>\n<\/ul>\n<p>That's all folks!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Recently I had to implement Single Sign On (SSO) for one of the Rails app I&#8217;d been working on. Since Devise is already fairly popular to integrate an authentication system in Rails app, I was more inclined towards using it to achieve SSO. So essentially what was required is a single user manager app that &hellip; <a href=\"https:\/\/codetheory.in\/rails-devise-omniauth-sso\/\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;Single Sign On (SSO) for Multiple Applications with Devise, OmniAuth and Custom OAuth2 Implementation in Rails&#8221;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[12],"tags":[161,162,150,47,163],"_links":{"self":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2168"}],"collection":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/comments?post=2168"}],"version-history":[{"count":9,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2168\/revisions"}],"predecessor-version":[{"id":2178,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2168\/revisions\/2178"}],"wp:attachment":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/media?parent=2168"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/categories?post=2168"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/tags?post=2168"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}