X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/ca7460bcc97a8b1402b81ecebc3f0ac3131230c0..feb290061b91fa059aefd251ed3c3532b32620ea:/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 4f6a9771f1..4d91b18c00 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -1,101 +1,237 @@
---
layout: default
navsection: installguide
-title: Install Single Sign On (SSO) server
+title: Install the Single Sign On (SSO) server
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+{% include 'notebox_begin_warning' %}
+Skip this section if you are using Google login via @arvados-controller@.
+{% include 'notebox_end' %}
+
+# "Install dependencies":#dependencies
+# "Set up database":#database-setup
+# "Update config.yml":#update-config
+# "Configure the SSO server":#create-application-yml
+# "Update Nginx configuration":#update-nginx
+# "Install arvados-sso-server":#install-packages
+# "Create arvados-server client record":#client
+# "Restart the API server and controller":#restart-api
h2(#dependencies). Install dependencies
-Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.
+# "Install PostgreSQL":install-postgresql.html
+# "Install Ruby and Bundler":ruby.html Important! The Single Sign On server only supports Ruby 2.3, to avoid version conflicts we recommend installing it on a different server from the API server. When installing Ruby, ensure that you get the right version by installing the "ruby2.3" package, or by using RVM with @--ruby=2.3@
+# "Install nginx":nginx.html
+# "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
+
+h2(#database-setup). Set up the database
+
+{% assign service_role = "arvados_sso" %}
+{% assign service_database = "arvados_sso_production" %}
+{% assign use_contrib = false %}
+{% include 'install_postgres_database' %}
+
+Now create @/etc/arvados/sso/database.yml@
+
+
+production:
+ adapter: postgresql
+ encoding: utf8
+ database: arvados_sso_production
+ username: arvados_sso
+ password: $password
+ host: localhost
+ template: template0
+
-h2(#install). Install SSO server
+h2(#update-config). Update config.yml
-h3. Get SSO server code and create database
+
+ Services:
+ SSO:
+ ExternalURL: auth.ClusterID.example.com
+ Login:
+ ProviderAppID: "arvados-server"
+ ProviderAppSecret: $app_secret
+
+
+Generate @ProviderAppSecret@:
-~$ 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
-
-
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
+
+h2(#create-application-yml). Configure the SSO server
+
+The SSO server runs from the @/var/www/arvados-sso/current/@ directory. The files @/var/www/arvados-sso/current/config/application.yml@ and @/var/www/arvados-sso/current/config/database.yml@ will be symlinked to the configuration files in @/etc/arvados/sso/@.
+
+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.
-h3. Configure Rails secret
+Consult @config/application.default.yml@ for a full list of configuration options. Local configuration goes in @/etc/arvados/sso/application.yml@, do not edit @config/application.default.yml@.
-Create a secret:
+Create @/etc/arvados/sso/application.yml@ and add these keys:
+
+
+production:
+ uuid_prefix: xxxxx
+ secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
+
+h3(#uuid_prefix). uuid_prefix
+
+Most of the time, you want this to be the same as your @ClusterID@. If not, generate a new one from the command line listed previously.
+
+h3(#secret_token). secret_token
+
+Generate a new secret token for signing cookies:
-~/sso-devise-omniauth-provider$ cp -i config/initializers/secret_token.rb.example config/initializers/secret_token.rb
-~/sso-devise-omniauth-provider$ rake secret
+~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
-
+
+
+h3(#authentication_methods). Authentication methods
+
+Authentication methods are configured in @application.yml@. Currently three authentication methods are supported: local accounts, LDAP, and Google. If neither Google nor LDAP are enabled, the SSO server defaults to local user accounts. Only one authentication mechanism should be in use at a time. Choose your authentication method and add the listed configuration items to the @production@ section.
+
+h4(#local_accounts). Local account authentication
+
+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 (otherwise users are activated immediately.)
+ require_email_confirmation: false
+
-Edit @config/initializers/secret_token.rb@ to set @config.secret_token@ to the string produced by @rake secret@.
+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
-h3. Configure upstream authentication provider
+If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console. {% include 'install_rails_command' %}
-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
+Enter the following commands at the console.
-~/sso-devise-omniauth-provider$ cp -i config/environments/production.rb.example config/environments/production.rb
+:001 > user = User.new(:email => "test@example.com")
+:002 > user.password = "passw0rd"
+:003 > user.save!
+:004 > quit
-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.
+h4(#ldap). LDAP authentication
+
+The following options are available to configure LDAP authentication. Note that you must preserve the indentation of the fields listed under @use_ldap@.
+
+
+ use_ldap:
+ 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"
+
+
+table(table).
+|_. Option|_. Description|
+|title |Title displayed to the user on the login page|
+|host |LDAP server hostname|
+|port |LDAP server port|
+|method|One of "plain", "ssl", "tls"|
+|base |Directory lookup base|
+|uid |User id field used for directory lookup|
+|email_domain|Strip off specified email domain from login and perform lookup on bare username|
+|bind_dn|If required by server, username to log with in before performing directory lookup|
+|password|If required by server, password to log with before performing directory lookup|
+
+h4(#google). Google authentication
+
+First, visit "Setting up Google auth.":google-auth.html
+
+Next, copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
-h3(#client). Create arvados-server client
+
+ # Google API tokens required for OAuth2 login.
+ google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
+ google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-
-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
+h2(#update-nginx). Update nginx configuration
+
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-sso.conf@ with the following configuration. Options that need attention are marked in red.
-~/sso-devise-omniauth-provider$ rake secret
-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails console
-:001 > c = Client.new
-:002 > c.name = "joshid"
-:003 > c.app_id = "arvados-server"
-:004 > c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-:005 > c.save!
-:006 > quit
+server {
+ listen auth.ClusterID.example.com:443 ssl;
+ server_name auth.ClusterID.example.com;
+
+ ssl on;
+ ssl_certificate /YOUR/PATH/TO/cert.pem;
+ ssl_certificate_key /YOUR/PATH/TO/cert.key;
+
+ root /var/www/arvados-sso/current/public;
+ index index.html;
+
+ passenger_enabled on;
+
+ # If you are using RVM, uncomment the line below.
+ # If you're using system ruby, leave it commented out.
+ #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+}
-h2(#manual-accounts). Adding user accounts manually
+h2(#install-packages). Install arvados-sso-server package
-Instead of relying on an upstream authentication such as Google, you can create accounts on the SSO server manually.
+h3. Centos 7
-~/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
+# yum install arvados-sso-server
-To log in using a manually created account:
+h3. Debian and Ubuntu
-# 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.
+
+# apt-get --no-install-recommends arvados-sso-server
+
+
-h2. Start the SSO server
+h2(#client). Create arvados-server client record
-h3. Run a simple standalone server
+{% assign railshost = "" %}
+{% assign railsdir = "/var/www/arvados-sso/current" %}
+Use @rails console@ to create a @Client@ record that will be used by the Arvados API server. {% include 'install_rails_command' %}
-You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning:
+Enter the following commands at the console. The values that appear after you assign @app_id@ and @app_secret@ will be copied to @Login.ProviderAppID@ and @Login.ProviderAppSecret@ in @config.yml@.
-~/arvados/services/api$ RAILS_ENV=production bundle exec rails server
+:001 > c = Client.new
+:002 > c.name = "joshid"
+:003 > c.app_id = "arvados-server"
+:004 > c.app_secret = "the value of Login.ProviderAppSecret"
+:005 > c.save!
+:006 > quit
-h3. Production environment
+h2(#restart-api). Restart the API server and controller
+
+After adding the SSO server to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
-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.
+
+# systemctl restart nginx arvados-controller
+
+