Install the Single Sign On (SSO) server

Install prerequisites

The Arvados package repository includes an SSO server package that can help automate much of the deployment.

Install Ruby and Bundler

Ruby 2.3 is recommended; Ruby 2.1 is also known to work.

Option 1: Install with RVM

sudo gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | sudo bash -s stable --ruby=2.3

Either log out and log back in to activate RVM, or explicitly load it in all open shells like this:

source /usr/local/rvm/scripts/rvm

Once RVM is activated in your shell, install Bundler:

~$ gem install bundler

Option 2: Install from source

Install prerequisites for Debian 8:

sudo apt-get install \
    bison build-essential gettext libcurl3 libcurl3-gnutls \
    libcurl4-openssl-dev libpcre3-dev libreadline-dev \
    libssl-dev libxslt1.1 zlib1g-dev

Install prerequisites for CentOS 7:

sudo yum install \
    libyaml-devel glibc-headers autoconf gcc-c++ glibc-devel \
    patch readline-devel zlib-devel libffi-devel openssl-devel \
    make automake libtool bison sqlite-devel tar

Install prerequisites for Ubuntu 12.04 or 14.04:

sudo apt-get install \
    gawk g++ gcc make libc6-dev libreadline6-dev zlib1g-dev libssl-dev \
    libyaml-dev libsqlite3-dev sqlite3 autoconf libgdbm-dev \
    libncurses5-dev automake libtool bison pkg-config libffi-dev curl

Build and install Ruby:

mkdir -p ~/src
cd ~/src
curl -f http://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz | tar xz
cd ruby-2.3.3
./configure --disable-install-rdoc
make
sudo make install

sudo -i gem install bundler

Set up a Web server

For best performance, we recommend you use Nginx as your Web server frontend with a Passenger backend to serve the SSO server. The Passenger team provides Nginx + Passenger installation instructions.

Follow the instructions until you see the section that says you are ready to deploy your Ruby application on the production server.

Install the SSO server

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

~$ sudo apt-get install arvados-sso-server

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

~$ sudo yum install arvados-sso-server

Configure the SSO server

The package has installed three configuration files in /etc/arvados/sso:

/etc/arvados/sso/application.yml
/etc/arvados/sso/database.yml
/etc/arvados/sso/production.rb

The SSO server runs from the /var/www/arvados-sso/current/ directory. The files /var/www/arvados-sso/current/config/application.yml, /var/www/arvados-sso/current/config/database.yml and /var/www/arvados-sso/current/config/environments/production.rb are symlinked to the configuration files in /etc/arvados/sso/.

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. Local configuration goes in /etc/arvados/sso/application.yml, do not edit config/application.default.yml.

uuid_prefix

Generate a uuid prefix for the single sign on service. This prefix is used to identify user records as originating from this site. It must be exactly 5 lowercase ASCII letters and/or digits. You may use the following snippet to generate a uuid prefix:

~$ ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'
abcde

Edit /etc/arvados/sso/application.yml and set uuid_prefix in the “common” section.

secret_token

Generate a new secret token for signing cookies:

~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz

Edit /etc/arvados/sso/application.yml and set secret_token in the “common” section.

There are other configuration options in /etc/arvados/sso/application.yml. See the Authentication methods section below for more details.

Set up the database

Configure the SSO server to connect to your database by updating /etc/arvados/sso/database.yml. Replace the xxxxxxxx database password placeholder with the password you generated during database setup. Be sure to update the production section.

~$ editor /etc/arvados/sso/database.yml

Reconfigure the package

Now that all your configuration is in place, rerun the arvados-sso-server package configuration to install necessary Ruby Gems and other server dependencies. On Debian-based systems:

~$ sudo dpkg-reconfigure arvados-sso-server

On Red Hat-based systems:

~$ sudo yum reinstall arvados-sso-server

You only need to do this manual step once, after initial configuration. When you make configuration changes in the future, you just need to restart Nginx for them to take effect.

Create arvados-server client

Use rails console to create a Client record that will be used by the Arvados API server.

Change webserver-user to the user that runs your web server process. If you install Phusion Passenger as we recommend, this is www-data on Debian-based systems, and nginx on Red Hat-based systems.

Using RVM:

~$ cd /var/www/arvados-sso/current
/var/www/arvados-sso/current$ sudo -u webserver-user RAILS_ENV=production `which rvm-exec` default bundle exec rails console

Not using RVM:

~$ cd /var/www/arvados-sso/current
/var/www/arvados-sso/current$ sudo -u webserver-user RAILS_ENV=production bundle exec rails console

Enter the following commands at the console. The values that appear after you assign app_id and app_secret correspond to the values for sso_app_id and sso_app_secret, respectively, in the API server’s SSO settings.

