Workbench authentication process¶

1. 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.
2. 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.
3. In API server, the 'login' endpoint goes to UserSessionsController#login in the API server. This redirects the browser to /auth/joshid?return_to=xxx
4. In API server, /auth/joshid is intercepted by the OmniAuth Rack middleware and invokes the josh_id OmniAuth strategy.
   1. The josh_id OmniAuth strategy is implemented in arvados/services/api/lib/josh_id.rb and is a subclass of OmniAuth::Strategies::OAuth2
   2. 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
5. 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)
   1. devise :omniauthable, :omniauth_providers => [:google] configures sso-provider/app/models/user.rb
   2. authenticate_user! is not explicitly defined but instead monkey patched into the controller in devise/lib/devise/controllers/helper.rb
   3. authenticate_user! calls warden.authenticate! (warden/lib/warden/proxy.rb) with a scope of :user (warden is another Rack-based authentication gem)
   4. 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
   5. 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)
6. In sso-provider /users/sign_in routes to the SSO SessionsController#new which subclasses Devise::SessionsController
   1. SessionsController#new redirects the browser to /users/auth/google
7. In sso-provider, OmniAuth intercepts /users/auth/google
   1. OmniAuth is configured with a path prefix of /users/auth by devise
   2. sso-provider/config/initializers/devise.rb configures a :open_id omniauth strategy named of 'google'
   3. This enters the request phase at omniauth-open-id/lib/omniauth/strategies/open_id.rb
   4. This creates a rack layer with Rack::OpenID.new (the rack-openid gem) executes it with call
   5. The Rack layer passes through the request to the underlying @app and checks for a 401 response code, if so it calls begin_authentication
   6. 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).
8. Google directs the browser to the sso-server at /users/auth/google/callback after a successful login (after more redirects within Google)
9. In sso-provider, Omniauth intercepts this and calls callback_phase in omniauth-openid
   1. The callback phase calls openid_response
   2. 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.
   3. Request handling continues to sso-provider where it routes to Users::OmniauthCallbacksController#google
   4. 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.
   5. The google callback also saves the first_name and last_name of the user.
   6. This calls sign_in_and_redirect defined in devise/lib/devise/controllers/helpers.rb
   7. This calls set_user in Warden, which uses Warden::SessionSerializer to save the user associated with the session
   8. 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.
10. 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.
    1. authorize builds an AccessGrant using the state token from the request
    2. 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)
11. In API server, /auth/josh_id/callback is intercepted by OmniAuth::Strategies::OAuth2 and calls callback_phase.
    1. OmniAuth::Strategies::OAuth2 creates a ::OAuth2::Client and calls get_token to convert the "authorization_code" into a "oauth_token"
    2. The API server makes a request to the sso-provider at /oauth/token
12. In the sso-provider, /oauth/token is routed to AuthController#access_token
    1. This first checks Client.authenticate which verifies that client_id (app_id) and client_secret (app_secret) are recognized
    2. Next it calls AccessGrant.authenticate which verifies that code and client_id are recognized
    3. This renders an JSON API response with the access_token, refresh_token and expires_in fields which are returned to the API server.
13. The API server, back in OmniAuth::Strategies::OAuth2, receives the response and saves the access_token.
    1. Request processing continues and routes to UserSessionsController#create
    2. API server gets the OmniAuth object and looks up the Arvados API user by identity_url
    3. The session is provisioned with the Arvados user id
    4. if params.has_key?(:return_to) then it calls send_api_token_to
    5. send_api_token_to creates a new ApiClientAuthorization
    6. It redirects the browser to the :return_to after adding api_token=xxx to the query portion of return_to
14. The browser is finally redirected to workbench to with api_token=xxx
    1. 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.

Questions¶

• What is workbench's "secret_token" for?