Merge branch '6264-cwl-runner' closes #6264

[arvados.git] / doc / install / install-sso.html.textile.liquid

---
layout: default
navsection: installguide
title: Install Single Sign On (SSO) server
...

h2(#dependencies). Install dependencies

Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.

On a Debian-based system, install the following packages:

<notextile>
<pre><code>~$ <span class="userinput">sudo apt-get install git libpq-dev postgresql</span>
</code></pre>
</notextile>

On a Red Hat-based system, install the following packages:

<notextile>
<pre><code>~$ <span class="userinput">sudo yum install git postgresql postgresql-devel</span>
</code></pre>
</notextile>

{% include 'notebox_begin' %}
If your distribution offers PostgreSQL 8, consider using Software Collections to install postgresql92 and postgresql92-postgresql-devel instead, as described on the "API server installation page":install-api-server.html.
{% include 'notebox_end' %}

h2(#install). Install SSO server

h3. Get SSO server code and run bundle

<notextile>
<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</span>
</code></pre></notextile>

h2. Configure the SSO server

First, copy the example configuration file:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
</code></pre></notextile>

The SSO server reads the @config/application.yml@ file, as well as the @config/application.defaults.yml@ file. Values in @config/application.yml@ take precedence over the defaults that are defined in @config/application.defaults.yml@. The @config/application.yml.example@ file is not read by the SSO server and is provided for installation convenience, only.

Consult @config/application.default.yml@ for a full list of configuration options. Always put your local configuration in @config/application.yml@, never edit @config/application.default.yml@.

h3(#uuid_prefix). uuid_prefix

Define your @uuid_prefix@ in @config/application.yml@ by setting the @uuid_prefix@ field in the section for your environment.  This prefix is used for all database identifiers to identify the record as originating from this site.  It must be exactly 5 alphanumeric characters (lowercase ASCII letters and digits).

h3(#secret_token). secret_token

Generate a new secret token for signing cookies:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>

Then put that value in the @secret_token@ field.

h3(#authentication_methods). Authentication methods

Three authentication methods are supported: Google+, LDAP, and local accounts.

h3(#google). Google+ authentication

In order to use Google+ authentication, you must use the "Google Developers Console":https://console.developers.google.com to create a set of client credentials. In short:

* Enable the Contacts and Google+ APIs.
* Create an OAuth Client ID for a web application.
** JavaScript origins: @https://sso.example.com/@
** Redirect URIs: @https://sso.example.com/auth/google_oauth2/callback@

Copy the "Client ID" and "Client secret" values from the Google Developers Console into the Google section of @config/application.yml@, like this:

<notextile>
<pre><code>
  # Google API tokens required for OAuth2 login.
  #
  # See https://github.com/zquestz/omniauth-google-oauth2
  #
  # and https://developers.google.com/accounts/docs/OAuth2
  google_oauth2_client_id: "<span class="userinput">---YOUR---CLIENT---ID---HERE---</span>"
  google_oauth2_client_secret: "<span class="userinput">---YOUR---CLIENT---SECRET---HERE---</span>"

  # Set this to your OpenId 2.0 realm to enable migration from Google OpenId
  # 2.0 to Google OAuth2 OpenId Connect (Google will provide OpenId 2.0 user
  # identifiers via the openid.realm parameter in the OAuth2 flow until 2017).
  google_openid_realm: <span class="userinput">false</span></code></pre></notextile>

h3(#ldap). LDAP authentication

LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@.

<pre>
  # Enable LDAP support.
  #
  # If you want to use LDAP, you need to provide
  # the following set of fields under the use_ldap key.
  #
  # use_ldap: false
  #   title: Example LDAP
  #   host: ldap.example.com
  #   port: 636
  #   method: ssl
  #   base: "ou=Users, dc=example, dc=com"
  #   uid: uid
  #   email_domain: example.com
  #   #bind_dn: "some_user"
  #   #password: "some_password"
  use_ldap: false
</pre>

h3(#local_accounts). Local account authentication

If neither Google OAuth2 nor LDAP are enabled, the SSO server automatically
falls back to local accounts. There are two configuration options for local
accounts:

<pre>
  # If true, allow new creation of new accounts in the SSO server's internal
  # user database.
  allow_account_registration: false

  # If true, send an email confirmation before activating new accounts in the
  # SSO server's internal user database.
  require_email_confirmation: false
</pre>

You can also create local accounts on the SSO server from the rails console:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
:001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
:002 &gt; <span class="userinput">user.password = "passw0rd"</span>
:003 &gt; <span class="userinput">user.save!</span>
:004 &gt; <span class="userinput">quit</span>
</code></pre>
</notextile>

h2. Set up the database

Generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
abcdefghijklmnopqrstuvwxyz012345689
</code></pre></notextile>

Create a new database user with permission to create its own databases.

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso</span>
Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
Enter it again: <span class="userinput">paste-database-password-you-generated</span>
</code></pre></notextile>

Configure SSO server to connect to your database by creating and updating @config/database.yml@. Replace the @xxxxxxxx@ database password placeholders with the new password you generated above.

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/database.yml.sample config/database.yml</span>
~/sso-devise-omniauth-provider$ <span class="userinput">edit config/database.yml</span>
</code></pre></notextile>

Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:setup</span>
</code></pre></notextile>

Alternatively, if the database user you intend to use for the SSO server is not allowed to create new databases, you can create the database first and then populate it with rake. Be sure to adjust the database name if you are using the @development@ environment. This sequence of commands is functionally equivalent to the rake db:setup command above:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">su postgres createdb arvados_sso_production -E UTF8 -O arvados_sso</span>
~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:schema:load</span>
~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:seed</span>
</code></pre></notextile>

h2(#client). Generate assets

If you are running in the production environment, you'll want to generate the assets:

<notextile>
<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake assets:precompile</span>
</code></pre>
</notextile>

h2(#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">ruby -e 'puts rand(2**400).to_s(36)'</span>
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
:001 &gt; <span class="userinput">c = Client.new</span>
:002 &gt; <span class="userinput">c.name = "joshid"</span>
:003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
:004 &gt; <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
:005 &gt; <span class="userinput">c.save!</span>
:006 &gt; <span class="userinput">quit</span>
</code></pre>
</notextile>

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>~/sso-devise-omniauth-provider$ <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.