| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <chapter xml:id="cas-auth" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" |
| xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> |
| <title>CAS Authentication</title> |
| <indexterm> |
| <primary>CAS Authentication</primary> |
| </indexterm> |
| <para>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. |
| </para> |
| <section xml:id="cas-downloading"> |
| <title>Downloading the CAS authentication extension</title> |
| <para>The CAS authentication extension is available separately from the main |
| <filename>guacamole.war</filename>. 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: <link |
| xlink:href="http://guacamole.apache.org/releases/" |
| >http://guacamole.apache.org/releases/</link>.</para> |
| <para>The CAS authentication extension is packaged as a <filename>.tar.gz</filename> |
| file containing only the extension itself, |
| <filename>guacamole-auth-cas-1.3.0.jar</filename>, which must |
| ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </section> |
| <section xml:id="installing-cas-auth"> |
| <title>Installing CAS authentication</title> |
| <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are |
| located within the <filename>GUACAMOLE_HOME/extensions</filename> directory. |
| <emphasis>If you are unsure where <varname>GUACAMOLE_HOME</varname> is located on |
| your system, please consult <xref linkend="configuring-guacamole"/> before |
| proceeding.</emphasis></para> |
| <para>To install the CAS authentication extension, you must:</para> |
| <procedure> |
| <step> |
| <para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it |
| does not already exist.</para> |
| </step> |
| <step> |
| <para>Copy <filename>guacamole-auth-cas-1.3.0.jar</filename> within |
| <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </step> |
| <step> |
| <para>Configure Guacamole to use CAS authentication, as described |
| below.</para> |
| </step> |
| </procedure> |
| <section xml:id="guac-cas-config"> |
| <title>Configuring Guacamole for CAS Authentication</title> |
| <indexterm> |
| <primary>configuring CAS authentication</primary> |
| </indexterm> |
| <indexterm> |
| <primary>CAS authentication</primary> |
| <secondary>configuration</secondary> |
| </indexterm> |
| <para>Guacamole's CAS support requires specifying two properties that describe the CAS |
| authentication server and the Guacamole deployment. These properties are |
| <emphasis>absolutely required in all cases</emphasis>, 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:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>cas-authorization-endpoint</property></term> |
| <listitem> |
| <para>The URL of the CAS authentication server. This should be the full |
| path to the base of the CAS installation.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>cas-redirect-uri</property></term> |
| <listitem> |
| <para>The URI to redirect back to upon successful authentication. Normally |
| this will be the full URL of your Guacamole installation.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>Additional optional properties are available to control how CAS tokens are |
| processed, including whether <link linkend="cas-clearpass">CAS ClearPass</link> |
| should be used and how user group memberships should be derived:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>cas-clearpass-key</property></term> |
| <listitem> |
| <para>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 <link linkend="cas-clearpass">the section on ClearPass</link> |
| below.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>cas-group-attribute</property></term> |
| <listitem> |
| <para>The CAS attribute that determines group membership, typically |
| "<property>memberOf</property>". 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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>cas-group-format</property></term> |
| <listitem> |
| <para>The format that CAS will use for its group names. Possible values are |
| <constant>plain</constant>, for groups that are simple text names, |
| or <constant>ldap</constant>, for groups that are represented as LDAP |
| DNs. If set to <constant>ldap</constant>, group names are always |
| determined from the last (leftmost) attribute of the DN. If omitted, |
| <constant>plain</constant> is used by default.</para> |
| <para>This property has no effect if |
| <property>cas-group-attribute</property> is not set.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>cas-group-ldap-base-dn</property></term> |
| <listitem> |
| <para>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.</para> |
| <para>This property has no effect if <property>cas-group-format</property> |
| is not <constant>ldap</constant>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>cas-group-ldap-attribute</property></term> |
| <listitem> |
| <para>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 <emphasis>always |
| determined from the last (leftmost) attribute of the DN</emphasis>. |
| Specifying this property will only have the effect of ignoring any |
| groups that do not use the specified attribute to represent the group |
| name.</para> |
| <para>This property has no effect if <property>cas-group-format</property> |
| is not <constant>ldap</constant>.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </section> |
| <section xml:id="completing-cas-install"> |
| <title>Completing the installation</title> |
| <para>Guacamole will only reread <filename>guacamole.properties</filename> and load |
| newly-installed extensions during startup, so your servlet container will need to be |
| restarted before CAS authentication can be used. <emphasis>Doing this will |
| disconnect all active users, so be sure that it is safe to do so prior to |
| attempting installation.</emphasis> When ready, restart your servlet container |
| and give the new authentication a try.</para> |
| </section> |
| <section xml:id="cas-clearpass"> |
| <title>Using CAS ClearPass</title> |
| <para>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: <link xlink:href="https://apereo.github.io/cas"> |
| https://apereo.github.io/cas</link>.</para> |
| <para>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 <property>cas-clearpass-key</property> property. The private key |
| file needs to be in RSA PKCS8 format.</para> |
| </section> |
| </section> |
| </chapter> |