doc/gug/openid-auth.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>OpenID Connect Authentication — Apache Guacamole Manual v1.5.3</title> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/tabs.css" type="text/css" /> <link rel="stylesheet" href="_static/gug.css" type="text/css" />  <script src="_static/jquery.js"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/doctools.js"></script> <script src="_static/sphinx_highlight.js"></script> <script src="_static/tabs.js"></script> <script src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="SAML Authentication" href="saml-auth.html" /> <link rel="prev" title="CAS Authentication" href="cas-auth.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Apache Guacamole </a> <div class="version"> 1.5.3 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Overview</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">User's Guide</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></li> <li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li> <li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="ldap-auth.html">LDAP authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="vault.html">Retrieving secrets from a vault</a></li> <li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">OpenID Connect Authentication</a><ul> <li class="toctree-l2"><a class="reference internal" href="#downloading-the-openid-connect-authentication-extension">Downloading the OpenID Connect authentication extension</a></li> <li class="toctree-l2"><a class="reference internal" href="#installing-support-for-openid-connect">Installing support for OpenID Connect</a><ul> <li class="toctree-l3"><a class="reference internal" href="#configuring-guacamole-for-single-sign-on-with-openid-connect">Configuring Guacamole for single sign-on with OpenID Connect</a></li> <li class="toctree-l3"><a class="reference internal" href="#controlling-login-behavior">Controlling login behavior</a><ul> <li class="toctree-l4"><a class="reference internal" href="#automatically-redirecting-all-unauthenticated-users">Automatically redirecting all unauthenticated users</a></li> <li class="toctree-l4"><a class="reference internal" href="#presenting-unauthenticated-users-with-a-login-screen">Presenting unauthenticated users with a login screen</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#completing-the-installation">Completing the installation</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li> <li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="recording-playback.html">Viewing session recordings in-browser</a></li> <li class="toctree-l1"><a class="reference internal" href="administration.html">Administration</a></li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Developer's Guide</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li> <li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common-js.html">guacamole-common-js</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li> <li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Appendices</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Apache Guacamole</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">OpenID Connect Authentication</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/openid-auth.md.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="openid-connect-authentication"> <h1>OpenID Connect Authentication<a class="headerlink" href="#openid-connect-authentication" title="Permalink to this heading"></a></h1> <p><a class="reference external" href="http://openid.net/connect/">OpenID Connect</a> is a widely-adopted open standard for implementing single sign-on (SSO). <a class="reference external" href="https://oauth.net/articles/authentication/">Not to be confused with OAuth</a>, which is <em>not</em> an authentication protocol, OpenID Connect defines an authentication protocol in the form of a simple identity layer on top of OAuth 2.0.</p> <p>Guacamole’s OpenID Connect support implements the “<a class="reference external" href="https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth">implicit flow</a>” of the OpenID Connect standard, and allows authentication of Guacamole users to be delegated to an identity provider which implements OpenID Connect, removing the need for users to log into Guacamole directly. This module must be layered on top of other authentication extensions that provide connection information, such as the <a class="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">database authentication extension</span></a>, as it only provides user authentication.</p> <section id="downloading-the-openid-connect-authentication-extension"> <span id="openid-downloading"></span><h2>Downloading the OpenID Connect authentication extension<a class="headerlink" href="#downloading-the-openid-connect-authentication-extension" title="Permalink to this heading"></a></h2> <p>Guacamole’s SSO extensions are available separately from the main <code class="docutils literal notranslate"><span class="pre">guacamole.war</span></code>. The link for this and all other officially-supported and compatible extensions for a particular version of Guacamole are provided on the release notes for that version. You can find the release notes for current versions of Guacamole here: <a class="reference external" href="http://guacamole.apache.org/releases/">http://guacamole.apache.org/releases/</a>.</p> <p>The SSO extensions are packaged together in a <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code> file containing one extension for each supported SSO method:</p> <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head"><p>SSO Method</p></th> <th class="head"><p>Extension</p></th> </tr> </thead> <tbody> <tr class="row-even"><td><p><a class="reference internal" href="cas-auth.html"><span class="doc std std-doc">CAS</span></a></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">cas/guacamole-auth-sso-cas-1.5.3.jar</span></code></p></td> </tr> <tr class="row-odd"><td><p><a class="reference internal" href="#"><span class="doc std std-doc">OpenID Connect</span></a></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">openid/guacamole-auth-sso-openid-1.5.3.jar</span></code></p></td> </tr> <tr class="row-even"><td><p><a class="reference internal" href="saml-auth.html"><span class="doc std std-doc">SAML</span></a></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">saml/guacamole-auth-sso-saml-1.5.3.jar</span></code></p></td> </tr> </tbody> </table> <p>The extension for the desired SSO method, in this case <code class="docutils literal notranslate"><span class="pre">guacamole-auth-sso-openid-1.5.3.jar</span></code> from within the <code class="docutils literal notranslate"><span class="pre">openid/</span></code> subdirectory, must ultimately be placed in <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p> </section> <section id="installing-support-for-openid-connect"> <span id="installing-openid-auth"></span><h2>Installing support for OpenID Connect<a class="headerlink" href="#installing-support-for-openid-connect" title="Permalink to this heading"></a></h2> <p>Guacamole extensions are self-contained <code class="docutils literal notranslate"><span class="pre">.jar</span></code> files which are located within the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory. <em>If you are unsure where <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME</span></code> is located on your system, please consult <a class="reference internal" href="configuring-guacamole.html"><span class="doc std std-doc">Configuring Guacamole</span></a> before proceeding.</em></p> <p>To install the OpenID Connect authentication extension, you must:</p> <ol class="arabic simple"> <li><p>Create the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory, if it does not already exist.</p></li> <li><p>Copy <code class="docutils literal notranslate"><span class="pre">guacamole-auth-sso-openid-1.5.3.jar</span></code> within <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p></li> <li><p>Configure Guacamole to use OpenID Connect authentication, as described below.</p></li> </ol> <section id="configuring-guacamole-for-single-sign-on-with-openid-connect"> <span id="guac-openid-config"></span><h3>Configuring Guacamole for single sign-on with OpenID Connect<a class="headerlink" href="#configuring-guacamole-for-single-sign-on-with-openid-connect" title="Permalink to this heading"></a></h3> <p>Guacamole’s OpenID connect support requires several properties which describe both the identity provider and the Guacamole deployment. These properties are <em>absolutely required in all cases</em>, as they dictate how Guacamole should connect to the identity provider, how it should verify the identity provider’s response, and how the identity provider should redirect users back to Guacamole once their identity has been confirmed:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">openid-authorization-endpoint</span></code></dt><dd><p>The authorization endpoint (URI) of the OpenID service.</p> <p>This value should be provided to you by the identity provider. For identity providers that implement <a class="reference external" href="https://openid.net/specs/openid-connect-discovery-1_0.html">OpenID Connect Discovery</a>, this value can be retrieved from the <code class="docutils literal notranslate"><span class="pre">authorization_endpoint</span></code> property of the JSON file hosted at <code class="samp docutils literal notranslate"><em><span class="pre">https://identity-provider</span></em><span class="pre">/.well-known/openid-configuration</span></code>, where <code class="docutils literal notranslate"><span class="pre">https://identity-provider</span></code> is the base URL of the identity provider.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-jwks-endpoint</span></code></dt><dd><p>The endpoint (URI) of the JWKS service which defines how received ID tokens (<a class="reference external" href="https://jwt.io/">JSON Web Tokens</a> or JWTs) shall be validated.</p> <p>This value should be provided to you by the identity provider. For identity providers that implement <a class="reference external" href="https://openid.net/specs/openid-connect-discovery-1_0.html">OpenID Connect Discovery</a>, this value can be retrieved from the <code class="docutils literal notranslate"><span class="pre">jwks_uri</span></code> property of the JSON file hosted at <code class="samp docutils literal notranslate"><em><span class="pre">https://identity-provider</span></em><span class="pre">/.well-known/openid-configuration</span></code>, where <code class="docutils literal notranslate"><span class="pre">https://identity-provider</span></code> is the base URL of the identity provider.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-issuer</span></code></dt><dd><p>The issuer to expect for all received ID tokens.</p> <p>This value should be provided to you by the identity provider. For identity providers that implement <a class="reference external" href="https://openid.net/specs/openid-connect-discovery-1_0.html">OpenID Connect Discovery</a>, this value can be retrieved from the <code class="docutils literal notranslate"><span class="pre">issuer</span></code> property of the JSON file hosted at <code class="samp docutils literal notranslate"><em><span class="pre">https://identity-provider</span></em><span class="pre">/.well-known/openid-configuration</span></code>, where <code class="docutils literal notranslate"><span class="pre">https://identity-provider</span></code> is the base URL of the identity provider.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-client-id</span></code></dt><dd><p>The OpenID client ID which should be submitted to the OpenID service when necessary. This value is typically provided to you by the OpenID service when OpenID credentials are generated for your application.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-redirect-uri</span></code></dt><dd><p>The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Guacamole after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Guacamole.</p> </dd> </dl> <p>Additional optional properties are available to control how claims within received ID tokens are used to derive the user’s Guacamole username, any associated groups, the OpenID scopes requested when user identities are confirmed, and to control the maximum amount of time allowed for various aspects of the conversation with the identity provider:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">openid-username-claim-type</span></code></dt><dd><p>The claim type within any valid JWT that contains the authenticated user’s username. By default, the “<code class="docutils literal notranslate"><span class="pre">email</span></code>” claim type is used.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-groups-claim-type</span></code></dt><dd><p>The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “<code class="docutils literal notranslate"><span class="pre">groups</span></code>” claim type is used.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-scope</span></code></dt><dd><p>The space-separated list of OpenID scopes to request. OpenID scopes determine the information returned within the OpenID token, and thus affect what values can be used as an authenticated user’s username. To be compliant with OpenID, at least “<code class="docutils literal notranslate"><span class="pre">openid</span> <span class="pre">profile</span></code>” must be requested. By default, “<code class="docutils literal notranslate"><span class="pre">openid</span> <span class="pre">email</span> <span class="pre">profile</span></code>” is used.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-allowed-clock-skew</span></code></dt><dd><p>The amount of clock skew tolerated for timestamp comparisons between the Guacamole server and OpenID service clocks, in seconds. By default, clock skew of up to 30 seconds is tolerated.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-max-token-validity</span></code></dt><dd><p>The maximum amount of time that an OpenID token should remain valid, in minutes. By default, each OpenID token remains valid for 300 minutes (5 hours).</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">openid-max-nonce-validity</span></code></dt><dd><p>The maximum amount of time that a nonce generated by the Guacamole server should remain valid, in minutes. As each OpenID request has a unique nonce value, this imposes an upper limit on the amount of time any particular OpenID request can result in successful authentication within Guacamole. By default, each generated nonce expires after 10 minutes.</p> </dd> </dl> </section> <section id="controlling-login-behavior"> <span id="openid-login"></span><h3>Controlling login behavior<a class="headerlink" href="#controlling-login-behavior" title="Permalink to this heading"></a></h3> <p>Guacamole loads authentication extensions in order of priority, and evaluates authentication attempts in this same order. This has implications for how the Guacamole login process behaves when an SSO extension is present:</p> <dl class="simple myst"> <dt>If the SSO extension has priority:</dt><dd><p>Users that are not yet authenticated will be immediately redirected to the configured identity provider. They will not see a Guacamole login screen.</p> </dd> <dt>If a non-SSO extension has priority:</dt><dd><p>Users that are not yet authenticated will be presented with a Guacamole login screen. Additionally, links to the configured identity provider(s) will be available for users that wish to log in using SSO.</p> </dd> </dl> <p>The default priority of extensions is dictated by their filenames, with extensions that sort earlier alphabetically having higher priority than others. This can be overridden <a class="reference internal" href="configuring-guacamole.html#initial-setup"><span class="std std-ref">by setting the <code class="docutils literal notranslate"><span class="pre">extension-priority</span></code> property within <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></code></span></a>.</p> <section id="automatically-redirecting-all-unauthenticated-users"> <h4>Automatically redirecting all unauthenticated users<a class="headerlink" href="#automatically-redirecting-all-unauthenticated-users" title="Permalink to this heading"></a></h4> <p>To ensure users are redirected to the OpenID identity provider immediately (without a Guacamole login screen), ensure the OpenID extension has priority over all others:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>extension-priority: openid </pre></div> </div> </section> <section id="presenting-unauthenticated-users-with-a-login-screen"> <h4>Presenting unauthenticated users with a login screen<a class="headerlink" href="#presenting-unauthenticated-users-with-a-login-screen" title="Permalink to this heading"></a></h4> <p>To ensure users are given a normal Guacamole login screen and have the option to log in with traditional credentials <em>or</em> with OpenID, ensure the OpenID extension does not have priority:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>extension-priority: *, openid </pre></div> </div> </section> </section> <section id="completing-the-installation"> <span id="completing-openid-install"></span><h3>Completing the installation<a class="headerlink" href="#completing-the-installation" title="Permalink to this heading"></a></h3> <p>Guacamole will only reread <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></code> and load newly-installed extensions during startup, so your servlet container will need to be restarted before OpenID Connect authentication can be used. <em>Doing this will disconnect all active users, so be sure that it is safe to do so prior to attempting installation.</em> When ready, restart your servlet container and give the new authentication a try.</p> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="cas-auth.html" class="btn btn-neutral float-left" title="CAS Authentication" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="saml-auth.html" class="btn btn-neutral float-right" title="SAML Authentication" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2023 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script>  <script type="text/javascript"> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-75289145-1', 'auto'); ga('send', 'pageview'); </script> </body> </html>

doc/gug/openid-auth.html (347 lines of code) (raw):