20123: Add detail about OIDC token validation/cache implementation.
[arvados.git] / doc / install / setup-login.html.textile.liquid
index 21b986fb89746600ad2647e4246881edb19c0b48..0de51eae2dcbae57e9385f1f1edd6da324c90801 100644 (file)
@@ -45,7 +45,11 @@ Use the <a href="https://console.developers.google.com" target="_blank">Google D
 
 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.
+
+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:
@@ -56,6 +60,14 @@ With this configuration, users will sign in with a third-party OpenID Connect pr
         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
 {% 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.
 
 h2(#ldap). LDAP