You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@guacamole.apache.org by mike-jumper <gi...@git.apache.org> on 2018/02/02 05:16:06 UTC
[GitHub] guacamole-manual pull request #33: GUACAMOLE-197: RADIUS Authentication Exte...
Github user mike-jumper commented on a diff in the pull request:
https://github.com/apache/guacamole-manual/pull/33#discussion_r165559998
--- Diff: src/chapters/radius-auth.xml ---
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="radius-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>RADIUS Authentication</title>
+ <indexterm>
+ <primary>RADIUS Authentication</primary>
+ </indexterm>
+ <para>Guacamole supports delegating authentication to a RADIUS service, such as FreeRADIUS, to
+ validate username and password combinations, and to support multi-factor authentication. This
+ authentication method must be layered on top of some other authentication extension, such as
+ those available from the main project website, in order to provide access to actual
+ connections.</para>
+ <section xml:id="radius-downloading">
+ <title>Downloading the RADIUS authentication extension</title>
+ <para>Due to licensing limitations on dependencies for the RADIUS extension, the extension
+ cannot be distributed in a binary format. This means that, in order to use this extension
+ you will need to build the Guacamole client code yourself. You can find build instructions
+ for Guacamole client in <xref linkend="installing-guacamole"/>.</para>
+ </section>
+ <section xml:id="installing-radius-auth">
+ <title>Installing RADIUS authentication</title>
+ <para>The RADIUS extension must be explicitly enabled during build time in order to generate
+ the binaries and resulting JAR file. This is done by adding the flag <option>-Plgpl-extensions</option>
+ to the MAVEN command line during the build, and should result in the output below:</para>
+ <informalexample>
+ <screen><prompt>$</prompt> <userinput>mvn clean package -Plgpl-extensions</userinput>
+<computeroutput>[INFO] --- maven-assembly-plugin:2.5.3:single (make-source-archive) @ guacamole-client ---
+[INFO] Reading assembly descriptor: project-assembly.xml
+[INFO] Building tar: /home/guac/guacamole-client/target/guacamole-client-0.9.14.tar.gz
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO]
+[INFO] guacamole-common .................................. SUCCESS [6.037s]
+[INFO] guacamole-ext ..................................... SUCCESS [5.382s]
+[INFO] guacamole-common-js ............................... SUCCESS [0.751s]
+[INFO] guacamole ......................................... SUCCESS [9.767s]
+[INFO] guacamole-auth-cas ................................ SUCCESS [2.811s]
+[INFO] guacamole-auth-duo ................................ SUCCESS [2.441s]
+[INFO] guacamole-auth-header ............................. SUCCESS [1.875s]
+[INFO] guacamole-auth-jdbc ............................... SUCCESS [0.277s]
+[INFO] guacamole-auth-jdbc-base .......................... SUCCESS [2.144s]
+[INFO] guacamole-auth-jdbc-mysql ......................... SUCCESS [5.637s]
+[INFO] guacamole-auth-jdbc-postgresql .................... SUCCESS [5.465s]
+[INFO] guacamole-auth-jdbc-sqlserver ..................... SUCCESS [5.398s]
+[INFO] guacamole-auth-jdbc-dist .......................... SUCCESS [0.824s]
+[INFO] guacamole-auth-ldap ............................... SUCCESS [2.743s]
+[INFO] guacamole-auth-noauth ............................. SUCCESS [0.964s]
+[INFO] guacamole-auth-openid ............................. SUCCESS [2.533s]
+[INFO] guacamole-example ................................. SUCCESS [0.888s]
+[INFO] guacamole-playback-example ........................ SUCCESS [0.628s]
+[INFO] guacamole-auth-radius ............................. SUCCESS [17.729s]
+[INFO] guacamole-client .................................. SUCCESS [5.645s]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1:20.134s
+[INFO] Finished at: Wed Jan 31 09:45:41 EST 2018
+[INFO] Final Memory: 47M/749M
+[INFO] ------------------------------------------------------------------------</computeroutput>
+<prompt>$</prompt></screen>
+ </informalexample>
+
+ <para>After the build completes successfully, the extension will be in the
+ <filename>extensions/guacamole-auth-radius/target/</filename> directory, and will be
+ called guacamole-auth-radius-0.9.14.jar. This extension file can be copied to
+ 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>Extensions are loaded in alphabetical order, and authentication is performed
+ in the order in which the extensions were loaded. If you are stacking the
+ RADIUS extension with another extension, like the JDBC extension, in order to
+ store connection information, you may need to change the name of the RADIUS
+ extension such that it is evaluated prior to the JDBC extension - otherwise
+ an authentication failure in one of the previous modules may block the RADIUS
+ module from ever being evaluated.</para>
+
+ <para>To install the RADIUS 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-radius-0.9.14.jar</filename> into
+ <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </step>
+ <step>
+ <para>Configure Guacamole to use RADIUS authentication, as described
+ below.</para>
+ </step>
+ </procedure>
+ </section>
+ <section xml:id="guac-radius-config">
+ <title>Configuring Guacamole for RADIUS authentication</title>
+ <indexterm>
+ <primary>configuring RADIUS authentication</primary>
+ </indexterm>
+ <indexterm>
+ <primary>RADIUS authentication</primary>
+ <secondary>configuration</secondary>
+ </indexterm>
+ <para>This extension provides several configuration properties in order
+ to communicate properly with the RADIUS server to which it needs to authenticate. It is
+ important that you know several key pieces of information about the RADIUS server -
+ at a minimum, the server name or IP, the Authentication port, the authentication
+ protocol in use by the server, and the shared secret for the RADIUS client. If you
+ are responsible for the RADIUS server, you'll need to properly configure these items
+ to get Guacamole to authenticate properly. If you're not responsible for the RADIUS
+ server you will need to work with the administrator to get all of the necessary
+ configuration items for the server. These items will need to be configured in the
+ <link linkend="initial-setup"><filename>guacamole.properties</filename></link>
+ file.</para>
+ <variablelist>
+ <varlistentry>
+ <term><property>radius-hostname</property></term>
+ <listitem>
+ <para>The RADIUS server to authenticate against. If not specified,
+ localhost will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-auth-port</property></term>
+ <listitem>
+ <para>The RADIUS authentication port on which the RADIUS service is
+ is listening. If not specified, the default of 1812 will be
+ used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-shared-secret</property></term>
+ <listitem>
+ <para>The shared secret to use when talking to the RADIUS server. This
+ parameter is required and defaults to null if not specified.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-auth-protocol</property></term>
+ <listitem>
+ <para>The authentication protocol to use when talking to the RADIUS server.
+ This parameter is required for the extension to operate. Supported
+ values are: pap, chap, mschapv1, mschapv2, eap-md5, eap-tls, and eap-ttls.
+ Support for PEAP is implemented inside the extension, but, due to a regression
+ in the JRadius implementation, it is currently broken. Also, if you specify
+ eap-ttls you will also need to specify the
+ <property>radius-eap-ttls-inner-protocol</property> parameter in order to
+ properly configure the protocol used inside the EAP TTLS tunnel.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-file</property></term>
+ <listitem>
+ <para>The combination certificate and private key pair to use for TLS-based
+ RADIUS protocols that require a client-side certificate. The file should be
+ present in the GUACAMOLE_HOME directory, and should be readable by the user
+ running Tomcat (or whatever Java servlet container you're running). If not
+ specified, this defaults to radius.pem.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-type</property></term>
+ <listitem>
+ <para>The type of the key file specified by the <property>radius-key-file</property>
+ parameter. If not specified, this defaults to pkcs12, the default used by
+ the JRadius library.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-password</property></term>
+ <listitem>
+ <para>The password of the private key specified in the
+ <property>radius-key-file</property> parameter. Defaults to null if not specified.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>ca-key-file</property></term>
+ <listitem>
+ <para>The file that stores the certificate authority certificates for the
+ connection to the RADIUS server. Defaults to no file - if specified, the
+ file must be present in the GUACAMOLE_HOME directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>ca-key-type</property></term>
+ <listitem>
+ <para>The type of file store used for the certificate authority. If not
+ specified this defaults to pem.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>ca-key-password</property></term>
+ <listitem>
+ <para>The password used to protect the certificate authority store, if
+ any. Default to null.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-trust-all</property></term>
+ <listitem>
+ <para>Trust all server certificates without verifying against a CA file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-retries</property></term>
+ <listitem>
+ <para>The number of times the client will retry the connection to the
+ RADIUS server and not receive a response before giving up. The default
+ is 5.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-timeout</property></term>
+ <listitem>
+ <para>The timeout for a RADIUS connection in seconds. The default is
+ 60 seconds.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-eap-ttls-inner-protocol</property></term>
+ <listitem>
+ <para>When EAP-TTLS is used, this parameter specifies the inner (tunneled)
+ protocol to use talking to the RADIUS server. It is required when the
+ <property>radius-auth-protocol</property> parameter is set to eap-ttls.</para>
--- End diff --
What is the behavior of this parameter if `radius-auth-protocol` is *not* set to `eap-ttls`? If it has no effect, we should note that here.
---