Install the Single Sign On (SSO) server

Note:

Skip this section if you are using Google login via arvados-controller.

Install dependencies
Set up database
Update config.yml
Configure the SSO server
Update Nginx configuration
Install arvados-sso-server
Create arvados-server client record
Restart the API server and controller

Install dependencies

Install PostgreSQL
Install Ruby and Bundler Important! The Single Sign On server only supports Ruby 2.3, to avoid version conflicts we recommend installing it on a different server from the API server. When installing Ruby, ensure that you get the right version by installing the “ruby2.3” package, or by using RVM with --ruby=2.3
Install nginx
Install Phusion Passenger

Set up the database

Start a shell for the postgres user:
```
# su postgres
```
Generate a new database password:
```
postgres$ tr -dc 0-9a-zA-Z </dev/urandom | head -c25; echo
yourgeneratedpassword
```
Record this. You’ll need it when you set up the Rails server later.

Create a database user with the password you generated:

postgres$ createuser --encrypted --no-createrole --no-superuser --pwprompt arvados_sso
  Enter password for new role: yourgeneratedpassword
  Enter it again: yourgeneratedpassword

Create a database owned by the new user:

postgres$ createdb arvados_sso_production -T template0 -E UTF8 -O arvados_sso

Exit the postgres user shell:
```
postgres$ exit
```

Now create /etc/arvados/sso/database.yml

production:
  adapter: postgresql
  encoding: utf8
  database: arvados_sso_production
  username: arvados_sso
  password: $password
  host: localhost
  template: template0

Update config.yml

    Services:
      SSO:
        ExternalURL: auth.ClusterID.example.com
    Login:
      ProviderAppID: "arvados-server"
      ProviderAppSecret: $app_secret

Generate ProviderAppSecret:

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

Configure the SSO server

The SSO server runs from the /var/www/arvados-sso/current/ directory. The files /var/www/arvados-sso/current/config/application.yml and /var/www/arvados-sso/current/config/database.yml will be 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.

Create /etc/arvados/sso/application.yml and add these keys:

production:
  uuid_prefix: xxxxx
  secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz

uuid_prefix

Most of the time, you want this to be the same as your ClusterID. If not, generate a new one from the command line listed previously.

secret_token

Generate a new secret token for signing cookies:

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

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. Choose your authentication method and add the listed configuration items to the production section.

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.

~$ 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

First, visit Setting up Google auth.

Next, 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--"-

Update nginx configuration

Use a text editor to create a new file /etc/nginx/conf.d/arvados-sso.conf with the following configuration. Options that need attention are marked in red.

server {
  listen       auth.ClusterID.example.com:443 ssl;
  server_name  auth.ClusterID.example.com;

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

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

  passenger_enabled on;

  # If you are using RVM, uncomment the line below.
  # If you're using system ruby, leave it commented out.
  #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
}

Install arvados-sso-server package

Centos 7

# yum install arvados-sso-server

Debian and Ubuntu

# apt-get --no-install-recommends arvados-sso-server

Create arvados-server client record

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

~$ 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 will be copied to Login.ProviderAppID and Login.ProviderAppSecret in config.yml.

:001 > c = Client.new
:002 > c.name = "joshid"
:003 > c.app_id = "arvados-server"
:004 > c.app_secret = "the value of Login.ProviderAppSecret"
:005 > c.save!
:006 > quit

Restart the API server and controller

After adding the SSO server to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.

# systemctl restart nginx arvados-controller

Previous: Set up web based login Next: Install Workbench