| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 13. RADIUS Authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="openid-auth.html" title="Chapter 12. OpenID Connect Authentication" /><link rel="next" href="adhoc-connections.html" title="Chapter 14. Ad-hoc Connections" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. RADIUS Authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="openid-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="adhoc-connections.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="radius-auth"></a>Chapter 13. RADIUS Authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="radius-auth.html#radius-downloading">Downloading the RADIUS authentication extension</a></span></dt><dt><span class="section"><a href="radius-auth.html#installing-radius-auth">Installing RADIUS authentication</a></span></dt><dt><span class="section"><a href="radius-auth.html#guac-radius-config">Configuring Guacamole for RADIUS authentication</a></span></dt><dt><span class="section"><a href="radius-auth.html#completing-radius-install">Completing the installation</a></span></dt></dl></div><a id="idm46248439943488" class="indexterm"></a><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="radius-downloading"></a>Downloading the RADIUS authentication extension</h2></div></div></div><p>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 |
| <a class="xref" href="installing-guacamole.html" title="Chapter 2. Installing Guacamole natively">Chapter 2, <em>Installing Guacamole natively</em></a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-radius-auth"></a>Installing RADIUS authentication</h2></div></div></div><p>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 <code class="option">-Plgpl-extensions</code> |
| to the Maven command line during the build, and should result in the output below:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>mvn clean package -Plgpl-extensions</code></strong> |
| <code class="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] ------------------------------------------------------------------------</code> |
| <code class="prompt">$</code></pre></div><p>After the build completes successfully, the extension will be in the |
| <code class="filename">extensions/guacamole-auth-radius/target/</code> directory, and will be |
| called guacamole-auth-radius-1.0.0.jar. This extension file can be copied to |
| the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. |
| <span class="emphasis"><em>If you are unsure where <code class="varname">GUACAMOLE_HOME</code> is located on |
| your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before |
| proceeding.</em></span></p><p>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.</p><p>To install the RADIUS authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it |
| does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-radius-1.0.0.jar</code> into |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use RADIUS authentication, as described |
| below.</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guac-radius-config"></a>Configuring Guacamole for RADIUS authentication</h2></div></div></div><a id="idm46248438908272" class="indexterm"></a><a id="idm46248438861168" class="indexterm"></a><p>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 |
| <a class="link" href="configuring-guacamole.html#initial-setup" title="guacamole.properties"><code class="filename">guacamole.properties</code></a> |
| file.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">radius-hostname</span></span></dt><dd><p>The RADIUS server to authenticate against. If not specified, |
| localhost will be used.</p></dd><dt><span class="term"><span class="property">radius-auth-port</span></span></dt><dd><p>The RADIUS authentication port on which the RADIUS service is |
| is listening. If not specified, the default of 1812 will be |
| used.</p></dd><dt><span class="term"><span class="property">radius-shared-secret</span></span></dt><dd><p>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. |
| </p></dd><dt><span class="term"><span class="property">radius-auth-protocol</span></span></dt><dd><p>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 |
| <span class="property">radius-eap-ttls-inner-protocol</span> parameter in order to |
| properly configure the protocol used inside the EAP TTLS tunnel.</p></dd><dt><span class="term"><span class="property">radius-key-file</span></span></dt><dd><p>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. |
| </p></dd><dt><span class="term"><span class="property">radius-key-type</span></span></dt><dd><p>The file type of the keystore specified by the <span class="property">radius-key-file</span> |
| parameter. Valid keystore types are pem, jceks, jks, and pkcs12. |
| If not specified, this defaults to pkcs12, the default used by |
| the JRadius library.</p></dd><dt><span class="term"><span class="property">radius-key-password</span></span></dt><dd><p>The password of the private key specified in the |
| <span class="property">radius-key-file</span> parameter. By default the extension |
| will not use any password when trying to open the key file.</p></dd><dt><span class="term"><span class="property">radius-ca-file</span></span></dt><dd><p>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. |
| </p></dd><dt><span class="term"><span class="property">radius-ca-type</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">radius-ca-password</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">radius-trust-all</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">radius-retries</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">radius-timeout</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">radius-eap-ttls-inner-protocol</span></span></dt><dd><p>When EAP-TTLS is used, this parameter specifies the inner (tunneled) |
| protocol to use talking to the RADIUS server. It is required when the |
| <span class="property">radius-auth-protocol</span> parameter is set to eap-ttls. |
| If the <span class="property">radius-auth-protocol</span> 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 |
| <span class="property">radius-auth-protocol</span>, except for eap-ttls.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="completing-radius-install"></a>Completing the installation</h2></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> and load |
| newly-installed extensions during startup, so your servlet container will need to be |
| restarted before HTTP header authentication can be used. <span class="emphasis"><em>Doing this will |
| disconnect all active users, so be sure that it is safe to do so prior to |
| attempting installation.</em></span> When ready, restart your servlet container |
| and give the new authentication a try.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openid-auth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adhoc-connections.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. OpenID Connect Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. Ad-hoc Connections</td></tr></table></div> |
| |
| </div></div> |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-75289145-1', 'auto'); |
| ga('send', 'pageview'); |
| </script> |
| </body></html> |
