| <?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>The RADIUS extension depends on software that is covered by a LGPL license, which is |
| incompatible with the Apache 2.0 license under which Guacamole is licensed. Due to this |
| dependency, the Guacamole project cannot distribute binary versions of the RADIUS extension. |
| If you want to use this extension you will need to build the code - or at least the RADIUS |
| extension yourself. Build instructions can be found in the section |
| <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-1.0.0.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-1.0.0.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-1.0.0.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 the extension will not load if this is 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. This parameter |
| should specify the absolute path to the file. By default the extension |
| will look for a file called radius.key in the GUACAMOLE_HOME directory. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-key-type</property></term> |
| <listitem> |
| <para>The file type of the keystore specified by the <property>radius-key-file</property> |
| parameter. Valid keystore types are pem, jceks, jks, and pkcs12. |
| 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. By default the extension |
| will not use any password when trying to open the key file.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-ca-file</property></term> |
| <listitem> |
| <para>The absolute path to the file that stores the certificate authority |
| certificates for encrypted connections to the RADIUS server. By default |
| a file with the name ca.crt in the GUACAMOLE_HOME directory will be used. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-ca-type</property></term> |
| <listitem> |
| <para>The file type of keystore used for the certificate authority. Valid formats are |
| pem, jceks, jks, and pkcs12. If not specified this defaults to pem.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-ca-password</property></term> |
| <listitem> |
| <para>The password used to protect the certificate authority store, if |
| any. If unspecified the extension will attempt to read the CA |
| store without any password.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-trust-all</property></term> |
| <listitem> |
| <para>This parameter controls whether or not the RADIUS extension |
| should trust all certificates or verify them against known good |
| certificate authorities. Set to true to allow the RADIUS server |
| to connect without validating certificates. The default is false, |
| which causes certificates to be validated.</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. By default |
| the client will try the connection at most 5 times.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>radius-timeout</property></term> |
| <listitem> |
| <para>The timeout for a RADIUS connection in seconds. By default the client |
| will wait for a response from the server for at most 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. |
| If the <property>radius-auth-protocol</property> value is set to something |
| other than eap-ttls, this parameter has no effect and will be ignored. Valid |
| options for this are any of the values for |
| <property>radius-auth-protocol</property>, except for eap-ttls.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </section> |
| <section xml:id="completing-radius-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 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> |
| </chapter> |
