GUACAMOLE-197: Initial commit for chapter for configuring RADIUS authentication in Guacamole.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/387ceb27 Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/387ceb27 Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/387ceb27 Branch: refs/heads/master Commit: 387ceb2753e34490b20a20eca2d43cafb1b71508 Parents: db9a8ad Author: Nick Couchman <nick_couch...@cotyinc.com> Authored: Mon Feb 13 12:19:01 2017 -0500 Committer: Nick Couchman <vn...@apache.org> Committed: Wed Jan 31 08:44:44 2018 -0500 ---------------------------------------------------------------------- src/chapters/radius-auth.xml | 169 ++++++++++++++++++++++++++++++++++++++ src/gug.xml | 1 + 2 files changed, 170 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/387ceb27/src/chapters/radius-auth.xml ---------------------------------------------------------------------- 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="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 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.incubator.apache.org/releases/"; + >http://guacamole.incubator.apache.org/releases/</link>.</para> + <para>The RADIUS authentication extension is packaged as a <filename>.tar.gz</filename> + file containing only the extension itself, + <filename>guacamole-auth-radius-0.9.11-incubating.jar</filename>, which must + ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para> + </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> 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 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 described + 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 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-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 specified.</para> + </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 <property>radius-key-file</property> + 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 directory.</para> + </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> + <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> + </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> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/387ceb27/src/gug.xml ---------------------------------------------------------------------- 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"/>
