doc/1.4.0/gug/cas-auth.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>CAS Authentication — Apache Guacamole Manual v1.4.0</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <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 type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/tabs.js"></script> <script type="text/javascript" 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="OpenID Connect Authentication" href="openid-auth.html" /> <link rel="prev" title="Encrypted JSON authentication" href="json-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.4.0 </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" /> <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="main navigation"> <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="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 current"><a class="current reference internal" href="#">CAS Authentication</a><ul> <li class="toctree-l2"><a class="reference internal" href="#downloading-the-cas-authentication-extension">Downloading the CAS authentication extension</a></li> <li class="toctree-l2"><a class="reference internal" href="#installing-cas-authentication">Installing CAS authentication</a><ul> <li class="toctree-l3"><a class="reference internal" href="#configuring-guacamole-for-cas-authentication">Configuring Guacamole for CAS Authentication</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> <li class="toctree-l3"><a class="reference internal" href="#using-cas-clearpass">Using CAS ClearPass</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></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="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="top navigation"> <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="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home"></a> »</li> <li>CAS Authentication</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/cas-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"> <div class="section" id="cas-authentication"> <h1>CAS Authentication<a class="headerlink" href="#cas-authentication" title="Permalink to this headline">¶</a></h1> <p>CAS is an open-source Single Sign On (SSO) provider that allows multiple applications and services to authenticate against it and brokers those authentication requests to a back-end authentication provider. This module allows Guacamole to redirect to CAS for authentication and user services. This module must be layered on top of other authentication extensions that provide connection information, as it only provides user authentication.</p> <div class="section" id="downloading-the-cas-authentication-extension"> <span id="cas-downloading"></span><h2>Downloading the CAS authentication extension<a class="headerlink" href="#downloading-the-cas-authentication-extension" title="Permalink to this headline">¶</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="colwidths-auto 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="#"><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.4.0.jar</span></code></p></td> </tr> <tr class="row-odd"><td><p><a class="reference internal" href="openid-auth.html"><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.4.0.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.4.0.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-cas-1.4.0.jar</span></code> from within the <code class="docutils literal notranslate"><span class="pre">cas/</span></code> subdirectory, must ultimately be placed in <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p> </div> <div class="section" id="installing-cas-authentication"> <span id="installing-cas-auth"></span><h2>Installing CAS authentication<a class="headerlink" href="#installing-cas-authentication" title="Permalink to this headline">¶</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 CAS authentication extension, you must:</p> <ol class="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-cas-1.4.0.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 CAS authentication, as described below.</p></li> </ol> <div class="section" id="configuring-guacamole-for-cas-authentication"> <span id="guac-cas-config"></span><h3>Configuring Guacamole for CAS Authentication<a class="headerlink" href="#configuring-guacamole-for-cas-authentication" title="Permalink to this headline">¶</a></h3> <p>Guacamole’s CAS support requires specifying two properties that describe the CAS authentication server and the Guacamole deployment. These properties are <em>absolutely required in all cases</em>, as they dictate how Guacamole should connect to the CAS and how CAS 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">cas-authorization-endpoint</span></code></dt><dd><p>The URL of the CAS authentication server. This should be the full path to the base of the CAS installation.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cas-redirect-uri</span></code></dt><dd><p>The URI to redirect back to upon successful authentication. Normally this will be the full URL of your Guacamole installation.</p> </dd> </dl> <p>Additional optional properties are available to control how CAS tokens are processed, including whether <a class="reference internal" href="#cas-clearpass"><span class="std std-ref">CAS ClearPass</span></a> should be used and how user group memberships should be derived:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">cas-clearpass-key</span></code></dt><dd><p>If using CAS ClearPass to pass the SSO password to Guacamole, this parameter specifies the private key file to use to decrypt the password. See <a class="reference internal" href="#cas-clearpass"><span class="std std-ref">the section on ClearPass</span></a> below.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cas-group-attribute</span></code></dt><dd><p>The CAS attribute that determines group membership, typically “memberOf”. This parameter is only required if using CAS to define user group memberships. If omitted, groups aren’t retrieved from CAS, and all other group-related properties for CAS are ignored.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cas-group-format</span></code></dt><dd><p>The format that CAS will use for its group names. Possible values are <code class="docutils literal notranslate"><span class="pre">plain</span></code>, for groups that are simple text names, or <code class="docutils literal notranslate"><span class="pre">ldap</span></code>, for groups that are represented as LDAP DNs. If set to <code class="docutils literal notranslate"><span class="pre">ldap</span></code>, group names are always determined from the last (leftmost) attribute of the DN. If omitted, <code class="docutils literal notranslate"><span class="pre">plain</span></code> is used by default.</p> <p>This property has no effect if cas-group-attribute is not set.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cas-group-ldap-base-dn</span></code></dt><dd><p>The base DN to require for LDAP-formatted CAS groups. If specified, only CAS groups beneath this DN will be included, and all other CAS groups will be ignored.</p> <p>This property has no effect if cas-group-format is not <code class="docutils literal notranslate"><span class="pre">ldap</span></code>.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cas-group-ldap-attribute</span></code></dt><dd><p>The LDAP attribute to require for LDAP-formatted CAS groups. If specified, only CAS groups that use this attribute for the name of the group will be included. Note that LDAP group names are <em>always determined from the last (leftmost) attribute of the DN</em>. Specifying this property will only have the effect of ignoring any groups that do not use the specified attribute to represent the group name.</p> <p>This property has no effect if cas-group-format is not <code class="docutils literal notranslate"><span class="pre">ldap</span></code>.</p> </dd> </dl> </div> <div class="section" id="controlling-login-behavior"> <span id="cas-login"></span><h3>Controlling login behavior<a class="headerlink" href="#controlling-login-behavior" title="Permalink to this headline">¶</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> <div class="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 headline">¶</a></h4> <p>To ensure users are redirected to the CAS identity provider immediately (without a Guacamole login screen), ensure the CAS extension has priority over all others:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>extension-priority: cas </pre></div> </div> </div> <div class="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 headline">¶</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 CAS, ensure the CAS extension does not have priority:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>extension-priority: *, cas </pre></div> </div> </div> </div> <div class="section" id="completing-the-installation"> <span id="completing-cas-install"></span><h3>Completing the installation<a class="headerlink" href="#completing-the-installation" title="Permalink to this headline">¶</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 CAS 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> </div> <div class="section" id="using-cas-clearpass"> <span id="cas-clearpass"></span><h3>Using CAS ClearPass<a class="headerlink" href="#using-cas-clearpass" title="Permalink to this headline">¶</a></h3> <p>CAS has a function called ClearPass that can be used to cache the password used for SSO authentication and make that available to services at a later time. Configuring the CAS server for ClearPass is beyond the scope of this article - more information can be found on the Apereo CAS wiki at the following URL: <a class="reference external" href="https://apereo.github.io/cas">https://apereo.github.io/cas</a>.</p> <p>Once you have CAS configured for credential caching, you need to configure the service with a keypair for passing the credential securely. The public key gets installed on the CAS server, while the private key gets configured with the cas-clearpass-key property. The private key file needs to be in RSA PKCS8 format.</p> </div> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="openid-auth.html" class="btn btn-neutral float-right" title="OpenID Connect Authentication" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> <a href="json-auth.html" class="btn btn-neutral float-left" title="Encrypted JSON authentication" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2021 <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 type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/1.4.0/gug/cas-auth.html (315 lines of code) (raw):