src/chapters/saml-auth.xml

<?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.3.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.3.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>