--- layout: default navsection: installguide title: Install the Single Sign On (SSO) server ... {% comment %} Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} {% include 'notebox_begin_warning' %} Skip this section if you are using Google login via @arvados-controller@. {% include 'notebox_end' %} # "Install dependencies":#dependencies # "Set up database":#database-setup # "Update config.yml":#update-config # "Configure the SSO server":#create-application-yml # "Update Nginx configuration":#update-nginx # "Install arvados-sso-server":#install-packages # "Create arvados-server client record":#client # "Restart the API server and controller":#restart-api h2(#dependencies). Install dependencies # "Install PostgreSQL":install-postgresql.html # "Install Ruby and Bundler":ruby.html 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":nginx.html # "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html h2(#database-setup). Set up the database {% assign service_role = "arvados_sso" %} {% assign service_database = "arvados_sso_production" %} {% assign use_contrib = false %} {% include 'install_postgres_database' %} 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
h2(#update-config). 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
h2(#create-application-yml). 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
h3(#uuid_prefix). 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. h3(#secret_token). secret_token Generate a new secret token for signing cookies:
~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
h3(#authentication_methods). 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. h4(#local_accounts). 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":http://guides.rubyonrails.org/configuring.html#configuring-action-mailer If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console. {% include 'install_rails_command' %} Enter the following commands at the console.
:001 > user = User.new(:email => "test@example.com")
:002 > user.password = "passw0rd"
:003 > user.save!
:004 > quit
h4(#ldap). 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"
table(table). |_. 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| h4(#google). Google authentication First, visit "Setting up Google auth.":google-auth.html 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--"-
h2(#update-nginx). 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;
}
h2(#install-packages). Install arvados-sso-server package h3. Centos 7
# yum install arvados-sso-server
h3. Debian and Ubuntu
# apt-get --no-install-recommends arvados-sso-server
h2(#client). Create arvados-server client record {% assign railshost = "" %} {% assign railsdir = "/var/www/arvados-sso/current" %} Use @rails console@ to create a @Client@ record that will be used by the Arvados API server. {% include 'install_rails_command' %} 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
h2(#restart-api). 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