20123: Add detail about OIDC token validation/cache implementation.

[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..0de51eae2dcbae57e9385f1f1edd6da324c90801 100644 (file)
--- a/doc/install/setup-login.html.textile.liquid
+++ b/doc/install/setup-login.html.textile.liquid
@@ -35,26 +35,38 @@ 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 %}
+
+Arvados can also be configured to accept provider-issued access tokens as Arvados API tokens. This can be useful for integrating third party applications.
+* If the provider-issued tokens are JWTs, Arvados can optionally check them for a specified scope before attempting to validate them. 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 rejected without re-checking for up to 5 minutes.
+* Validation errors such as 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.
 
 Check the OpenIDConnect section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options.
 
@@ -64,7 +76,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 +84,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 +102,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.