:001 > c = Client.new
:002 > c.name = "joshid"
:003 > c.app_id = "arvados-server"
:004 > c.app_secret = rand(2**400).to_s(36)
=> "save this string for your API server's sso_app_secret"
:005 > c.save!
:006 > quit

Configure your web server

Edit the http section of your Nginx configuration to run the Passenger server and act as a frontend for it. You might add a block like the following, adding SSL and logging parameters to taste:

server {
  listen 127.0.0.1:8900;
  server_name localhost-sso;

  root   /var/www/arvados-sso/current/public;
  index  index.html;

  passenger_enabled on;
  # If you're not using RVM, comment out the line below.
  passenger_ruby /usr/local/rvm/wrappers/default/ruby;
}

upstream sso {
  server     127.0.0.1:8900  fail_timeout=10s;
}

proxy_http_version 1.1;

server {
  listen       [your public IP address]:443 ssl;
  server_name  auth.your.domain;

  ssl on;
  ssl_certificate     /YOUR/PATH/TO/cert.pem;
  ssl_certificate_key /YOUR/PATH/TO/cert.key;

  index  index.html;

  location / {
    proxy_pass            http://sso;
    proxy_redirect        off;
    proxy_connect_timeout 90s;
    proxy_read_timeout    300s;

    proxy_set_header      X-Forwarded-Proto https;
    proxy_set_header      Host $http_host;
    proxy_set_header      X-Real-IP $remote_addr;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Finally, restart Nginx and your Arvados SSO server should be up and running. You can verify that by visiting the URL you configured your Nginx web server to listen on in the server section above (port 443). Read on if you want to configure your Arvados SSO server to use a different authentication backend.

Authentication methods

Authentication methods are configured in application.yml. Currently three authentication methods are supported: local accounts, LDAP, and Google+. If neither Google+ nor LDAP are enabled, the SSO server defaults to local user accounts. Only one authentication mechanism should be in use at a time.

Local account authentication

There are two configuration options for local accounts:

  # 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 (otherwise users are activated immediately.)
  require_email_confirmation: false

For more information about configuring backend support for sending email (required to send email confirmations) see Configuring Action Mailer

If allow_account_registration is false, you may manually create local accounts on the SSO server from the Rails console.

Change webserver-user to the user that runs your web server process. If you install Phusion Passenger as we recommend, this is www-data on Debian-based systems, and nginx on Red Hat-based systems.

Using RVM:

~$ cd /var/www/arvados-sso/current
/var/www/arvados-sso/current$ sudo -u webserver-user RAILS_ENV=production `which rvm-exec` default bundle exec rails console

Not using RVM:

~$ cd /var/www/arvados-sso/current
/var/www/arvados-sso/current$ sudo -u webserver-user RAILS_ENV=production bundle exec rails console

Enter the following commands at the console.

:001 > user = User.new(:email => "test@example.com")
:002 > user.password = "passw0rd"
:003 > user.save!
:004 > quit

LDAP authentication

The following options are available to configure LDAP authentication. Note that you must preserve the indentation of the fields listed under use_ldap.

  use_ldap:
    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"

Option	Description
title	Title displayed to the user on the login page
host	LDAP server hostname
port	LDAP server port
method	One of “plain”, “ssl”, “tls”
base	Directory lookup base
uid	User id field used for directory lookup
email_domain	Strip off specified email domain from login and perform lookup on bare username
bind_dn	If required by server, username to log with in before performing directory lookup
password	If required by server, password to log with before performing directory lookup

Google+ authentication

In order to use Google+ authentication, you must use the Google Developers Console to create a set of client credentials.

1. Go to the Google Developers Console and select or create a project; this will take you to the project page.
2. On the sidebar, click on APIs & auth then select APIs.
   1. Search for Contacts API and click on Enable API.
   2. Search for Google+ API and click on Enable API.
3. On the sidebar, click on Credentials; under OAuth click on Create new Client ID to bring up the Create Client ID dialog box.
4. Under Application type select Web application.
5. If the authorization origins are not displayed, clicking on Create Client ID will take you to Consent screen settings.
   1. On consent screen settings, enter the appropriate details and click on Save.
   2. This will return you to the Create Client ID dialog box.
6. You must set the authorization origins. Edit auth.your.domain to the appropriate hostname that you will use to access the SSO service:
   1. JavaScript origin should be https://auth.your.domain/
   2. Redirect URI should be https://auth.your.domain/users/auth/google_oauth2/callback
7. Copy the values of Client ID and Client secret from the Google Developers Console into the Google section of config/application.yml, like this:

  # Google API tokens required for OAuth2 login.
  google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
  google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-

---

Previous: Install Keep-balance Next: Install Workbench