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 create database
  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 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:create</span>
  21 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rake db:migrate</span>
  22 </code></pre>
  23 </notextile>
  24
  25 h2. Configure the SSO server
  26
  27 First, copy the example configuration file:
  28
  29 <notextile>
  30 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
  31 </code></pre></notextile>
  32
  33 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.
  34
  35 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@.
  36
  37 h3(#uuid_prefix). uuid_prefix
  38
  39 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).
  40
  41 h3(#secret_token). secret_token
  42
  43 Generate a new secret token for signing cookies:
  44
  45 <notextile>
  46 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  47 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  48 </code></pre></notextile>
  49
  50 Then put that value in the @secret_token@ field.
  51
  52 h3(#authentication_methods). Authentication methods
  53
  54 Three authentication methods are supported: google OAuth2, ldap, local accounts.
  55
  56 h3(#google_oauth2). google_oauth2 authentication
  57
  58 Google OAuth2 authentication can be configured with these options.
  59
  60 <pre>
  61   # Google API tokens required for OAuth2 login.
  62   #
  63   # See https://github.com/zquestz/omniauth-google-oauth2
  64   #
  65   # and https://developers.google.com/accounts/docs/OAuth2
  66   google_oauth2_client_id: false
  67   google_oauth2_client_secret: false
  68
  69   # Set this to your OpenId 2.0 realm to enable migration from Google OpenId
  70   # 2.0 to Google OAuth2 OpenId Connect (Google will provide OpenId 2.0 user
  71   # identifiers via the openid.realm parameter in the OAuth2 flow until 2017).
  72   google_openid_realm: false
  73 </pre>
  74
  75 h3(#ldap). ldap authentication
  76
  77 LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@.
  78
  79 <pre>
  80   # Enable LDAP support.
  81   #
  82   # If you want to use LDAP, you need to provide
  83   # the following set of fields under the use_ldap key.
  84   #
  85   # use_ldap: false
  86   #   title: Example LDAP
  87   #   host: ldap.example.com
  88   #   port: 636
  89   #   method: ssl
  90   #   base: "ou=Users, dc=example, dc=com"
  91   #   uid: uid
  92   #   email_domain: example.com
  93   #   #bind_dn: "some_user"
  94   #   #password: "some_password"
  95   use_ldap: false
  96 </pre>
  97
  98 h3(#local_accounts). local account authentication
  99
 100 If neither Google OAuth2 nor LDAP are enabled, the SSO server automatically
 101 falls back to local accounts. There are two configuration options for local
 102 accounts:
 103
 104 <pre>
 105   # If true, allow new creation of new accounts in the SSO server's internal
 106   # user database.
 107   allow_account_registration: false
 108
 109   # If true, send an email confirmation before activating new accounts in the
 110   # SSO server's internal user database.
 111   require_email_confirmation: false
 112 </pre>
 113
 114 You can also create local accounts on the SSO server from the rails console:
 115
 116 <notextile>
 117 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
 118 :001 &gt; <span class="userinput">user = User.new(:email =&gt; "test@example.com")</span>
 119 :002 &gt; <span class="userinput">user.password = "passw0rd"</span>
 120 :003 &gt; <span class="userinput">user.save!</span>
 121 :004 &gt; <span class="userinput">quit</span>
 122 </code></pre>
 123 </notextile>
 124
 125 h2(#client). Create arvados-server client
 126
 127 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
 128
 129 <notextile>
 130 <pre><code>~/sso-devise-omniauth-provider$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
 131 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 132 ~/sso-devise-omniauth-provider$ <span class="userinput">RAILS_ENV=production bundle exec rails console</span>
 133 :001 &gt; <span class="userinput">c = Client.new</span>
 134 :002 &gt; <span class="userinput">c.name = "joshid"</span>
 135 :003 &gt; <span class="userinput">c.app_id = "arvados-server"</span>
 136 :004 &gt; <span class="userinput">c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
 137 :005 &gt; <span class="userinput">c.save!</span>
 138 :006 &gt; <span class="userinput">quit</span>
 139 </code></pre>
 140 </notextile>
 141
 142 h2. Start the SSO server
 143
 144 h3. Run a simple standalone server
 145
 146 You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
 147
 148 <notextile>
 149 <pre><code>~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rails server</span>
 150 </code></pre>
 151 </notextile>
 152
 153 h3. Production environment
 154
 155 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.