Merge branch '21383-misc-fixes'. Refs #21383

[arvados.git] / 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 47d0c21beafcfb2bac714a75e561a340ffef029c..a9991f642e6b048d52cf03c4dc6c04ea239b6c0f 100644 (file)
--- a/doc/install/setup-login.html.textile.liquid
+++ b/doc/install/setup-login.html.textile.liquid
@@ -35,26 +35,48 @@ Use the <a href="https://console.developers.google.com" target="_blank">Google D
 # 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@.
 
-<pre>
+{% codeblock as yaml %}
     Login:
       Google:
         Enable: true
         ClientID: "0000000000000-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.apps.googleusercontent.com"
         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
-</pre>
+{% endcodeblock %}
 
 h2(#oidc). OpenID Connect
 
-With this configuration, users will sign in with a third-party OpenID Connect provider. The provider will supply appropriate values for the issuer URL, client ID, and client secret config entries.
+With this configuration, users will sign in with a third-party OpenID Connect provider such as GitHub, Auth0, Okta, or PingFederate.
 
-<pre>
+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"
-</pre>
+{% 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.
+
+{% codeblock as yaml %}
+    Login:
+      OpenIDConnect:
+        AcceptAccessToken: true
+        AcceptAccessTokenScope: "arvados"
+{% endcodeblock %}
+
+# 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.
+# 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.
 
@@ -64,7 +86,7 @@ With this configuration, authentication uses an external LDAP service like OpenL
 
 Enable LDAP authentication and provide your LDAP server's host, port, and credentials (if needed to search the directory) in @config.yml@:
 
-<pre>
+{% codeblock as yaml %}
     Login:
       LDAP:
         Enable: true
@@ -72,7 +94,7 @@ Enable LDAP authentication and provide your LDAP server's host, port, and creden
         SearchBindUser: cn=lookupuser,dc=example,dc=com
         SearchBindPassword: xxxxxxxx
         SearchBase: ou=Users,dc=example,dc=com
-</pre>
+{% 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.
 
@@ -90,11 +112,11 @@ With this configuration, authentication is done according to the Linux PAM ("Plu
 
 Enable PAM authentication in @config.yml@:
 
-<pre>
+{% codeblock as yaml %}
     Login:
       PAM:
         Enable: true
-</pre>
+{% endcodeblock %}
 
 Check the "default config file":{{site.baseurl}}/admin/config.html for more PAM configuration options.