Merge 1.2.0 changes back to master.
diff --git a/src/chapters/saml-auth.xml b/src/chapters/saml-auth.xml
new file mode 100644
index 0000000..1fa89d3
--- /dev/null
+++ b/src/chapters/saml-auth.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="saml-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>SAML Authentication</title>
+ <indexterm>
+ <primary>SAML Authentication</primary>
+ </indexterm>
+ <para>SAML is a widely implemented and used Single Sign On (SSO) provider that allows
+ applications and services to authenticate in a standard way, and brokers those
+ authentication requests to one or more back-end authentication providers. The SAML
+ authentication extension allows Guacamole to redirect to a SAML Identity Provider (IdP)
+ for authentication and user services. This module does not provide any capability
+ for storing or retrieving connections, and must be layered with other authentication
+ extensions that provide connection management.</para>
+ <section xml:id="saml-downloading">
+ <title>Downloading the SAML authentication extension</title>
+ <para>The SAML 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.apache.org/releases/"
+ >http://guacamole.apache.org/releases/</link>.</para>
+ <para>The SAML authentication extension is packaged as a <filename>.tar.gz</filename>
+ file containing only the extension itself,
+ <filename>guacamole-auth-saml-1.2.0.jar</filename>, which must
+ ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </section>
+ <section xml:id="installing-saml-auth">
+ <title>Installing SAML 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 SAML 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-saml-1.2.0.jar</filename> within
+ <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </step>
+ <step>
+ <para>Configure Guacamole to use SAML authentication, as described
+ below.</para>
+ </step>
+ </procedure>
+ <section xml:id="guac-saml-config">
+ <title>Configuring Guacamole for SAML Authentication</title>
+ <indexterm>
+ <primary>configuring SAML authentication</primary>
+ </indexterm>
+ <indexterm>
+ <primary>SAML authentication</primary>
+ <secondary>configuration</secondary>
+ </indexterm>
+ <para>The SAML authentication extension provides several configuration properties
+ to set it up to talk to the IdP. The SAML IdP also must be configured with
+ Guacamole as a Service Provider (SP). Configuration of the SAML IdP is beyond
+ the scope of this document, and will vary widely based on the IdP in use.</para>
+ <variablelist>
+ <varlistentry>
+ <term><property>saml-idp-metadata-url</property></term>
+ <listitem>
+ <para>The URI of the XML metadata file that from the
+ SAML Identity Provider that contains all of the
+ information the SAML extension needs in order to
+ know how to authenticate with the IdP. This URI can
+ either be a remote server (e.g. https://) or a local
+ file on the filesystem (e.g. file://). Often the
+ metadata file contains most of the required
+ properties for SAML authentication and the other
+ parameters are not required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-idp-url</property></term>
+ <listitem>
+ <para>The base URL of the SAML IdP. This is the URL that
+ the SAML authentication extension will use to redirect
+ when requesting SAML authentication. If the
+ <property>saml-idp-metadata</property> property is
+ provided, this parameter will be ignored. If the metadata
+ file is not provided this property is required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-entity-id</property></term>
+ <listitem>
+ <para>The entity ID of the Guacamole SAML client, which is
+ generally the URL of the Guacamole server, but is not
+ required to be so. This property is required if
+ either the <property>saml-idp-metadata-url</property>
+ property is not specified, or if the provided
+ metadata file does not contain the SAML SP Entity
+ ID for Guacamole Client.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-callback-url</property></term>
+ <listitem>
+ <para>The URL that the IdP will use once authentication has
+ succeeded to return to the Guacamole web application and
+ provide the authentication details to the SAML extension.
+ The SAML extension currently only supports callback as a
+ POST operation to this callback URL. This property
+ is required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-strict</property></term>
+ <listitem>
+ <para>Require strict security checks during SAML logins.
+ This will insure that valid certificates are
+ present for all interactions with SAML servers and
+ fail SAML authentication if security restrictions
+ are violated. This property is optional, and will
+ default to true, requiring strict security checks.
+ This property should only be set to false in
+ non-production environments during testing of
+ SAML authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-debug</property></term>
+ <listitem>
+ <para>Enable additional logging within the supporting
+ SAML library that can assist in tracking down issues
+ during SAML logins. This property is optional, and
+ will default to false (no debugging).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-compress-request</property></term>
+ <listitem>
+ <para>Enable compression of the HTTP requests sent to
+ the SAML IdP. This property is optional and will
+ default to true (compression enabled).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-compress-response</property></term>
+ <listitem>
+ <para>Request that the SAML response returned by the
+ IdP be compressed. This property is optional and
+ will default to true (compression will be requested).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-group-attribute</property></term>
+ <listitem>
+ <para>The name of the attribute provided by the SAML IdP
+ that contains group membership of the user. These
+ groups will be parsed and used to map group
+ membership of the user logging in, which can be used
+ for permissions management within Guacamole Client,
+ particularly when layered with other authentication
+ modules. This property is optional, and defaults to
+ "groups".</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section xml:id="completing-saml-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 SAML 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>
diff --git a/src/gug.xml b/src/gug.xml
index b6dad07..f09ba87 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -165,6 +165,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/saml-auth.xml"/>
<xi:include href="chapters/radius-auth.xml"/>
<xi:include href="chapters/adhoc-connections.xml"/>
<xi:include href="chapters/using.xml"/>
