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