title: Install Single Sign On (SSO) server
...
+h2(#dependencies). Install dependencies
+
+Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.
+
+h2(#install). Install SSO server
+
+h3. Get SSO server code and create database
+
<notextile>
-<pre><code>~$ <span class="userinput">git clone https://github.com/curoverse/sso-devise-omniauth-provider.git</span>
+<pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
+~$ <span class="userinput">git clone https://github.com/curoverse/sso-devise-omniauth-provider.git</span>
~$ <span class="userinput">cd sso-devise-omniauth-provider</span>
~/sso-devise-omniauth-provider$ <span class="userinput">bundle install</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">rake db:create</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">rake db:migrate</span>
+~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:create</span>
+~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:migrate</span>
+</code></pre>
+</notextile>
+
+h3. Configure Rails secret
+
+Create a secret:
+
+<notextile>
+<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/initializers/secret_token.rb.example config/initializers/secret_token.rb</span>
~/sso-devise-omniauth-provider$ <span class="userinput">rake secret</span>
+zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+</code></pre>
+</notextile>
+
+Edit @config/initializers/secret_token.rb@ to set @config.secret_token@ to the string produced by @rake secret@.
+
+h3. Configure upstream authentication provider
+
+This will enable users to log in using their existing Google accounts. If you don't want to use Google for account services, you can also "add accounts manually.":#manual-accounts
+
+<notextile>
+<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/environments/production.rb.example config/environments/production.rb</span>
+</code></pre>
+</notextile>
+
+Edit @config/environments/production.rb@ to set @config.google_oauth2_client_id@ and @config.google_oauth2_client_secret@. See "Omniauth Google OAuth2 gem documentation":https://github.com/zquestz/omniauth-google-oauth2 and "Using OAuth 2.0 to Access Google APIs":https://developers.google.com/accounts/docs/OAuth2 for information about using the "Google Developers Console":https://console.developers.google.com to get a Google client id and client secret.
+
+h3(#client). Create arvados-server client
+
+Use @rails console@ to create a @Client@ record that will be used by the Arvados API server. The values of @app_id@ and @app_secret@ correspond to the @APP_ID@ and @APP_SECRET@ that must be set in in "Setting up Omniauth in the API server.":install-api-server.html#omniauth
+
+<notextile>
+<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">rake secret</span>
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-~/sso-devise-omniauth-provider$ <span class="userinput">rails console</span>
-irb(main):001:0> <span class="userinput">c = Client.new</span>
-irb(main):002:0> <span class="userinput">c.name = "joshid"</span>
-irb(main):003:0> <span class="userinput">c.app_id = "arvados-server"</span>
-irb(main):004:0> <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
-irb(main):005:0> <span class="userinput">c.save!</span>
-irb(main):006:0> <span class="userinput">quit</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">rails server --port=3002</span>
+~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
+:001 > <span class="userinput">c = Client.new</span>
+:002 > <span class="userinput">c.name = "joshid"</span>
+:003 > <span class="userinput">c.app_id = "arvados-server"</span>
+:004 > <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
+:005 > <span class="userinput">c.save!</span>
+:006 > <span class="userinput">quit</span>
+</code></pre>
+</notextile>
+
+h2(#manual-accounts). Adding user accounts manually
+
+Instead of relying on an upstream authentication such as Google, you can create accounts on the SSO server manually.
+
+<notextile>
+<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
+:001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
+:002 > <span class="userinput">user.password = "passw0rd"</span>
+:003 > <span class="userinput">user.save!</span>
+:004 > <span class="userinput">quit</span>
+</code></pre>
+</notextile>
+
+To log in using a manually created account:
+
+# Go to https://auth.your.domain/users/sign_in
+# Enter the email address and password and click on "Sign in"
+# You will arrive at a page "You are now signed in as test@example.com"
+# Go to https://workbench.@uuid_prefix@.your.domain/
+# Click on the Workbench "Log in" button.
+# You should now be logged in to Workbench. Confirm by looking for the email address displayed in the upper right.
+
+h2. Start the SSO server
+
+h3. Run a simple standalone server
+
+You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
+
+<notextile>
+<pre><code>~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rails server</span>
</code></pre>
</notextile>
+
+h3. Production environment
+
+As a Ruby on Rails application, the SSO server should be compatible with any Ruby application server that supports Rack applications. We recommend "Passenger":https://www.phusionpassenger.com/ to run the SSO server in production.