---
layout: default
navsection: installguide
-title: Install Single Sign On (SSO) server
+title: Install the Single Sign On (SSO) server
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-h2(#dependencies). Install dependencies
-
-Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-h2(#install). Install SSO server
+{% include 'notebox_begin_warning' %}
+Skip this section if you are using Google login via @arvados-controller@.
+{% include 'notebox_end' %}
-h3. Get SSO server code and create database
+# "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
-<notextile>
-<pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
-~$ <span class="userinput">git clone https://github.com/curoverse/sso-devise-omniauth-provider.git</span>
-~$ <span class="userinput">cd sso-devise-omniauth-provider</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">bundle install</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:create</span>
-~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:migrate</span>
-</code></pre>
-</notextile>
-
-h2. Configure the SSO server
+h2(#dependencies). Install dependencies
-First, copy the example configuration file:
+# "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
-<notextile>
-<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
-</code></pre></notextile>
+h2(#database-setup). Set up the database
-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.
+{% assign service_role = "arvados_sso" %}
+{% assign service_database = "arvados_sso_production" %}
+{% assign use_contrib = false %}
+{% include 'install_postgres_database' %}
-Consult @config/application.default.yml@ for a full list of configuration options. Always put your local configuration in @config/application.yml@, never edit @config/application.default.yml@.
+Now create @/etc/arvados/sso/database.yml@
-h3(#uuid_prefix). uuid_prefix
+<pre>
+production:
+ adapter: postgresql
+ encoding: utf8
+ database: arvados_sso_production
+ username: arvados_sso
+ password: $password
+ host: localhost
+ template: template0
+</pre>
-Define your @uuid_prefix@ in @config/application.yml@ by setting the @uuid_prefix@ field in the section for your environment. This prefix is used for all database identifiers to identify the record as originating from this site. It must be exactly 5 alphanumeric characters (lowercase ASCII letters and digits).
+h2(#update-config). Update config.yml
-h3(#secret_token). secret_token
+<pre>
+ Services:
+ SSO:
+ ExternalURL: auth.ClusterID.example.com
+ Login:
+ ProviderAppID: "arvados-server"
+ ProviderAppSecret: $app_secret
+</pre>
-Generate a new secret token for signing cookies:
+Generate @ProviderAppSecret@:
<notextile>
-<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
+<pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>
-Then put that value in the @secret_token@ field.
+h2(#create-application-yml). Configure the SSO server
-h3(#authentication_methods). Authentication methods
+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/@.
-Three authentication methods are supported: google OAuth2, ldap, local accounts.
+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.
-h3(#google_oauth2). google_oauth2 authentication
+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@.
-Google OAuth2 authentication can be configured with these options.
+Create @/etc/arvados/sso/application.yml@ and add these keys:
<pre>
- # Google API tokens required for OAuth2 login.
- #
- # See https://github.com/zquestz/omniauth-google-oauth2
- #
- # and https://developers.google.com/accounts/docs/OAuth2
- google_oauth2_client_id: false
- google_oauth2_client_secret: false
-
- # Set this to your OpenId 2.0 realm to enable migration from Google OpenId
- # 2.0 to Google OAuth2 OpenId Connect (Google will provide OpenId 2.0 user
- # identifiers via the openid.realm parameter in the OAuth2 flow until 2017).
- google_openid_realm: false
+production:
+ uuid_prefix: xxxxx
+ secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</pre>
-h3(#ldap). ldap authentication
+h3(#uuid_prefix). uuid_prefix
-LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@.
+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.
-<pre>
- # Enable LDAP support.
- #
- # If you want to use LDAP, you need to provide
- # the following set of fields under the use_ldap key.
- #
- # use_ldap: false
- # 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"
- use_ldap: false
-</pre>
+h3(#secret_token). secret_token
-h3(#local_accounts). local account authentication
+Generate a new secret token for signing cookies:
-If neither Google OAuth2 nor LDAP are enabled, the SSO server automatically
-falls back to local accounts. There are two configuration options for local
-accounts:
+<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
allow_account_registration: false
# If true, send an email confirmation before activating new accounts in the
- # SSO server's internal user database.
+ # SSO server's internal user database (otherwise users are activated immediately.)
require_email_confirmation: false
</pre>
-You can also create local accounts on the SSO server from the rails console:
+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>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
-:001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
+<pre><code>:001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
:002 > <span class="userinput">user.password = "passw0rd"</span>
:003 > <span class="userinput">user.save!</span>
:004 > <span class="userinput">quit</span>
</code></pre>
</notextile>
-h2(#client). Create arvados-server client
+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
-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 @APP_ID@ and @APP_SECRET@ that must be set in in "Setting up Omniauth in the API server.":install-api-server.html#omniauth
+h3. Centos 7
<notextile>
-<pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
-:001 > <span class="userinput">c = Client.new</span>
+<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 --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 > <span class="userinput">c = Client.new</span>
:002 > <span class="userinput">c.name = "joshid"</span>
:003 > <span class="userinput">c.app_id = "arvados-server"</span>
-:004 > <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
+:004 > <span class="userinput">c.app_secret = "the value of Login.ProviderAppSecret"</span>
:005 > <span class="userinput">c.save!</span>
:006 > <span class="userinput">quit</span>
</code></pre>
</notextile>
-h2. Start the SSO server
-
-h3. Run a simple standalone server
+h2(#restart-api). Restart the API server and controller
-You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
+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>~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rails server</span>
+<pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
</code></pre>
</notextile>
-
-h3. Production environment
-
-As a Ruby on Rails application, the SSO server should be compatible with any Ruby application server that supports Rack applications. We recommend "Passenger":https://www.phusionpassenger.com/ to run the SSO server in production.
projects / arvados.git / blobdiff