doc/install/setup-login.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Set up web based login
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Select one of the following login mechanisms for your cluster.
  13
  14 # If all users will authenticate with Google, "configure Google login":#google.
  15 # If all users will authenticate with an OpenID Connect provider (other than Google), "configure OpenID Connect":#oidc.
  16 # If all users will authenticate with an existing LDAP service, "configure LDAP":#ldap.
  17 # If all users will authenticate using PAM as configured on your controller node, "configure PAM":#pam.
  18
  19 h2(#google). Google login
  20
  21 With this configuration, users will sign in with their Google accounts.
  22
  23 Use the <a href="https://console.developers.google.com" target="_blank">Google Developers Console</a> to create a set of client credentials.
  24 # Select or create a project.
  25 # Click *+ Enable APIs and Services*.
  26 #* Search for *People API* and click *Enable API*.
  27 #* Navigate back to the main "APIs & Services" page.
  28 # On the sidebar, click *OAuth consent screen*.
  29 #* On consent screen settings, enter your identifying details.
  30 #* Under *Authorized domains* add your domain (@example.com@).
  31 #* Click *Save*.
  32 # On the sidebar, click *Credentials*, then click *Create credentials*&rarr;*OAuth client ID*
  33 # Under *Application type* select *Web application*.
  34 # Add the JavaScript origin: @https://ClusterID.example.com/@
  35 # Add the Redirect URI: @https://ClusterID.example.com/login@
  36 # Copy the values of *Client ID* and *Client secret* to the @Login.Google@ section of @config.yml@.
  37
  38 {% codeblock as yaml %}
  39     Login:
  40       Google:
  41         Enable: true
  42         ClientID: "0000000000000-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.apps.googleusercontent.com"
  43         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  44 {% endcodeblock %}
  45
  46 h2(#oidc). OpenID Connect
  47
  48 With this configuration, users will sign in with a third-party OpenID Connect provider such as GitHub, Auth0, Okta, or PingFederate.
  49
  50 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@).
  51
  52 The provider will supply an issuer URL, client ID, and client secret. Add these to your Arvados configuration.
  53
  54 {% codeblock as yaml %}
  55     Login:
  56       OpenIDConnect:
  57         Enable: true
  58         Issuer: https://accounts.example.com/
  59         ClientID: "0123456789abcdef"
  60         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  61 {% endcodeblock %}
  62
  63 h3. Accepting OpenID bearer tokens as Arvados API tokens
  64
  65 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.
  66
  67 {% codeblock as yaml %}
  68     Login:
  69       OpenIDConnect:
  70         AcceptAccessToken: true
  71         AcceptAccessTokenScope: "arvados"
  72 {% endcodeblock %}
  73
  74 # If the provider-issued tokens are JWTs, and @Login.OpenIDConnect.AcceptAccessTokenScope@ is not empty, Arvados will check that the token contains the configured scope, and reject tokens that do not have the configured scope.  This can be used to control which users or applications are permitted to access your Arvados instance.
  75 # Tokens are validated by presenting them to the UserInfo endpoint advertised by the OIDC provider.
  76 # Once validated, a token is cached and accepted without re-checking for up to 10 minutes.
  77 # A token that fails validation is cached and will not be re-checked for up to 5 minutes.
  78 # Network errors and HTTP 5xx responses from the provider's UserInfo endpoint are not cached.
  79 # 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.
  80
  81 Check the OpenIDConnect section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options.
  82
  83 h2(#ldap). LDAP
  84
  85 With this configuration, authentication uses an external LDAP service like OpenLDAP or Active Directory.
  86
  87 Enable LDAP authentication and provide your LDAP server's host, port, and credentials (if needed to search the directory) in @config.yml@:
  88
  89 {% codeblock as yaml %}
  90     Login:
  91       LDAP:
  92         Enable: true
  93         URL: ldap://ldap.example.com:389
  94         SearchBindUser: cn=lookupuser,dc=example,dc=com
  95         SearchBindPassword: xxxxxxxx
  96         SearchBase: ou=Users,dc=example,dc=com
  97 {% endcodeblock %}
  98
  99 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.
 100
 101 Additional configuration settings are available:
 102 * @StartTLS@ is enabled by default.
 103 * @StripDomain@ and @AppendDomain@ modify the username entered by the user before searching for it in the directory.
 104 * @SearchAttribute@ (default @uid@) is the LDAP attribute used when searching for usernames.
 105 * @SearchFilters@ accepts LDAP filter expressions to control which users can log in.
 106
 107 Check the LDAP section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options.
 108
 109 h2(#pam). PAM
 110
 111 With this configuration, authentication is done according to the Linux PAM ("Pluggable Authentication Modules") configuration on your controller host.
 112
 113 Enable PAM authentication in @config.yml@:
 114
 115 {% codeblock as yaml %}
 116     Login:
 117       PAM:
 118         Enable: true
 119 {% endcodeblock %}
 120
 121 Check the "default config file":{{site.baseurl}}/admin/config.html for more PAM configuration options.
 122
 123 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.
 124
 125 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.
 126
 127 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.