3 navsection: installguide
4 title: Install the Single Sign On (SSO) server
7 h2(#dependencies). Install prerequisites
9 The Arvados package repository includes an SSO server package that can help automate much of the deployment.
11 h3(#install_ruby_and_bundler). Install Ruby and Bundler
13 {% include 'install_ruby_and_bundler' %}
15 h3(#install_web_server). Set up a Web server
17 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.
19 Follow the instructions until you see the section that says you are ready to deploy your Ruby application on the production server.
21 h2(#install). Install the SSO server
23 On a Debian-based system, install the following package:
26 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-sso-server</span>
30 On a Red Hat-based system, install the following package:
33 <pre><code>~$ <span class="userinput">sudo yum install arvados-sso-server</span>
37 h2(#configure). Configure the SSO server
39 The package has installed three configuration files in @/etc/arvados/sso@:
42 <pre><code>/etc/arvados/sso/application.yml
43 /etc/arvados/sso/database.yml
44 /etc/arvados/sso/production.rb
48 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/@.
50 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.
52 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@.
54 h3(#uuid_prefix). uuid_prefix
56 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:
59 <pre><code>~$ <span class="userinput">ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'</span>
61 </code></pre></notextile>
63 Edit @/etc/arvados/sso/application.yml@ and set @uuid_prefix@ in the "common" section.
65 h3(#secret_token). secret_token
67 Generate a new secret token for signing cookies:
70 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
71 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
72 </code></pre></notextile>
74 Edit @/etc/arvados/sso/application.yml@ and set @secret_token@ in the "common" section.
76 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.
78 h2(#database). Set up the database
80 If PostgreSQL was newly installed as a dependency of the @arvados-sso-server@ package, you will need to start the service.
82 On a Debian-based system:
85 <pre><code>~$ <span class="userinput">sudo service postgresql start</span>
89 On a Red Hat-based system, we also need to initialize the database system:
92 <pre><code>~$ <span class="userinput">sudo service postgresql initdb</span>
93 ~$ <span class="userinput">sudo service postgresql start</span>
97 {% include 'notebox_begin' %}
99 If you are installing on CentOS6, you will need to modify PostgreSQL's configuration to allow password authentication for local users. The default configuration allows 'ident' only. The following commands will make the configuration change, and restart PostgreSQL for it to take effect.
102 <pre><code>~$ <span class="userinput">sudo sed -i -e "s/127.0.0.1\/32 ident/127.0.0.1\/32 md5/" /var/lib/pgsql/data/pg_hba.conf</span>
103 ~$ <span class="userinput">sudo sed -i -e "s/::1\/128 ident/::1\/128 md5/" /var/lib/pgsql/data/pg_hba.conf</span>
104 ~$ <span class="userinput">sudo service postgresql restart</span>
107 {% include 'notebox_end' %}
110 Next, generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
113 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
114 abcdefghijklmnopqrstuvwxyz012345689
115 </code></pre></notextile>
117 Configure the SSO server to connect to your database by updating @/etc/arvados/sso/database.yml@. Replace the @xxxxxxxx@ database password placeholder with the new password you generated above. Be sure to update the @production@ section.
120 <pre><code>~$ <span class="userinput">editor /etc/arvados/sso/database.yml</span>
121 </code></pre></notextile>
123 Create a new database user with permission to create its own databases.
126 <pre><code>~$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso</span>
127 Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
128 Enter it again: <span class="userinput">paste-database-password-you-generated</span>
129 </code></pre></notextile>
131 Rails will take care of creating the database, based on the information from @/etc/arvados/sso/database.yml@.
133 Alternatively, if the database user you intend to use for the SSO server should not be allowed to create new databases, the user and the database can be created like this:
136 <pre><code>~$ <span class="userinput">sudo -u postgres createuser --encrypted -R -S --pwprompt arvados_sso</span>
137 Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
138 Enter it again: <span class="userinput">paste-database-password-you-generated</span>
139 ~$ <span class="userinput">sudo -u postgres createdb arvados_sso_production -E UTF8 -O arvados_sso -T template0</span>
140 </code></pre></notextile>
142 h2(#reconfigure_package). Reconfigure the package
144 Now that the @/etc/arvados/sso/application.yml@ and @/etc/arvados/sso/database.yml@ files have been updated, we need to reconfigure our installed package. Doing so will create and/or initialize the database and precompile the assets.
146 On a Debian-based system:
149 <pre><code>~$ <span class="userinput">sudo dpkg-reconfigure arvados-sso-server</span>
153 On a Red Hat-based system, we need to reinstall the package instead:
156 <pre><code>~$ <span class="userinput">sudo yum reinstall arvados-sso-server</span>
160 h2(#client). Create arvados-server client
162 Use @rails console@ to create a @Client@ record that will be used by the Arvados API server. The values of @app_id@ and @app_secret@ correspond to the values for @sso_app_id@ and @sso_app_secret@ in the "API server's SSO settings.":install-api-server.html#omniauth
165 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
166 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
167 ~$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
168 :001 > <span class="userinput">c = Client.new</span>
169 :002 > <span class="userinput">c.name = "joshid"</span>
170 :003 > <span class="userinput">c.app_id = "arvados-server"</span>
171 :004 > <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
172 :005 > <span class="userinput">c.save!</span>
173 :006 > <span class="userinput">quit</span>
177 h2(#configure_web_server). Configure your web server
179 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:
183 listen 127.0.0.1:8900;
184 server_name localhost-sso;
186 root /var/www/arvados-sso/current/public;
189 passenger_enabled on;
190 # If you're not using RVM, comment out the line below.
191 passenger_ruby /usr/local/rvm/wrappers/default/ruby;
195 server 127.0.0.1:8900 fail_timeout=10s;
198 proxy_http_version 1.1;
201 listen <span class="userinput">[your public IP address]</span>:443 ssl;
202 server_name auth.<span class="userinput">your.domain</span>;
205 ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
206 ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
211 proxy_pass http://sso;
213 proxy_connect_timeout 90s;
214 proxy_read_timeout 300s;
216 proxy_set_header X-Forwarded-Proto https;
217 proxy_set_header Host $http_host;
218 proxy_set_header X-Real-IP $remote_addr;
219 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
225 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.
227 h2(#authentication_methods). Authentication methods
229 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.
231 h3(#local_accounts). Local account authentication
233 There are two configuration options for local accounts:
236 # If true, allow new creation of new accounts in the SSO server's internal
238 allow_account_registration: false
240 # If true, send an email confirmation before activating new accounts in the
241 # SSO server's internal user database (otherwise users are activated immediately.)
242 require_email_confirmation: false
245 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
247 If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the rails console:
250 <pre><code>~$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
251 :001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
252 :002 > <span class="userinput">user.password = "passw0rd"</span>
253 :003 > <span class="userinput">user.save!</span>
254 :004 > <span class="userinput">quit</span>
258 h3(#ldap). LDAP authentication
260 The following options are available to configure LDAP authentication. Note that you must preserve the indentation of the fields listed under @use_ldap@.
265 host: ldap.example.com
268 base: "ou=Users, dc=example, dc=com"
270 email_domain: example.com
271 #bind_dn: "some_user"
272 #password: "some_password"
276 |_. Option|_. Description|
277 |title |Title displayed to the user on the login page|
278 |host |LDAP server hostname|
279 |port |LDAP server port|
280 |method|One of "plain", "ssl", "tls"|
281 |base |Directory lookup base|
282 |uid |User id field used for directory lookup|
283 |email_domain|Strip off specified email domain from login and perform lookup on bare username|
284 |bind_dn|If required by server, username to log with in before performing directory lookup|
285 |password|If required by server, password to log with before performing directory lookup|
287 h3(#google). Google+ authentication
289 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.
291 # 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.
292 # On the sidebar, click on *APIs & auth* then select *APIs*.
293 ## Search for *Contacts API* and click on *Enable API*.
294 ## Search for *Google+ API* and click on *Enable API*.
295 # On the sidebar, click on *Credentials*; under *OAuth* click on *Create new Client ID* to bring up the *Create Client ID* dialog box.
296 # Under *Application type* select *Web application*.
297 # If the authorization origins are not displayed, clicking on *Create Client ID* will take you to *Consent screen* settings.
298 ## On consent screen settings, enter the appropriate details and click on *Save*.
299 ## This will return you to the *Create Client ID* dialog box.
300 # You must set the authorization origins. Edit @sso.your-site.com@ to the appropriate hostname that you will use to access the SSO service:
301 ## JavaScript origin should be @https://sso.your-site.com/@
302 ## Redirect URI should be @https://sso.your-site.com/users/auth/google_oauth2/callback@
303 # Copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
306 <pre><code> # Google API tokens required for OAuth2 login.
307 google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
308 google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>