X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/7e773735e9d547381a77baeeb139696dfa66a7a6..3f0914ec893c01440778b01620776745da2546de:/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 af999e95a9..4d91b18c00 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -1,137 +1,106 @@
---
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.
-h2(#dependencies). Install dependencies
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-h3(#install_git_curl). Install git and curl
+{% include 'notebox_begin_warning' %}
+Skip this section if you are using Google login via @arvados-controller@.
+{% include 'notebox_end' %}
-{% include 'install_git_curl' %}
+# "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
-h3(#install_ruby_and_bundler). Install Ruby and Bundler
+h2(#dependencies). Install dependencies
-{% include 'install_ruby_and_bundler' %}
+# "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
-h3(#install_postgres). Install PostgreSQL
+h2(#database-setup). Set up the database
-{% include 'install_postgres' %}
+{% assign service_role = "arvados_sso" %}
+{% assign service_database = "arvados_sso_production" %}
+{% assign use_contrib = false %}
+{% include 'install_postgres_database' %}
-h2(#install). Install SSO server
+Now create @/etc/arvados/sso/database.yml@
-h3. Get SSO server code and run bundle
+
+production:
+ adapter: postgresql
+ encoding: utf8
+ database: arvados_sso_production
+ username: arvados_sso
+ password: $password
+ host: localhost
+ template: template0
+
-
-~$ 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 --without=development
-
+h2(#update-config). Update config.yml
-h2. Configure the SSO server
+
+ Services:
+ SSO:
+ ExternalURL: auth.ClusterID.example.com
+ Login:
+ ProviderAppID: "arvados-server"
+ ProviderAppSecret: $app_secret
+
-First, copy the example configuration file:
+Generate @ProviderAppSecret@:
-~/sso-devise-omniauth-provider$ cp -i config/application.yml.example config/application.yml
+~$ 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.
-Consult @config/application.default.yml@ for a full list of configuration options. Local configuration goes in @config/application.yml@, do not edit @config/application.default.yml@.
+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@.
-h3(#uuid_prefix). uuid_prefix
+Create @/etc/arvados/sso/application.yml@ and add these keys:
-Generate a uuid prefix for the single sign on service. This prefix is used to identify user records as originating from this site. It must be exactly 5 lowercase ASCII letters and/or digits. You may use the following snippet to generate a uuid prefix:
+
+production:
+ uuid_prefix: xxxxx
+ secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
-
-~/sso-devise-omniauth-provider$ ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'
-abcde
-
+h3(#uuid_prefix). uuid_prefix
-Edit @config/application.yml@ and set @uuid_prefix@ in the "common" section.
+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$ ruby -e 'puts rand(2**400).to_s(36)'
+~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-Edit @config/application.yml@ and set @secret_token@ in the "common" section.
-
-h2(#database). Set up the database
-
-Generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
-
-
-~/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. If you are planning a production system, update the @production@ section, otherwise use @development@.
-
-
-~/sso-devise-omniauth-provider$ cp -i config/database.yml.example 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$ sudo -u postgres createdb arvados_sso_production -E UTF8 -O arvados_sso -T template0
-~/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(#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 values for @sso_app_id@ and @sso_app_secret@ in the "API server's SSO settings.":install-api-server.html#omniauth
-
-
-~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**400).to_s(36)'
-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
-
-
-
-h2(#assets). Precompile assets
-
-If you are running in the production environment, you must precompile the assets:
-
-
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake assets:precompile
-
-
+h3(#authentication_methods). Authentication methods
-h2(#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.
-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.
-
-h3(#local_accounts). Local account authentication
+h4(#local_accounts). Local account authentication
There are two configuration options for local accounts:
@@ -147,18 +116,19 @@ There are two configuration options for local accounts:
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
-If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the rails console:
+If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console. {% include 'install_rails_command' %}
+
+Enter the following commands at the console.
-~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails console
-:001 > user = User.new(:email => "test@example.com")
+:001 > user = User.new(:email => "test@example.com")
:002 > user.password = "passw0rd"
:003 > user.save!
:004 > quit
-h3(#ldap). LDAP authentication
+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@.
@@ -187,99 +157,81 @@ table(table).
|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|
-h3(#google). Google+ authentication
+h4(#google). Google authentication
-In order to use Google+ authentication, you must use the Google Developers Console to create a set of client credentials.
+First, visit "Setting up Google auth.":google-auth.html
-# Go to the Google Developers Console and select or create a project; this will take you to the project page.
-# On the sidebar, click on *APIs & auth* then select *APIs*.
-## Search for *Contacts API* and click on *Enable API*.
-## Search for *Google+ API* and click on *Enable API*.
-# On the sidebar, click on *Credentials*; under *OAuth* click on *Create new Client ID* to bring up the *Create Client ID* dialog box.
-# Under *Application type* select *Web application*.
-# If the authorization origins are not displayed, clicking on *Create Client ID* will take you to *Consent screen* settings.
-## On consent screen settings, enter the appropriate details and click on *Save*.
-## This will return you to the *Create Client ID* dialog box.
-# You must set the authorization origins. Edit @sso.your-site.com@ to the appropriate hostname that you will use to access the SSO service:
-## JavaScript origin should be @https://sso.your-site.com/@
-## Redirect URI should be @https://sso.your-site.com/users/auth/google_oauth2/callback@
-# Copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
+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:
# Google API tokens required for OAuth2 login.
google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-
-h2(#start). Set up a Web server
+h2(#update-nginx). Update nginx configuration
-For best performance, we recommend you use Nginx as your Web server front-end, with a Passenger backend to serve the SSO server. To do that:
+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.
-
-- Install Nginx and Phusion Passenger.
-
-Edit the http section of your Nginx configuration to run the Passenger server, and act as a front-end for it. You might add a block like the following, adding SSL and logging parameters to taste:
-
server {
- listen 127.0.0.1:8900;
- server_name localhost-sso;
+ 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 /YOUR/PATH/TO/sso-devise-omniauth-provider/public;
- index index.html index.htm index.php;
+ root /var/www/arvados-sso/current/public;
+ index index.html;
passenger_enabled on;
- # If you're using RVM, uncomment the line below.
- #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
-}
-upstream sso {
- server 127.0.0.1:8900 fail_timeout=10s;
+ # 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;
}
+
+
-proxy_http_version 1.1;
-
-server {
- listen [your public IP address]:443 ssl;
- server_name auth.your.domain;
+h2(#install-packages). Install arvados-sso-server package
- ssl on;
- ssl_certificate /YOUR/PATH/TO/cert.pem;
- ssl_certificate_key /YOUR/PATH/TO/cert.key;
+h3. Centos 7
- index index.html index.htm index.php;
+
+# yum install arvados-sso-server
+
+
- location / {
- proxy_pass http://sso;
- proxy_redirect off;
- proxy_connect_timeout 90s;
- proxy_read_timeout 300s;
+h3. Debian and Ubuntu
- proxy_set_header X-Forwarded-Proto https;
- proxy_set_header Host $http_host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-}
+
+# apt-get --no-install-recommends arvados-sso-server
-
+
-Restart Nginx.
+h2(#client). Create arvados-server client record
-
-
+{% 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' %}
-{% include 'notebox_begin' %}
+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@.
-If you see the following warning "you may safely ignore it":https://stackoverflow.com/questions/10374871/no-secret-option-provided-to-racksessioncookie-warning:
+
+: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
+
+
-
-SECURITY WARNING: No secret option provided to Rack::Session::Cookie.
-This poses a security threat. It is strongly recommended that you
-provide a secret to prevent exploits that may be possible from crafted
-cookies. This will not be supported in future versions of Rack, and
-future versions will even invalidate your existing user cookies.
+h2(#restart-api). Restart the API server and controller
-Called from: /var/lib/gems/2.1.0/gems/actionpack-3.2.8/lib/action_dispatch/middleware/session/abstract_store.rb:28:in `initialize'.
-
+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.
-{% include 'notebox_end' %}
+
+# systemctl restart nginx arvados-controller
+
+