[arvados.git] / doc / install / install-sso.html.textile.liquid

---
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@

<pre>
production:
  adapter: postgresql
  encoding: utf8
  database: arvados_sso_production
  username: arvados_sso
  password: $password
  host: localhost
  template: template0
</pre>

h2(#update-config). Update config.yml

<pre>
    Services:
      SSO:
        ExternalURL: auth.ClusterID.example.com
    Login:
      SSO:
        Enable: true
        ProviderAppID: "arvados-server"
        ProviderAppSecret: $app_secret
</pre>

Generate @ProviderAppSecret@:

<notextile>
<pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>

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:

<pre>
production:
  uuid_prefix: xxxxx
  secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</pre>

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:

<notextile>
<pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>

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:

<pre>
  # 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
</pre>

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.

<notextile>
<pre><code>:001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
:002 &gt; <span class="userinput">user.password = "passw0rd"</span>
:003 &gt; <span class="userinput">user.save!</span>
:004 &gt; <span class="userinput">quit</span>
</code></pre>
</notextile>

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@.

<pre>
  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"
</pre>

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:

<notextile>
<pre><code>  # Google API tokens required for OAuth2 login.
  google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
  google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>

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 <span class="userinput">red</span>.

<notextile>
<pre><code>server {
  listen       <span class="userinput">auth.ClusterID.example.com</span>:443 ssl;
  server_name  <span class="userinput">auth.ClusterID.example.com</span>;

  ssl on;
  ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
  ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;

  root   /var/www/arvados-sso/current/public;
  index  index.html;

  passenger_enabled on;

  # <span class="userinput">If you are using RVM, uncomment the line below.</span>
  # <span class="userinput">If you're using system ruby, leave it commented out.</span>
  #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
}
</code></pre>
</notextile>

h2(#install-packages). Install arvados-sso-server package

h3. Centos 7

<notextile>
<pre><code># <span class="userinput">yum install arvados-sso-server</span>
</code></pre>
</notextile>

h3. Debian and Ubuntu

<notextile>
<pre><code># <span class="userinput">apt-get install --no-install-recommends arvados-sso-server</span>
</code></pre>
</notextile>

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@.

<notextile>
<pre><code>:001 &gt; <span class="userinput">c = Client.new</span>
:002 &gt; <span class="userinput">c.name = "joshid"</span>
:003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
:004 &gt; <span class="userinput">c.app_secret = "the value of Login.ProviderAppSecret"</span>
:005 &gt; <span class="userinput">c.save!</span>
:006 &gt; <span class="userinput">quit</span>
</code></pre>
</notextile>

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.

<notextile>
<pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
</code></pre>
</notextile>