X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/8c1a3773b9ae07e8f37e3567a9e7c225e47d2ea5..a3851eec63fb52c1f8121395d0092f4aff25405f:/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 d07fc3fc20..e86116a4c3 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -1,224 +1,247 @@
---
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 %}
-Make sure you have "Ruby and Bundler":install-manual-prerequisites-ruby.html installed.
+h2(#dependencies). Install prerequisites
-On a Debian-based system, install the following packages:
+The Arvados package repository includes an SSO server package that can help automate much of the deployment.
+
+h3(#install_ruby_and_bundler). Install Ruby and Bundler
+
+{% include 'install_ruby_and_bundler' %}
+
+h3(#install_web_server). Set up a Web server
+
+For best performance, we recommend you use Nginx as your Web server frontend with a Passenger backend to serve the SSO server. The Passenger team provides "Nginx + Passenger installation instructions":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
+
+Follow the instructions until you see the section that says you are ready to deploy your Ruby application on the production server.
+
+h2(#install). Install the SSO server
+
+On a Debian-based system, install the following package:
~$ sudo apt-get install git libpq-dev postgresql
+
~$ sudo apt-get install arvados-sso-server
~$ sudo yum install git postgresql postgresql-devel
+
~$ sudo yum install arvados-sso-server
~$ 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
-
/etc/arvados/sso/application.yml
+/etc/arvados/sso/database.yml
+/etc/arvados/sso/production.rb
+
+
-h2. 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@, @/var/www/arvados-sso/current/config/database.yml@ and @/var/www/arvados-sso/current/config/environments/production.rb@ are symlinked to the configuration files in @/etc/arvados/sso/@.
-First, copy the example configuration file:
+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.
-~/sso-devise-omniauth-provider$ cp -i config/application.yml.example config/application.yml
-
~$ ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'
+abcde
+
~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**400).to_s(36)'
+~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
- # 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
- # 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 -+
~$ editor /etc/arvados/sso/database.yml
+
-h3(#local_accounts). Local account authentication
+h2(#reconfigure_package). Reconfigure the package
-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:
+{% assign railspkg = "arvados-sso-server" %}
+{% include 'install_rails_reconfigure' %}
-- # If true, allow new creation of new accounts in the SSO server's internal - # user database. - allow_account_registration: false +h2(#client). Create arvados-server client - # If true, send an email confirmation before activating new accounts in the - # SSO server's internal user database. - require_email_confirmation: false -+{% 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 also create local accounts on the SSO server from the rails console: +Enter the following commands at the console. The values that appear after you assign @app_id@ and @app_secret@ correspond to the values for @sso_app_id@ and @sso_app_secret@, respectively, in the "API server's SSO settings":install-api-server.html#omniauth.
~/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
+:001 > c = Client.new
+:002 > c.name = "joshid"
+:003 > c.app_id = "arvados-server"
+:004 > c.app_secret = rand(2**400).to_s(36)
+=> "save this string for your API server's sso_app_secret"
+:005 > c.save!
+:006 > quit
~/sso-devise-omniauth-provider$ ruby -e 'puts rand(2**128).to_s(36)'
-abcdefghijklmnopqrstuvwxyz012345689
-
server {
+ listen 127.0.0.1:8900;
+ server_name localhost-sso;
+
+ root /var/www/arvados-sso/current/public;
+ index index.html;
+
+ passenger_enabled on;
+ # If you're not using RVM, comment out the line below.
+ passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+}
+
+upstream sso {
+ server 127.0.0.1:8900 fail_timeout=10s;
+}
+
+proxy_http_version 1.1;
+
+server {
+ listen [your public IP address]:443 ssl;
+ server_name auth.your.domain;
+
+ ssl on;
+ ssl_certificate /YOUR/PATH/TO/cert.pem;
+ ssl_certificate_key /YOUR/PATH/TO/cert.key;
+
+ index index.html;
+
+ location / {
+ proxy_pass http://sso;
+ proxy_redirect off;
+ proxy_connect_timeout 90s;
+ proxy_read_timeout 300s;
+
+ 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;
+ }
+}
+
+
-Create a new database user with permission to create its own databases.
+Finally, restart Nginx and your Arvados SSO server should be up and running. You can verify that by visiting the URL you configured your Nginx web server to listen on in the server section above (port 443). Read on if you want to configure your Arvados SSO server to use a different authentication backend.
-~/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
-
~/sso-devise-omniauth-provider$ cp -i config/database.yml.sample config/database.yml
-~/sso-devise-omniauth-provider$ edit config/database.yml
-
~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:setup
-
+ # If true, allow new creation of new accounts in the SSO server's internal + # user database. + allow_account_registration: false -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: + # 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 +-
~/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
-
~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake assets:precompile
+:001 > user = User.new(:email => "test@example.com")
+:002 > user.password = "passw0rd"
+:003 > user.save!
+:004 > quit
~/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
-
-+ 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" +-h2. Start the SSO server +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| -h3. Run a simple standalone server +h3(#google). Google+ authentication -You can use the Webrick server that is bundled with Ruby to quickly verify that your installation is functioning: +In order to use Google+ authentication, you must use the Google Developers Console to create a set of client credentials. + +# 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:
~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails server
-
- # Google API tokens required for OAuth2 login.
+ google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
+ google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-