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