doc/install/install-sso.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the Single Sign On (SSO) server
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 {% include 'notebox_begin_warning' %}
  13 Skip this section if you are using Google login via @arvados-controller@.
  14 {% include 'notebox_end' %}
  15
  16 # "Install dependencies":#dependencies
  17 # "Set up database":#database-setup
  18 # "Update config.yml":#update-config
  19 # "Configure the SSO server":#create-application-yml
  20 # "Update Nginx configuration":#update-nginx
  21 # "Install arvados-sso-server":#install-packages
  22 # "Create arvados-server client record":#client
  23 # "Restart the API server and controller":#restart-api
  24
  25 h2(#dependencies). Install dependencies
  26
  27 # "Install PostgreSQL":install-postgresql.html
  28 # "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@
  29 # "Install nginx":nginx.html
  30 # "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
  31
  32 h2(#database-setup). Set up the database
  33
  34 {% assign service_role = "arvados_sso" %}
  35 {% assign service_database = "arvados_sso_production" %}
  36 {% assign use_contrib = false %}
  37 {% include 'install_postgres_database' %}
  38
  39 Now create @/etc/arvados/sso/database.yml@
  40
  41 <pre>
  42 production:
  43   adapter: postgresql
  44   encoding: utf8
  45   database: arvados_sso_production
  46   username: arvados_sso
  47   password: $password
  48   host: localhost
  49   template: template0
  50 </pre>
  51
  52 h2(#update-config). Update config.yml
  53
  54 <pre>
  55     Services:
  56       SSO:
  57         ExternalURL: auth.ClusterID.example.com
  58     Login:
  59       ProviderAppID: "arvados-server"
  60       ProviderAppSecret: $app_secret
  61 </pre>
  62
  63 Generate @ProviderAppSecret@:
  64
  65 <notextile>
  66 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  67 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  68 </code></pre></notextile>
  69
  70 h2(#create-application-yml). Configure the SSO server
  71
  72 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/@.
  73
  74 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.
  75
  76 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@.
  77
  78 Create @/etc/arvados/sso/application.yml@ and add these keys:
  79
  80 <pre>
  81 production:
  82   uuid_prefix: xxxxx
  83   secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  84 </pre>
  85
  86 h3(#uuid_prefix). uuid_prefix
  87
  88 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.
  89
  90 h3(#secret_token). secret_token
  91
  92 Generate a new secret token for signing cookies:
  93
  94 <notextile>
  95 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  96 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  97 </code></pre></notextile>
  98
  99 h3(#authentication_methods). Authentication methods
 100
 101 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.
 102
 103 h4(#local_accounts). Local account authentication
 104
 105 There are two configuration options for local accounts:
 106
 107 <pre>
 108   # If true, allow new creation of new accounts in the SSO server's internal
 109   # user database.
 110   allow_account_registration: false
 111
 112   # If true, send an email confirmation before activating new accounts in the
 113   # SSO server's internal user database (otherwise users are activated immediately.)
 114   require_email_confirmation: false
 115 </pre>
 116
 117 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
 118
 119 If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console.  {% include 'install_rails_command' %}
 120
 121 Enter the following commands at the console.
 122
 123 <notextile>
 124 <pre><code>:001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
 125 :002 &gt; <span class="userinput">user.password = "passw0rd"</span>
 126 :003 &gt; <span class="userinput">user.save!</span>
 127 :004 &gt; <span class="userinput">quit</span>
 128 </code></pre>
 129 </notextile>
 130
 131 h4(#ldap). LDAP authentication
 132
 133 The following options are available to configure LDAP authentication.  Note that you must preserve the indentation of the fields listed under @use_ldap@.
 134
 135 <pre>
 136   use_ldap:
 137     title: Example LDAP
 138     host: ldap.example.com
 139     port: 636
 140     method: ssl
 141     base: "ou=Users, dc=example, dc=com"
 142     uid: uid
 143     email_domain: example.com
 144     #bind_dn: "some_user"
 145     #password: "some_password"
 146 </pre>
 147
 148 table(table).
 149 |_. Option|_. Description|
 150 |title |Title displayed to the user on the login page|
 151 |host  |LDAP server hostname|
 152 |port  |LDAP server port|
 153 |method|One of "plain", "ssl", "tls"|
 154 |base  |Directory lookup base|
 155 |uid   |User id field used for directory lookup|
 156 |email_domain|Strip off specified email domain from login and perform lookup on bare username|
 157 |bind_dn|If required by server, username to log with in before performing directory lookup|
 158 |password|If required by server, password to log with before performing directory lookup|
 159
 160 h4(#google). Google authentication
 161
 162 First, visit "Setting up Google auth.":google-auth.html
 163
 164 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:
 165
 166 <notextile>
 167 <pre><code>  # Google API tokens required for OAuth2 login.
 168   google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
 169   google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>
 170
 171 h2(#update-nginx). Update nginx configuration
 172
 173 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 <span class="userinput">red</span>.
 174
 175 <notextile>
 176 <pre><code>server {
 177   listen       <span class="userinput">auth.ClusterID.example.com</span>:443 ssl;
 178   server_name  <span class="userinput">auth.ClusterID.example.com</span>;
 179
 180   ssl on;
 181   ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
 182   ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
 183
 184   root   /var/www/arvados-sso/current/public;
 185   index  index.html;
 186
 187   passenger_enabled on;
 188
 189   # <span class="userinput">If you are using RVM, uncomment the line below.</span>
 190   # <span class="userinput">If you're using system ruby, leave it commented out.</span>
 191   #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
 192 }
 193 </code></pre>
 194 </notextile>
 195
 196 h2(#install-packages). Install arvados-sso-server package
 197
 198 h3. Centos 7
 199
 200 <notextile>
 201 <pre><code># <span class="userinput">yum install arvados-sso-server</span>
 202 </code></pre>
 203 </notextile>
 204
 205 h3. Debian and Ubuntu
 206
 207 <notextile>
 208 <pre><code># <span class="userinput">apt-get --no-install-recommends arvados-sso-server</span>
 209 </code></pre>
 210 </notextile>
 211
 212 h2(#client). Create arvados-server client record
 213
 214 {% assign railshost = "" %}
 215 {% assign railsdir = "/var/www/arvados-sso/current" %}
 216 Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  {% include 'install_rails_command' %}
 217
 218 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@.
 219
 220 <notextile>
 221 <pre><code>:001 &gt; <span class="userinput">c = Client.new</span>
 222 :002 &gt; <span class="userinput">c.name = "joshid"</span>
 223 :003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
 224 :004 &gt; <span class="userinput">c.app_secret = "the value of Login.ProviderAppSecret"</span>
 225 :005 &gt; <span class="userinput">c.save!</span>
 226 :006 &gt; <span class="userinput">quit</span>
 227 </code></pre>
 228 </notextile>
 229
 230 h2(#restart-api). Restart the API server and controller
 231
 232 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.
 233
 234 <notextile>
 235 <pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
 236 </code></pre>
 237 </notextile>