GUACAMOLE-197: Initial commit for chapter for configuring RADIUS authentication 
in Guacamole.


Branch: refs/heads/master
Commit: 387ceb2753e34490b20a20eca2d43cafb1b71508
Parents: db9a8ad
Author: Nick Couchman <>
Authored: Mon Feb 13 12:19:01 2017 -0500
Committer: Nick Couchman <>
Committed: Wed Jan 31 08:44:44 2018 -0500

 src/chapters/radius-auth.xml | 169 ++++++++++++++++++++++++++++++++++++++
 src/gug.xml                  |   1 +
 2 files changed, 170 insertions(+)
diff --git a/src/chapters/radius-auth.xml b/src/chapters/radius-auth.xml
new file mode 100644
index 0000000..23eb882
--- /dev/null
+++ b/src/chapters/radius-auth.xml
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xml:id="radius-auth" xmlns=""; 
version="5.0" xml:lang="en"
+    xmlns:xi=""; 
+    <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>The RADIUS authentication extension is available separately from 
the main
+                <filename>guacamole.war</filename>. The link for this and all 
+            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="";
+                ></link>.</para>
+        <para>The RADIUS authentication extension is packaged as a 
+            file containing only the extension itself,
<filename>guacamole-auth-radius-0.9.11-incubating.jar</filename>, which must
+            ultimately be placed in 
+    </section>
+    <section xml:id="installing-radius-auth">
+        <title>Installing RADIUS authentication</title>
+        <para>Guacamole extensions are self-contained 
<filename>.jar</filename> files which are
+            located within the <filename>GUACAMOLE_HOME/extensions</filename> 
+                <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 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.11-incubating.jar</filename> into
+                        <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+            </step>
+            <step>
+                <para>Configure Guacamole to use RADIUS authentication, as 
+                    below.</para>
+            </step>
+        </procedure>
+        <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 
+                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 
+                file.</para>
+            <variablelist>
+                <varlistentry>
+                    <term><property>radius-server</property></term>
+                    <listitem>
+                        <para>The RADIUS server to authenticate against.  If 
not specified, 
+                            localhost will be used.</para>
+                    </listitem>
+                    <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>
+                    <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 
+                    </listitem>
+                    <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>
+                    <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>
+                    <term><property>radius-key-type</property></term>
+                    <listitem>
+                        <para>The type of the key file specified by the 
+                        parameter.  If not specified, this defaults to pkcs12, 
the default used by 
+                        the JRadius library.</para>
+                    </listitem>
+                    <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>
+                    <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 
+                    </listitem>
+                    <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>
+                    <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>
+                    <term><property>radius-trust-all</property></term>
+                    <listitem>
+                        <para>Trust all server certificates without verifying 
against a CA file.
+                        </para>
+                    </listitem>
+                    <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>
+                    <term><property>radius-timeout</property></term>
+                    <listitem>
+                        <para>The timeout for a RADIUS connection in seconds.  
The default is
+                        60 seconds.</para>
+                    </listitem>
+                    <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>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </section>
+        <section xml:id="completing-radius-install">
+            <title>Completing the installation</title>
+            <para>Guacamole will only reread 
<filename></filename> and load
+                newly-installed extensions during startup, so your servlet 
container will need to be
+                restarted before HTTP header 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>
diff --git a/src/gug.xml b/src/gug.xml
index a953f40..fc39401 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -164,6 +164,7 @@
         <xi:include href="chapters/header-auth.xml"/>
         <xi:include href="chapters/cas-auth.xml"/>
         <xi:include href="chapters/openid-auth.xml"/>
+        <xi:include href="chapters/radius-auth.xml"/>
         <xi:include href="chapters/using.xml"/>
         <xi:include href="chapters/administration.xml"/>
         <xi:include href="chapters/troubleshooting.xml"/>

Reply via email to