doc/install/install-sso.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Single Sign On (SSO) server
   5 ...
   6
   7 h2(#dependencies). Install dependencies
   8
   9 h3(#install_ruby_and_bundler). Install Ruby and Bundler
  10
  11 {% include 'install_ruby_and_bundler' %}
  12
  13 h3(#install_postgres). Install PostgreSQL
  14
  15 {% include 'install_postgres' %}
  16
  17 h2(#install). Install SSO server
  18
  19 h3. Get SSO server code and run bundle
  20
  21 <notextile>
  22 <pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
  23 ~$ <span class="userinput">git clone https://github.com/curoverse/sso-devise-omniauth-provider.git</span>
  24 ~$ <span class="userinput">cd sso-devise-omniauth-provider</span>
  25 ~/sso-devise-omniauth-provider$ <span class="userinput">bundle</span>
  26 </code></pre></notextile>
  27
  28 h2. Configure the SSO server
  29
  30 First, copy the example configuration file:
  31
  32 <notextile>
  33 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
  34 </code></pre></notextile>
  35
  36 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.
  37
  38 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@.
  39
  40 h3(#uuid_prefix). uuid_prefix
  41
  42 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).
  43
  44 h3(#secret_token). secret_token
  45
  46 Generate a new secret token for signing cookies:
  47
  48 <notextile>
  49 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  50 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  51 </code></pre></notextile>
  52
  53 Then put that value in the @secret_token@ field.
  54
  55 h3(#authentication_methods). Authentication methods
  56
  57 Three authentication methods are supported: Google+, LDAP, and local accounts.
  58
  59 h3(#google). Google+ authentication
  60
  61 In order to use Google+ authentication, you must use the "Google Developers Console":https://console.developers.google.com to create a set of client credentials. In short:
  62
  63 * Enable the Contacts and Google+ APIs.
  64 * Create an OAuth Client ID for a web application.
  65 ** JavaScript origins: @https://sso.example.com/@
  66 ** Redirect URIs: @https://sso.example.com/auth/google_oauth2/callback@
  67
  68 Copy the "Client ID" and "Client secret" values from the Google Developers Console into the Google section of @config/application.yml@, like this:
  69
  70 <notextile>
  71 <pre><code>
  72   # Google API tokens required for OAuth2 login.
  73   #
  74   # See https://github.com/zquestz/omniauth-google-oauth2
  75   #
  76   # and https://developers.google.com/accounts/docs/OAuth2
  77   google_oauth2_client_id: "<span class="userinput">---YOUR---CLIENT---ID---HERE---</span>"
  78   google_oauth2_client_secret: "<span class="userinput">---YOUR---CLIENT---SECRET---HERE---</span>"
  79
  80   # Set this to your OpenId 2.0 realm to enable migration from Google OpenId
  81   # 2.0 to Google OAuth2 OpenId Connect (Google will provide OpenId 2.0 user
  82   # identifiers via the openid.realm parameter in the OAuth2 flow until 2017).
  83   google_openid_realm: <span class="userinput">false</span></code></pre></notextile>
  84
  85 h3(#ldap). LDAP authentication
  86
  87 LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@.
  88
  89 <pre>
  90   # Enable LDAP support.
  91   #
  92   # If you want to use LDAP, you need to provide
  93   # the following set of fields under the use_ldap key.
  94   #
  95   # use_ldap: false
  96   #   title: Example LDAP
  97   #   host: ldap.example.com
  98   #   port: 636
  99   #   method: ssl
 100   #   base: "ou=Users, dc=example, dc=com"
 101   #   uid: uid
 102   #   email_domain: example.com
 103   #   #bind_dn: "some_user"
 104   #   #password: "some_password"
 105   use_ldap: false
 106 </pre>
 107
 108 h3(#local_accounts). Local account authentication
 109
 110 If neither Google OAuth2 nor LDAP are enabled, the SSO server automatically
 111 falls back to local accounts. There are two configuration options for local
 112 accounts:
 113
 114 <pre>
 115   # If true, allow new creation of new accounts in the SSO server's internal
 116   # user database.
 117   allow_account_registration: false
 118
 119   # If true, send an email confirmation before activating new accounts in the
 120   # SSO server's internal user database.
 121   require_email_confirmation: false
 122 </pre>
 123
 124 You can also create local accounts on the SSO server from the rails console:
 125
 126 <notextile>
 127 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
 128 :001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
 129 :002 &gt; <span class="userinput">user.password = "passw0rd"</span>
 130 :003 &gt; <span class="userinput">user.save!</span>
 131 :004 &gt; <span class="userinput">quit</span>
 132 </code></pre>
 133 </notextile>
 134
 135 h2. Set up the database
 136
 137 Generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
 138
 139 <notextile>
 140 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
 141 abcdefghijklmnopqrstuvwxyz012345689
 142 </code></pre></notextile>
 143
 144 Create a new database user with permission to create its own databases.
 145
 146 <notextile>
 147 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso</span>
 148 Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
 149 Enter it again: <span class="userinput">paste-database-password-you-generated</span>
 150 </code></pre></notextile>
 151
 152 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.
 153
 154 <notextile>
 155 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/database.yml.sample config/database.yml</span>
 156 ~/sso-devise-omniauth-provider$ <span class="userinput">edit config/database.yml</span>
 157 </code></pre></notextile>
 158
 159 Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
 160
 161 <notextile>
 162 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:setup</span>
 163 </code></pre></notextile>
 164
 165 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:
 166
 167 <notextile>
 168 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">su postgres createdb arvados_sso_production -E UTF8 -O arvados_sso</span>
 169 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:schema:load</span>
 170 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:seed</span>
 171 </code></pre></notextile>
 172
 173 h2(#client). Generate assets
 174
 175 If you are running in the production environment, you'll want to generate the assets:
 176
 177 <notextile>
 178 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake assets:precompile</span>
 179 </code></pre>
 180 </notextile>
 181
 182 h2(#client). Create arvados-server client
 183
 184 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
 185
 186 <notextile>
 187 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
 188 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 189 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
 190 :001 &gt; <span class="userinput">c = Client.new</span>
 191 :002 &gt; <span class="userinput">c.name = "joshid"</span>
 192 :003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
 193 :004 &gt; <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
 194 :005 &gt; <span class="userinput">c.save!</span>
 195 :006 &gt; <span class="userinput">quit</span>
 196 </code></pre>
 197 </notextile>
 198
 199 h2. Start the SSO server
 200
 201 h3. Run a simple standalone server
 202
 203 You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
 204
 205 <notextile>
 206 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails server</span>
 207 </code></pre>
 208 </notextile>
 209
 210 h3. Production environment
 211
 212 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.