X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/682dd5b6cc23a455766a7651e3e841257660b31c..7d5d40c55d2a38b12e810f3b9d3e168ee434cbd2:/doc/install/install-sso.html.textile.liquid
diff --git a/doc/install/install-sso.html.textile.liquid b/doc/install/install-sso.html.textile.liquid
index b0ad8b4253..3efe124ca2 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -6,47 +6,180 @@ title: Install Single Sign On (SSO) server
h2(#dependencies). Install dependencies
-Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.
+h3(#install_ruby_and_bundler). Install Ruby and Bundler
+
+{% include 'install_ruby_and_bundler' %}
+
+h3(#install_postgres). Install PostgreSQL
+
+{% include 'install_postgres' %}
h2(#install). Install SSO server
-h3. Get SSO server code and create database
+h3. Get SSO server code and run bundle
~$ cd $HOME # (or wherever you want to install)
~$ git clone https://github.com/curoverse/sso-devise-omniauth-provider.git
~$ cd sso-devise-omniauth-provider
-~/sso-devise-omniauth-provider$ bundle install
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:create
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:migrate
-
-
+~/sso-devise-omniauth-provider$ bundle
+
-h3. Configure Rails secret
+h2. Configure the SSO server
-Create a secret:
+First, copy the example configuration file:
-~/sso-devise-omniauth-provider$ cp -i config/initializers/secret_token.rb.example config/initializers/secret_token.rb
-~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**400).to_s(36)'
+~/sso-devise-omniauth-provider$ cp -i config/application.yml.example config/application.yml
+
+
+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.
+
+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@.
+
+h3(#uuid_prefix). uuid_prefix
+
+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).
+
+h3(#secret_token). secret_token
+
+Generate a new secret token for signing cookies:
+
+
+~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
+
+Then put that value in the @secret_token@ field.
+
+h3(#authentication_methods). Authentication methods
+
+Three authentication methods are supported: Google+, LDAP, and local accounts.
+
+h3(#google). Google+ authentication
+
+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:
+
+* Enable the Contacts and Google+ APIs.
+* Create an OAuth Client ID for a web application.
+** JavaScript origins: @https://sso.example.com/@
+** Redirect URIs: @https://sso.example.com/auth/google_oauth2/callback@
+
+Copy the "Client ID" and "Client secret" values from the Google Developers Console into the Google section of @config/application.yml@, like this:
+
+
+
+ # Google API tokens required for OAuth2 login.
+ #
+ # See https://github.com/zquestz/omniauth-google-oauth2
+ #
+ # and https://developers.google.com/accounts/docs/OAuth2
+ google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE---"
+ google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE---"
+
+ # Set this to your OpenId 2.0 realm to enable migration from Google OpenId
+ # 2.0 to Google OAuth2 OpenId Connect (Google will provide OpenId 2.0 user
+ # identifiers via the openid.realm parameter in the OAuth2 flow until 2017).
+ google_openid_realm: false
+
+h3(#ldap). LDAP authentication
+
+LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@.
+
+
+ # Enable LDAP support.
+ #
+ # If you want to use LDAP, you need to provide
+ # the following set of fields under the use_ldap key.
+ #
+ # use_ldap: false
+ # title: Example LDAP
+ # host: ldap.example.com
+ # port: 636
+ # method: ssl
+ # base: "ou=Users, dc=example, dc=com"
+ # uid: uid
+ # email_domain: example.com
+ # #bind_dn: "some_user"
+ # #password: "some_password"
+ use_ldap: false
+
+
+h3(#local_accounts). Local account authentication
+
+If neither Google OAuth2 nor LDAP are enabled, the SSO server automatically
+falls back to local accounts. There are two configuration options for local
+accounts:
+
+
+ # If true, allow new creation of new accounts in the SSO server's internal
+ # user database.
+ allow_account_registration: false
+
+ # If true, send an email confirmation before activating new accounts in the
+ # SSO server's internal user database.
+ require_email_confirmation: false
+
+
+You can also create local accounts on the SSO server from the rails console:
+
+
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails console
+:001 > user = User.new(:email => "test@example.com")
+:002 > user.password = "passw0rd"
+:003 > user.save!
+:004 > quit
-Edit @config/initializers/secret_token.rb@ to set @config.secret_token@ to the string produced by @rand@ above.
+h2. Set up the database
-h3. Configure upstream authentication provider
+Generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
-This will enable users to log in using their existing Google accounts. If you don't want to use Google for account services, you can also "add accounts manually.":#manual-accounts
+
+~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**128).to_s(36)'
+abcdefghijklmnopqrstuvwxyz012345689
+
+
+Create a new database user with permission to create its own databases.
+
+
+~/sso-devise-omniauth-provider$ sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso
+Enter password for new role: paste-database-password-you-generated
+Enter it again: paste-database-password-you-generated
+
+
+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.
+
+
+~/sso-devise-omniauth-provider$ cp -i config/database.yml.sample config/database.yml
+~/sso-devise-omniauth-provider$ edit config/database.yml
+
+
+Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
+
+
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:setup
+
+
+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:
+
+
+~/sso-devise-omniauth-provider$ su postgres createdb arvados_sso_production -E UTF8 -O arvados_sso
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:schema:load
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:seed
+
+
+h2(#assets). Generate assets
+
+If you are running in the production environment, you'll want to generate the assets:
-~/sso-devise-omniauth-provider$ cp -i config/environments/production.rb.example config/environments/production.rb
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake assets:precompile
-Edit @config/environments/production.rb@ to set @config.google_oauth2_client_id@ and @config.google_oauth2_client_secret@. See "Omniauth Google OAuth2 gem documentation":https://github.com/zquestz/omniauth-google-oauth2 and "Using OAuth 2.0 to Access Google APIs":https://developers.google.com/accounts/docs/OAuth2 for information about using the "Google Developers Console":https://console.developers.google.com to get a Google client id and client secret.
-
-h3(#client). Create arvados-server client
+h2(#client). Create arvados-server client
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
@@ -63,28 +196,6 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-h2(#manual-accounts). Adding user accounts manually
-
-Instead of relying on an upstream authentication such as Google, you can create accounts on the SSO server manually.
-
-
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails console
-:001 > user = User.new(:email => "test@example.com")
-:002 > user.password = "passw0rd"
-:003 > user.save!
-:004 > quit
-
-
-
-To log in using a manually created account:
-
-# Go to https://auth.your.domain/users/sign_in
-# Enter the email address and password and click on "Sign in"
-# You will arrive at a page "You are now signed in as test@example.com"
-# Go to https://workbench.@uuid_prefix@.your.domain/
-# Click on the Workbench "Log in" button.
-# You should now be logged in to Workbench. Confirm by looking for the email address displayed in the upper right.
-
h2. Start the SSO server
h3. Run a simple standalone server
@@ -92,7 +203,7 @@ h3. Run a simple standalone server
You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
-~/arvados/services/api$ RAILS_ENV=production bundle exec rails server
+~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails server