3 navsection: installguide
4 title: Install the Single Sign On (SSO) server
7 Copyright (C) The Arvados Authors. All rights reserved.
9 SPDX-License-Identifier: CC-BY-SA-3.0
12 {% include 'notebox_begin_warning' %}
13 Skip this section if you are using Google login via @arvados-controller@.
14 {% include 'notebox_end' %}
16 # "Install dependencies":#dependencies
17 # "Set up database":#database-setup
18 # "Update config.yml":#update-config
19 # "Configure the SSO server":#create-application-yml
20 # "Update Nginx configuration":#update-nginx
21 # "Install arvados-sso-server":#install-packages
22 # "Create arvados-server client record":#client
23 # "Restart the API server and controller":#restart-api
25 h2(#dependencies). Install dependencies
27 # "Install PostgreSQL":install-postgresql.html
28 # "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@
29 # "Install nginx":nginx.html
30 # "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
32 h2(#database-setup). Set up the database
34 {% assign service_role = "arvados_sso" %}
35 {% assign service_database = "arvados_sso_production" %}
36 {% assign use_contrib = false %}
37 {% include 'install_postgres_database' %}
39 Now create @/etc/arvados/sso/database.yml@
45 database: arvados_sso_production
52 h2(#update-config). Update config.yml
57 ExternalURL: auth.ClusterID.example.com
61 ProviderAppID: "arvados-server"
62 ProviderAppSecret: $app_secret
65 Generate @ProviderAppSecret@:
68 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
69 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
70 </code></pre></notextile>
72 h2(#create-application-yml). Configure the SSO server
74 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/@.
76 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.
78 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@.
80 Create @/etc/arvados/sso/application.yml@ and add these keys:
85 secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
88 h3(#uuid_prefix). uuid_prefix
90 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.
92 h3(#secret_token). secret_token
94 Generate a new secret token for signing cookies:
97 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
98 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
99 </code></pre></notextile>
101 h3(#authentication_methods). Authentication methods
103 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.
105 h4(#local_accounts). Local account authentication
107 There are two configuration options for local accounts:
110 # If true, allow new creation of new accounts in the SSO server's internal
112 allow_account_registration: false
114 # If true, send an email confirmation before activating new accounts in the
115 # SSO server's internal user database (otherwise users are activated immediately.)
116 require_email_confirmation: false
119 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
121 If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console. {% include 'install_rails_command' %}
123 Enter the following commands at the console.
126 <pre><code>:001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
127 :002 > <span class="userinput">user.password = "passw0rd"</span>
128 :003 > <span class="userinput">user.save!</span>
129 :004 > <span class="userinput">quit</span>
133 h4(#ldap). LDAP authentication
135 The following options are available to configure LDAP authentication. Note that you must preserve the indentation of the fields listed under @use_ldap@.
140 host: ldap.example.com
143 base: "ou=Users, dc=example, dc=com"
145 email_domain: example.com
146 #bind_dn: "some_user"
147 #password: "some_password"
151 |_. Option|_. Description|
152 |title |Title displayed to the user on the login page|
153 |host |LDAP server hostname|
154 |port |LDAP server port|
155 |method|One of "plain", "ssl", "tls"|
156 |base |Directory lookup base|
157 |uid |User id field used for directory lookup|
158 |email_domain|Strip off specified email domain from login and perform lookup on bare username|
159 |bind_dn|If required by server, username to log with in before performing directory lookup|
160 |password|If required by server, password to log with before performing directory lookup|
162 h4(#google). Google authentication
164 First, visit "Setting up Google auth.":google-auth.html
166 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:
169 <pre><code> # Google API tokens required for OAuth2 login.
170 google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
171 google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>
173 h2(#update-nginx). Update nginx configuration
175 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>.
179 listen <span class="userinput">auth.ClusterID.example.com</span>:443 ssl;
180 server_name <span class="userinput">auth.ClusterID.example.com</span>;
183 ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
184 ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
186 root /var/www/arvados-sso/current/public;
189 passenger_enabled on;
191 # <span class="userinput">If you are using RVM, uncomment the line below.</span>
192 # <span class="userinput">If you're using system ruby, leave it commented out.</span>
193 #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
198 h2(#install-packages). Install arvados-sso-server package
203 <pre><code># <span class="userinput">yum install arvados-sso-server</span>
207 h3. Debian and Ubuntu
210 <pre><code># <span class="userinput">apt-get install --no-install-recommends arvados-sso-server</span>
214 h2(#client). Create arvados-server client record
216 {% assign railshost = "" %}
217 {% assign railsdir = "/var/www/arvados-sso/current" %}
218 Use @rails console@ to create a @Client@ record that will be used by the Arvados API server. {% include 'install_rails_command' %}
220 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@.
223 <pre><code>:001 > <span class="userinput">c = Client.new</span>
224 :002 > <span class="userinput">c.name = "joshid"</span>
225 :003 > <span class="userinput">c.app_id = "arvados-server"</span>
226 :004 > <span class="userinput">c.app_secret = "the value of Login.ProviderAppSecret"</span>
227 :005 > <span class="userinput">c.save!</span>
228 :006 > <span class="userinput">quit</span>
232 h2(#restart-api). Restart the API server and controller
234 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.
237 <pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>