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 h2(#dependencies). Install prerequisites
  13
  14 The Arvados package repository includes an SSO server package that can help automate much of the deployment.
  15
  16 h3(#install_ruby_and_bundler). Install Ruby and Bundler
  17
  18 {% include 'install_ruby_and_bundler_sso' %}
  19
  20 h3(#install_web_server). Set up a Web server
  21
  22 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":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
  23
  24 Follow the instructions until you see the section that says you are ready to deploy your Ruby application on the production server.
  25
  26 h2(#install). Install the SSO server
  27
  28 On a Debian-based system, install the following package:
  29
  30 <notextile>
  31 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-sso-server</span>
  32 </code></pre>
  33 </notextile>
  34
  35 On a Red Hat-based system, install the following package:
  36
  37 <notextile>
  38 <pre><code>~$ <span class="userinput">sudo yum install arvados-sso-server</span>
  39 </code></pre>
  40 </notextile>
  41
  42 h2(#configure). Configure the SSO server
  43
  44 The package has installed three configuration files in @/etc/arvados/sso@:
  45
  46 <notextile>
  47 <pre><code>/etc/arvados/sso/application.yml
  48 /etc/arvados/sso/database.yml
  49 /etc/arvados/sso/production.rb
  50 </code></pre>
  51 </notextile>
  52
  53 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/@.
  54
  55 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.
  56
  57 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@.
  58
  59 h3(#uuid_prefix). uuid_prefix
  60
  61 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:
  62
  63 <notextile>
  64 <pre><code>~$ <span class="userinput">ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'</span>
  65 abcde
  66 </code></pre></notextile>
  67
  68 Edit @/etc/arvados/sso/application.yml@ and set @uuid_prefix@ in the "common" section.
  69
  70 h3(#secret_token). secret_token
  71
  72 Generate a new secret token for signing cookies:
  73
  74 <notextile>
  75 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  76 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  77 </code></pre></notextile>
  78
  79 Edit @/etc/arvados/sso/application.yml@ and set @secret_token@ in the "common" section.
  80
  81 There are other configuration options in @/etc/arvados/sso/application.yml@. See the "Authentication methods":install-sso.html#authentication_methods section below for more details.
  82
  83 h2(#database). Set up the database
  84
  85 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":install-postgresql.html#sso. Be sure to update the @production@ section.
  86
  87 <notextile>
  88 <pre><code>~$ <span class="userinput">editor /etc/arvados/sso/database.yml</span>
  89 </code></pre></notextile>
  90
  91 h2(#reconfigure_package). Reconfigure the package
  92
  93 {% assign railspkg = "arvados-sso-server" %}
  94 {% include 'install_rails_reconfigure' %}
  95
  96 h2(#client). Create arvados-server client
  97
  98 {% assign railshost = "" %}
  99 {% assign railsdir = "/var/www/arvados-sso/current" %}
 100 Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  {% include 'install_rails_command' %}
 101
 102 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":install-api-server.html#omniauth.
 103
 104 <notextile>
 105 <pre><code>:001 &gt; <span class="userinput">c = Client.new</span>
 106 :002 &gt; <span class="userinput">c.name = "joshid"</span>
 107 :003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
 108 :004 &gt; <span class="userinput">c.app_secret = rand(2**400).to_s(36)</span>
 109 =&gt; "<strong>save this string for your API server's sso_app_secret</strong>"
 110 :005 &gt; <span class="userinput">c.save!</span>
 111 :006 &gt; <span class="userinput">quit</span>
 112 </code></pre>
 113 </notextile>
 114
 115 h2(#configure_web_server). Configure your web server
 116
 117 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:
 118
 119 <notextile>
 120 <pre><code>server {
 121   listen 127.0.0.1:8900;
 122   server_name localhost-sso;
 123
 124   root   /var/www/arvados-sso/current/public;
 125   index  index.html;
 126
 127   passenger_enabled on;
 128   # If you're not using RVM, comment out the line below.
 129   passenger_ruby /usr/local/rvm/wrappers/default/ruby;
 130 }
 131
 132 upstream sso {
 133   server     127.0.0.1:8900  fail_timeout=10s;
 134 }
 135
 136 proxy_http_version 1.1;
 137
 138 server {
 139   listen       <span class="userinput">[your public IP address]</span>:443 ssl;
 140   server_name  auth.<span class="userinput">your.domain</span>;
 141
 142   ssl on;
 143   ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
 144   ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
 145
 146   index  index.html;
 147
 148   location / {
 149     proxy_pass            http://sso;
 150     proxy_redirect        off;
 151     proxy_connect_timeout 90s;
 152     proxy_read_timeout    300s;
 153
 154     proxy_set_header      X-Forwarded-Proto https;
 155     proxy_set_header      Host $http_host;
 156     proxy_set_header      X-Real-IP $remote_addr;
 157     proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
 158   }
 159 }
 160 </code></pre>
 161 </notextile>
 162
 163 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.
 164
 165 h2(#authentication_methods). Authentication methods
 166
 167 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.
 168
 169 h3(#local_accounts). Local account authentication
 170
 171 There are two configuration options for local accounts:
 172
 173 <pre>
 174   # If true, allow new creation of new accounts in the SSO server's internal
 175   # user database.
 176   allow_account_registration: false
 177
 178   # If true, send an email confirmation before activating new accounts in the
 179   # SSO server's internal user database (otherwise users are activated immediately.)
 180   require_email_confirmation: false
 181 </pre>
 182
 183 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
 184
 185 If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console.  {% include 'install_rails_command' %}
 186
 187 Enter the following commands at the console.
 188
 189 <notextile>
 190 <pre><code>:001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
 191 :002 &gt; <span class="userinput">user.password = "passw0rd"</span>
 192 :003 &gt; <span class="userinput">user.save!</span>
 193 :004 &gt; <span class="userinput">quit</span>
 194 </code></pre>
 195 </notextile>
 196
 197 h3(#ldap). LDAP authentication
 198
 199 The following options are available to configure LDAP authentication.  Note that you must preserve the indentation of the fields listed under @use_ldap@.
 200
 201 <pre>
 202   use_ldap:
 203     title: Example LDAP
 204     host: ldap.example.com
 205     port: 636
 206     method: ssl
 207     base: "ou=Users, dc=example, dc=com"
 208     uid: uid
 209     email_domain: example.com
 210     #bind_dn: "some_user"
 211     #password: "some_password"
 212 </pre>
 213
 214 table(table).
 215 |_. Option|_. Description|
 216 |title |Title displayed to the user on the login page|
 217 |host  |LDAP server hostname|
 218 |port  |LDAP server port|
 219 |method|One of "plain", "ssl", "tls"|
 220 |base  |Directory lookup base|
 221 |uid   |User id field used for directory lookup|
 222 |email_domain|Strip off specified email domain from login and perform lookup on bare username|
 223 |bind_dn|If required by server, username to log with in before performing directory lookup|
 224 |password|If required by server, password to log with before performing directory lookup|
 225
 226 h3(#google). Google+ authentication
 227
 228 In order to use Google+ authentication, you must use the <a href="https://console.developers.google.com" target="_blank">Google Developers Console</a> to create a set of client credentials.
 229
 230 # Go to the <a href="https://console.developers.google.com" target="_blank">Google Developers Console</a> and select or create a project; this will take you to the project page.
 231 # On the sidebar, click on *APIs & auth* then select *APIs*.
 232 ## Search for *Contacts API* and click on *Enable API*.
 233 ## Search for *Google+ API* and click on *Enable API*.
 234 # On the sidebar, click on *Credentials*; under *OAuth* click on *Create new Client ID* to bring up the *Create Client ID* dialog box.
 235 # Under *Application type* select *Web application*.
 236 # If the authorization origins are not displayed, clicking on *Create Client ID* will take you to *Consent screen* settings.
 237 ## On consent screen settings, enter the appropriate details and click on *Save*.
 238 ## This will return you to the *Create Client ID* dialog box.
 239 # You must set the authorization origins.  Edit @auth.your.domain@ to the appropriate hostname that you will use to access the SSO service:
 240 ## JavaScript origin should be @https://auth.your.domain/@
 241 ## Redirect URI should be @https://auth.your.domain/users/auth/google_oauth2/callback@
 242 # Copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
 243
 244 <notextile>
 245 <pre><code>  # Google API tokens required for OAuth2 login.
 246   google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
 247   google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>