3 navsection: installguide
4 title: Install Single Sign On (SSO) server
7 h2(#dependencies). Install dependencies
9 h3(#install_ruby_and_bundler). Install git and curl
11 {% include 'install_tools' %}
13 h3(#install_ruby_and_bundler). Install Ruby and Bundler
15 {% include 'install_ruby_and_bundler' %}
17 h3(#install_postgres). Install PostgreSQL
19 {% include 'install_postgres' %}
21 h2(#install). Install SSO server
23 h3. Get SSO server code and run bundle
26 <pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
27 ~$ <span class="userinput">git clone https://github.com/curoverse/sso-devise-omniauth-provider.git</span>
28 ~$ <span class="userinput">cd sso-devise-omniauth-provider</span>
29 ~/sso-devise-omniauth-provider$ <span class="userinput">bundle install --without=development</span>
30 </code></pre></notextile>
32 h2. Configure the SSO server
34 First, copy the example configuration file:
37 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
38 </code></pre></notextile>
40 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.
42 Consult @config/application.default.yml@ for a full list of configuration options. Local configuration goes in @config/application.yml@, do not edit @config/application.default.yml@.
44 h3(#uuid_prefix). uuid_prefix
46 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 alphanumeric characters (lowercase ASCII letters and digits). You may use the following snippet to generate a uuid prefix:
49 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'</span>
51 </code></pre></notextile>
53 Edit @config/application.yml@ and set @uuid_prefix@ in the "common" section.
55 h3(#secret_token). secret_token
57 Generate a new secret token for signing cookies:
60 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
61 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
62 </code></pre></notextile>
64 Edit @config/application.yml@ and set @secret_token@ in the "common" section.
66 h2(#authentication_methods). Authentication methods
68 Three authentication methods are supported: local accounts, LDAP, and Google+. If neither Google OAuth2 nor LDAP are enabled, the SSO server defaults to local user accounts. Only one authentication mechanism should be in use at a time.
70 h3(#local_accounts). Local account authentication
72 There are two configuration options for local accounts:
75 # If true, allow new creation of new accounts in the SSO server's internal
77 allow_account_registration: false
79 # If true, send an email confirmation before activating new accounts in the
80 # SSO server's internal user database (otherwise users are activated immediately.)
81 require_email_confirmation: false
84 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
86 If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the rails console:
89 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
90 :001 > <span class="userinput">user = User.new(:email => "test@example.com")</span>
91 :002 > <span class="userinput">user.password = "passw0rd"</span>
92 :003 > <span class="userinput">user.save!</span>
93 :004 > <span class="userinput">quit</span>
97 h3(#ldap). LDAP authentication
99 The following options are available to configure LDAP authentication. Note that you must preserve the indentation of the fields listed under @use_ldap@.
104 host: ldap.example.com
107 base: "ou=Users, dc=example, dc=com"
109 email_domain: example.com
110 #bind_dn: "some_user"
111 #password: "some_password"
115 |_. Option|_. Description|
116 |title |Title displayed to the user on the login page|
117 |host |LDAP server hostname|
118 |port |LDAP server port|
119 |method|One of "plain", "ssl", "tls"|
120 |base |Directory lookup base|
121 |uid |User id field used for directory lookup|
122 |email_domain|Strip off specified email domain from login and perform lookup on bare username|
123 |bind_dn|If required by server, username to log with in before performing directory lookup|
124 |password|If required by server, password to log with before performing directory lookup|
126 h3(#google). Google+ authentication
128 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.
130 # 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
131 # On the sidebar, click on *APIs & auth* then select *APIs*
132 ## Search for "Contacts API" and click on "Enable API"
133 ## Search for "Google+ API" and click on "Enable API"
134 # On the sidebar, click on *Credentials*; under *OAuth* click on "Create new Client ID" to bring up the "Create Client ID" dialog box
135 # Under "Application type" select "Web application"
136 # If the authorization origins are not displayed, clicking on "Create Client ID" will take you to *Consent screen* settings.
137 ## On consent screen settings, enter the appropriate details and click on "Save"
138 ## This will return you to the "Create Client ID" dialog box.
139 # You must set the authorization origins. Edit @sso.your-site.com@ to the appropriate hostname that you will use to access the SSO service:
140 ## JavaScript origin should be @https://sso.your-site.com/@
141 ## Redirect URI should be @https://sso.your-site.com/auth/google_oauth2/callback@
142 # Copy the values of "Client ID" and "Client secret" from the Google Developers Console into the Google section of @config/application.yml@, like this:
145 <pre><code> # Google API tokens required for OAuth2 login.
146 google_oauth2_client_id: <span class="userinput">"---YOUR---CLIENT---ID---HERE--"-</span>
147 google_oauth2_client_secret: <span class="userinput">"---YOUR---CLIENT---SECRET---HERE--"-</span></code></pre></notextile>
150 h2. Set up the database
152 Generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
155 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
156 abcdefghijklmnopqrstuvwxyz012345689
157 </code></pre></notextile>
159 Create a new database user with permission to create its own databases.
162 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso</span>
163 Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
164 Enter it again: <span class="userinput">paste-database-password-you-generated</span>
165 </code></pre></notextile>
167 Configure SSO server to connect to your database by creating and updating @config/database.yml@. Replace the @xxxxxxxx@ database password placeholders with the new password you generated above.
170 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/database.yml.sample config/database.yml</span>
171 ~/sso-devise-omniauth-provider$ <span class="userinput">edit config/database.yml</span>
172 </code></pre></notextile>
174 Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
177 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:setup</span>
178 </code></pre></notextile>
180 Alternatively, if the database user you intend to use for the SSO server is not allowed to create new databases, you can create the database first and then populate it with rake. Be sure to adjust the database name if you are using the @development@ environment. This sequence of commands is functionally equivalent to the rake db:setup command above:
183 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">su postgres createdb arvados_sso_production -E UTF8 -O arvados_sso</span>
184 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:schema:load</span>
185 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:seed</span>
186 </code></pre></notextile>
188 h2(#client). Create arvados-server client
190 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
193 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
194 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
195 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
196 :001 > <span class="userinput">c = Client.new</span>
197 :002 > <span class="userinput">c.name = "joshid"</span>
198 :003 > <span class="userinput">c.app_id = "arvados-server"</span>
199 :004 > <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
200 :005 > <span class="userinput">c.save!</span>
201 :006 > <span class="userinput">quit</span>
205 h2(#client). Precompile assets
207 If you are running in the production environment, you must precompile the assets:
210 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake assets:precompile</span>
214 h2. Start the SSO server
216 h3. Run a standalone passenger server
219 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production passenger start</span>
220 =============== Phusion Passenger Standalone web server started ===============
224 Note, if you get the following warning "you may safely ignore it:":https://stackoverflow.com/questions/10374871/no-secret-option-provided-to-racksessioncookie-warning
227 Connecting to database specified by database.yml
228 App 4574 stderr: SECURITY WARNING: No secret option provided to Rack::Session::Cookie.
229 App 4574 stderr: This poses a security threat. It is strongly recommended that you
230 App 4574 stderr: provide a secret to prevent exploits that may be possible from crafted
231 App 4574 stderr: cookies. This will not be supported in future versions of Rack, and
232 App 4574 stderr: future versions will even invalidate your existing user cookies.
234 App 4574 stderr: Called from: /var/lib/gems/2.1.0/gems/actionpack-3.2.8/lib/action_dispatch/middleware/session/abstract_store.rb:28:in `initialize'.