X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/d2f2463930bd8c0178982221d0f9f3d5b3075670..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 caf384b378..e86116a4c3 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -1,191 +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
-h2(#install). Install SSO server
+The Arvados package repository includes an SSO server package that can help automate much of the deployment.
-h3. Get SSO server code and run bundle
+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:
~$ 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
-
~$ sudo apt-get install arvados-sso-server
+
+
-h2. Configure the SSO server
+On a Red Hat-based system, install the following package:
-First, copy the example configuration file:
+~$ sudo yum install arvados-sso-server
+
+~/sso-devise-omniauth-provider$ cp -i config/application.yml.example config/application.yml
-
/etc/arvados/sso/application.yml
+/etc/arvados/sso/database.yml
+/etc/arvados/sso/production.rb
+
+
+
+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/@.
-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.
+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@.
+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
-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).
+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:
+
+~$ 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: false - google_oauth2_client_secret: false - - # 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 -+There are other configuration options in @/etc/arvados/sso/application.yml@. See the "Authentication methods":install-sso.html#authentication_methods section below for more details. -h3(#ldap). ldap authentication +h2(#database). Set up the database -LDAP authentication can be configured with these options. Make sure to preserve the indentation of the fields beyond @use_ldap@. +Configure the SSO server to connect to your database by updating @/etc/arvados/sso/database.yml@. Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#sso. Be sure to update the @production@ section. -
- # 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
+
- # 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;
+ }
+}
+
+
-~/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 -+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 -h2(#client). Create arvados-server client +If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console. {% include 'install_rails_command' %} -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 +Enter the following commands at the console.- + # 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:structure:load -~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rake db:seed -
~/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
+:001 > user = User.new(:email => "test@example.com")
+:002 > user.password = "passw0rd"
+:003 > user.save!
+:004 > quit
~/sso-devise-omniauth-provider$ RAILS_ENV=production bundle exec rails server
-
-+ 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" +-h3. Production environment +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(#google). Google+ authentication + +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: -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. +
# Google API tokens required for OAuth2 login.
+ google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
+ google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-