Project

General

Profile

Workbench authentication process » History » Version 17

Peter Amstutz, 11/20/2014 02:29 PM

1 17 Peter Amstutz
h1. 
2
3
h1. Workbench authentication process (Google OAuth2) (WIP)
4
5
# In workbench, when the browser goes to a page, it checks for a session or @?api_token=xxx@ in the URL for the API token.  If no API token is found, the brower is directed to the workbench "welcome" page.
6
# In workbench, the "welcome" page has a "log in" button that directs the browser to the API server login URL, with a @?return_to=xxx@ link embedded in the URL.
7
# In API server, the 'login' endpoint goes to @UserSessionsController#login@ in the API server.  This redirects the browser to @/auth/joshid?return_to=xxx@
8
# In API server, @/auth/joshid@ is intercepted by the "OmniAuth":https://github.com/intridea/omniauth Rack middleware and invokes the @josh_id@ OmniAuth strategy.
9
## The @josh_id@ OmniAuth strategy is implemented in @arvados/services/api/lib/josh_id.rb@ and is a subclass of @OmniAuth::Strategies::OAuth2@
10
## OmniAuth starts the "request_phase" of @OmniAuth::Strategies::OAuth2@.  This redirects the browser to @#{options[:custom_provider_url]}/auth/josh_id/authorize@ using CUSTOM_PROVIDER_URL defined in @arvados/services/api/config/initializers/omniauth.rb@
11
# In sso-provider, @/auth/josh_id/authorize@ is routed to @AuthController#authorize@, and is intercepted by @before_filter :authenticate_user!@ (part of the "devise gem":https://github.com/plataformatec/devise)
12
## @devise :omniauthable, :omniauth_providers => [:google]@ configures @sso-provider/app/models/user.rb@
13
## @authenticate_user!@ is not explicitly defined but instead monkey patched into the controller in @devise/lib/devise/controllers/helper.rb@
14
## @authenticate_user!@ calls @warden.authenticate!@ (@warden/lib/warden/proxy.rb@) with a scope of @:user@ ("warden":https://github.com/hassox/warden is another Rack-based authentication gem)
15
## Warden proxy tries the TokenAuthenticatable and DatabaseAuthenticatable strategies, but these strategies fail and it raises a :warden exception.  This causes it to call @failure_app@ which is set up in @devise/lib/devise.rb@ to be @Devise::Delegator.new@ 
16
## This calls @devise/lib/devise/failure_app.rb@ which saves the attempted path in the session ("user_return_to") using @store_location!@, then redirects the browser to  @new_user_session_path@ (@/users/sign_in@) 
17
# In sso-provider @/users/sign_in@ routes to the SSO @SessionsController#new@ which subclasses @Devise::SessionsController@
18
## @SessionsController#new@ redirects the browser to @/users/auth/google@
19
# In sso-provider, OmniAuth intercepts @/users/auth/google@ 
20
## OmniAuth is configured with a path prefix of @/users/auth@ by devise 
21
## @sso-provider/config/initializers/devise.rb@ configures a @:open_id@ omniauth strategy named of 'google'
22
## This enters the request phase at @omniauth-open-id/lib/omniauth/strategies/open_id.rb@
23
## This creates a rack layer with @Rack::OpenID.new@ (the @rack-openid@ gem) executes it with @call@
24
## The Rack layer passes through the request to the underlying @@app@ and checks for a 401 response code, if so it calls @begin_authentication@
25
## @begin_authentication@ constructs an @::OpenID::Consumer@ object and calls redirects the browser to @open_id_redirect_url@, which finally takes us to a Google login page (after some redirects within Google).
26
# Google presents the user with a login page, and directs the browser to the sso-server at @/users/auth/google/callback@ after a successful login (after more redirects within Google)
27
# In sso-provider, Omniauth intercepts this and calls @callback_phase@ in omniauth-openid
28
## The callback phase calls @openid_response@
29
## @openid_response@ creates a rack layer with @Rack::OpenID.new@ (the @rack-openid@ gem) executes it with @call@.  This provisions the Rack environment with info from the OpenID callback.
30
## Request handling continues to sso-provider where it routes to @Users::OmniauthCallbacksController#google@
31
## This calls @find_for_open_id@ on the @User@ model which finds a user record with a matching identity url, or creates and saves a new user record with the identity url.
32
## The @google@ callback also saves the first_name and last_name of the user.
33
## This calls @sign_in_and_redirect@ defined in @devise/lib/devise/controllers/helpers.rb@
34
## This calls set_user in Warden, which uses @Warden::SessionSerializer@ to save the user associated with the session
35
## This redirects the browser to @stored_location_for@ which returns the value of @user_return_to@ in the session, which is @/auth/josh_id/authorize@ from step 5.
36
# In sso-provider, @/auth/josh_id/authorize@ routes to @AuthController#authorize@, and passes @authenticate_user!@ because the there is now a user associated with the session.
37
## @authorize@ builds an @AccessGrant@ using the @state@ token from the request
38
## @authorize@ redirects the browser to @params[:redirect_uri]@ which is @/auth/josh_id/callback@ (this is the oauth callback on the API server, saved from step 5)
39
# In API server, @/auth/josh_id/callback@ is intercepted by @OmniAuth::Strategies::OAuth2@ and calls @callback_phase@.
40
## @OmniAuth::Strategies::OAuth2@ creates a @::OAuth2::Client@ and calls @get_token@ to convert the "authorization_code" into a "oauth_token"
41
## The API server makes a request to the sso-provider at @/oauth/token@
42
# In the sso-provider, @/oauth/token@ is routed to @AuthController#access_token@
43
## This first checks @Client.authenticate@ which verifies that @client_id@ (@app_id@) and @client_secret@ (@app_secret@) are recognized
44
## Next it calls @AccessGrant.authenticate@ which verifies that @code@ and @client_id@ are recognized
45
## This renders an JSON API response with the @access_token@, @refresh_token@ and @expires_in@ fields which are returned to the API server.
46
# The API server, back in OmniAuth::Strategies::OAuth2, receives the response and saves the @access_token@.
47
## Request processing continues and routes to @UserSessionsController#create@
48
## API server gets the OmniAuth object and looks up the Arvados API user by @identity_url@
49
## The session is provisioned with the Arvados user id
50
## @if params.has_key?(:return_to)@ then it calls @send_api_token_to@ 
51
## @send_api_token_to@ creates a new ApiClientAuthorization
52
## It redirects the browser to the @:return_to@  after adding @api_token=xxx@ to the query portion of return_to
53
# The browser is finally redirected to workbench to with @api_token=xxx@
54
## Workbench adds the api_token to the session, and redirects the browser one last time to the same location with @?api_token@ stripped from the query portion.
55
56
h2. Questions
57
58
* What is workbench's "secret_token" for? 
59
60
h1. Workbench authentication process (Google OpenID 2.0)
61 1 Peter Amstutz
62 15 Peter Amstutz
# In workbench, when the browser goes to a page, it checks for a session or @?api_token=xxx@ in the URL for the API token.  If no API token is found, the brower is directed to the workbench "welcome" page.
63
# In workbench, the "welcome" page has a "log in" button that directs the browser to the API server login URL, with a @?return_to=xxx@ link embedded in the URL.
64
# In API server, the 'login' endpoint goes to @UserSessionsController#login@ in the API server.  This redirects the browser to @/auth/joshid?return_to=xxx@
65 12 Peter Amstutz
# In API server, @/auth/joshid@ is intercepted by the "OmniAuth":https://github.com/intridea/omniauth Rack middleware and invokes the @josh_id@ OmniAuth strategy.
66 11 Peter Amstutz
## The @josh_id@ OmniAuth strategy is implemented in @arvados/services/api/lib/josh_id.rb@ and is a subclass of @OmniAuth::Strategies::OAuth2@
67 15 Peter Amstutz
## OmniAuth starts the "request_phase" of @OmniAuth::Strategies::OAuth2@.  This redirects the browser to @#{options[:custom_provider_url]}/auth/josh_id/authorize@ using CUSTOM_PROVIDER_URL defined in @arvados/services/api/config/initializers/omniauth.rb@
68 14 Peter Amstutz
# In sso-provider, @/auth/josh_id/authorize@ is routed to @AuthController#authorize@, and is intercepted by @before_filter :authenticate_user!@ (part of the "devise gem":https://github.com/plataformatec/devise)
69 10 Peter Amstutz
## @devise :omniauthable, :omniauth_providers => [:google]@ configures @sso-provider/app/models/user.rb@
70
## @authenticate_user!@ is not explicitly defined but instead monkey patched into the controller in @devise/lib/devise/controllers/helper.rb@
71
## @authenticate_user!@ calls @warden.authenticate!@ (@warden/lib/warden/proxy.rb@) with a scope of @:user@ ("warden":https://github.com/hassox/warden is another Rack-based authentication gem)
72 1 Peter Amstutz
## Warden proxy tries the TokenAuthenticatable and DatabaseAuthenticatable strategies, but these strategies fail and it raises a :warden exception.  This causes it to call @failure_app@ which is set up in @devise/lib/devise.rb@ to be @Devise::Delegator.new@ 
73 15 Peter Amstutz
## This calls @devise/lib/devise/failure_app.rb@ which saves the attempted path in the session ("user_return_to") using @store_location!@, then redirects the browser to  @new_user_session_path@ (@/users/sign_in@) 
74 14 Peter Amstutz
# In sso-provider @/users/sign_in@ routes to the SSO @SessionsController#new@ which subclasses @Devise::SessionsController@
75 15 Peter Amstutz
## @SessionsController#new@ redirects the browser to @/users/auth/google@
76 13 Peter Amstutz
# In sso-provider, OmniAuth intercepts @/users/auth/google@ 
77
## OmniAuth is configured with a path prefix of @/users/auth@ by devise 
78 1 Peter Amstutz
## @sso-provider/config/initializers/devise.rb@ configures a @:open_id@ omniauth strategy named of 'google'
79
## This enters the request phase at @omniauth-open-id/lib/omniauth/strategies/open_id.rb@
80
## This creates a rack layer with @Rack::OpenID.new@ (the @rack-openid@ gem) executes it with @call@
81
## The Rack layer passes through the request to the underlying @@app@ and checks for a 401 response code, if so it calls @begin_authentication@
82 15 Peter Amstutz
## @begin_authentication@ constructs an @::OpenID::Consumer@ object and calls redirects the browser to @open_id_redirect_url@, which finally takes us to a Google login page (after some redirects within Google).
83 16 Peter Amstutz
# Google presents the user with a login page, and directs the browser to the sso-server at @/users/auth/google/callback@ after a successful login (after more redirects within Google)
84 1 Peter Amstutz
# In sso-provider, Omniauth intercepts this and calls @callback_phase@ in omniauth-openid
85
## The callback phase calls @openid_response@
86
## @openid_response@ creates a rack layer with @Rack::OpenID.new@ (the @rack-openid@ gem) executes it with @call@.  This provisions the Rack environment with info from the OpenID callback.
87
## Request handling continues to sso-provider where it routes to @Users::OmniauthCallbacksController#google@
88
## This calls @find_for_open_id@ on the @User@ model which finds a user record with a matching identity url, or creates and saves a new user record with the identity url.
89
## The @google@ callback also saves the first_name and last_name of the user.
90
## This calls @sign_in_and_redirect@ defined in @devise/lib/devise/controllers/helpers.rb@
91
## This calls set_user in Warden, which uses @Warden::SessionSerializer@ to save the user associated with the session
92 15 Peter Amstutz
## This redirects the browser to @stored_location_for@ which returns the value of @user_return_to@ in the session, which is @/auth/josh_id/authorize@ from step 5.
93
# In sso-provider, @/auth/josh_id/authorize@ routes to @AuthController#authorize@, and passes @authenticate_user!@ because the there is now a user associated with the session.
94
## @authorize@ builds an @AccessGrant@ using the @state@ token from the request
95
## @authorize@ redirects the browser to @params[:redirect_uri]@ which is @/auth/josh_id/callback@ (this is the oauth callback on the API server, saved from step 5)
96
# In API server, @/auth/josh_id/callback@ is intercepted by @OmniAuth::Strategies::OAuth2@ and calls @callback_phase@.
97
## @OmniAuth::Strategies::OAuth2@ creates a @::OAuth2::Client@ and calls @get_token@ to convert the "authorization_code" into a "oauth_token"
98
## The API server makes a request to the sso-provider at @/oauth/token@
99
# In the sso-provider, @/oauth/token@ is routed to @AuthController#access_token@
100
## This first checks @Client.authenticate@ which verifies that @client_id@ (@app_id@) and @client_secret@ (@app_secret@) are recognized
101
## Next it calls @AccessGrant.authenticate@ which verifies that @code@ and @client_id@ are recognized
102
## This renders an JSON API response with the @access_token@, @refresh_token@ and @expires_in@ fields which are returned to the API server.
103
# The API server, back in OmniAuth::Strategies::OAuth2, receives the response and saves the @access_token@.
104
## Request processing continues and routes to @UserSessionsController#create@
105
## API server gets the OmniAuth object and looks up the Arvados API user by @identity_url@
106
## The session is provisioned with the Arvados user id
107
## @if params.has_key?(:return_to)@ then it calls @send_api_token_to@ 
108
## @send_api_token_to@ creates a new ApiClientAuthorization
109
## It redirects the browser to the @:return_to@  after adding @api_token=xxx@ to the query portion of return_to
110
# The browser is finally redirected to workbench to with @api_token=xxx@
111
## Workbench adds the api_token to the session, and redirects the browser one last time to the same location with @?api_token@ stripped from the query portion.
112 1 Peter Amstutz
113
h2. Questions
114
115
* What is workbench's "secret_token" for?