X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/5792ec3a8ddfdba959da5c09dfa1be4ac7472c20..933e687424e67f3a3e3c064016abd295b49c5f98:/doc/install/setup-login.html.textile.liquid
diff --git a/doc/install/setup-login.html.textile.liquid b/doc/install/setup-login.html.textile.liquid
index 2f757b48d3..b16170a888 100644
--- a/doc/install/setup-login.html.textile.liquid
+++ b/doc/install/setup-login.html.textile.liquid
@@ -12,38 +12,115 @@ SPDX-License-Identifier: CC-BY-SA-3.0
Select one of the following login mechanisms for your cluster.
# If all users will authenticate with Google, "configure Google login":#google.
+# If all users will authenticate with an OpenID Connect provider (other than Google), "configure OpenID Connect":#oidc.
+# If all users will authenticate with an existing LDAP service, "configure LDAP":#ldap.
# If all users will authenticate using PAM as configured on your controller node, "configure PAM":#pam.
-# If you need to enable multiple authentication methods, or your backend can't be configured as a PAM service on your controller node, "configure a separate single sign-on (SSO) server":#sso.
h2(#google). Google login
With this configuration, users will sign in with their Google accounts.
-First, visit "Setting up Google auth.":google-auth.html
+Use the Google Developers Console to create a set of client credentials.
+# Select or create a project.
+# Click *+ Enable APIs and Services*.
+#* Search for *People API* and click *Enable API*.
+#* Navigate back to the main "APIs & Services" page.
+# On the sidebar, click *OAuth consent screen*.
+#* On consent screen settings, enter your identifying details.
+#* Under *Authorized domains* add your domain (@example.com@).
+#* Click *Save*.
+# On the sidebar, click *Credentials*, then click *Create credentials*→*OAuth client ID*
+# Under *Application type* select *Web application*.
+# Add the JavaScript origin: @https://ClusterID.example.com/@
+# Add the Redirect URI: @https://ClusterID.example.com/login@
+# Copy the values of *Client ID* and *Client secret* to the @Login.Google@ section of @config.yml@.
+
+{% codeblock as yaml %}
+ Login:
+ Google:
+ Enable: true
+ ClientID: "0000000000000-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.apps.googleusercontent.com"
+ ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
+{% endcodeblock %}
+
+h2(#oidc). OpenID Connect
+
+With this configuration, users will sign in with a third-party OpenID Connect provider such as GitHub, Auth0, Okta, or PingFederate.
+
+Similar to the Google login section above, you will need to register your Arvados cluster with the provider as an application (relying party). When asked for a redirect URL or callback URL, use @https://ClusterID.example.com/login@ (the external URL of your controller service, plus @/login@).
+
+The provider will supply an issuer URL, client ID, and client secret. Add these to your Arvados configuration.
+
+{% codeblock as yaml %}
+ Login:
+ OpenIDConnect:
+ Enable: true
+ Issuer: https://accounts.example.com/
+ ClientID: "0123456789abcdef"
+ ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
+{% endcodeblock %}
+
+h3. Accepting OpenID bearer tokens as Arvados API tokens
+
+Arvados can also be configured to accept provider-issued access tokens as Arvados API tokens by setting @Login.OpenIDConnect.AcceptAccessToken@ to @true@. This can be useful for integrating third party applications.
-Next, copy the values of *Client ID* and *Client secret* from the Google Developers Console into @Login.GoogleClientID@ and @Login.GoogleClientSecret@ of @config.yml@:
+{% codeblock as yaml %}
+ Login:
+ OpenIDConnect:
+ AcceptAccessToken: true
+{% endcodeblock %}
+
+# If the provider-issued tokens are JWTs, Arvados can optionally check for the scope specified in @Login.OpenIDConnect.AcceptAccessTokenScope@ before attempting to validate them. Tokens withou the configured the scope will not be accepted by Arvados. This is the recommended configuration.
+# Tokens are validated by presenting them to the UserInfo endpoint advertised by the OIDC provider.
+# Once validated, a token is cached and accepted without re-checking for up to 10 minutes.
+# A token that fails validation is cached and will not be re-checked for up to 5 minutes.
+# Network errors and HTTP 5xx responses from the provider's UserInfo endpoint are not cached.
+# The OIDC token cache size is currently limited to 1000 tokens, if the number of distinct tokens used in a 5 minute period is greater than this, tokens may be checked more frequently.
+
+Check the OpenIDConnect section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options.
+
+h2(#ldap). LDAP
+
+With this configuration, authentication uses an external LDAP service like OpenLDAP or Active Directory.
-
+Enable LDAP authentication and provide your LDAP server's host, port, and credentials (if needed to search the directory) in @config.yml@:
+
+{% codeblock as yaml %}
Login:
- GoogleClientID: "0000000000000-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.apps.googleusercontent.com"
- GoogleClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
-
+ LDAP:
+ Enable: true
+ URL: ldap://ldap.example.com:389
+ SearchBindUser: cn=lookupuser,dc=example,dc=com
+ SearchBindPassword: xxxxxxxx
+ SearchBase: ou=Users,dc=example,dc=com
+{% endcodeblock %}
+
+The email address reported by LDAP will be used as primary key for Arvados accounts. This means *users must not be able to edit their own email addresses* in the directory.
+
+Additional configuration settings are available:
+* @StartTLS@ is enabled by default.
+* @StripDomain@ and @AppendDomain@ modify the username entered by the user before searching for it in the directory.
+* @SearchAttribute@ (default @uid@) is the LDAP attribute used when searching for usernames.
+* @SearchFilters@ accepts LDAP filter expressions to control which users can log in.
+
+Check the LDAP section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options.
-h2(#pam). PAM (experimental)
+h2(#pam). PAM
-With this configuration, authentication is done according to the Linux PAM configuration on your controller host.
+With this configuration, authentication is done according to the Linux PAM ("Pluggable Authentication Modules") configuration on your controller host.
Enable PAM authentication in @config.yml@:
-
+{% codeblock as yaml %}
Login:
- PAM: true
-
+ PAM:
+ Enable: true
+{% endcodeblock %}
Check the "default config file":{{site.baseurl}}/admin/config.html for more PAM configuration options.
-h2(#sso). Separate single-sign-on (SSO) server
+The default PAM configuration on most Linux systems uses the local user/password database in @/etc/passwd@ and @/etc/shadow@ for all logins. In this case, in order to log in to Arvados, users must have a UNIX account and password on the controller host itself. This can be convenient for a single-user or test cluster. Configuring a user account with a shell of @/bin/false@ will enable the user to log into Arvados but not log into shell login on the controller host.
-With this configuration, Arvados passes off authentication to a separate SSO server that supports Google, LDAP, and a local password database.
+PAM can also be configured to use other authentication systems such such as NIS or Kerberos. In a production environment, PAM configuration should use the service name ("arvados" by default) and set a separate policy for Arvados login. In this case, Arvados users should not have shell accounts on the controller node.
-See "Install the Single Sign On (SSO) server":install-sso.html
+For information about configuring PAM, refer to the "PAM System Administrator's Guide":http://www.linux-pam.org/Linux-PAM-html/Linux-PAM_SAG.html.