Repository: guacamole-manual
Updated Branches:
  refs/heads/master 9b84bbb06 -> c36251e6e


GUACAMOLE-210: Document usage of OpenID Connect authentication extension.


Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/cfe8863d
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/cfe8863d
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/cfe8863d

Branch: refs/heads/master
Commit: cfe8863d92ef932a934a128d3529ce9edd96a96f
Parents: 3fa0924
Author: Michael Jumper <mjum...@apache.org>
Authored: Sun Jan 7 16:11:17 2018 -0800
Committer: Michael Jumper <mjum...@apache.org>
Committed: Sun Jan 7 16:13:18 2018 -0800

----------------------------------------------------------------------
 src/chapters/openid-auth.xml | 203 ++++++++++++++++++++++++++++++++++++++
 src/gug.xml                  |   1 +
 2 files changed, 204 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/cfe8863d/src/chapters/openid-auth.xml
----------------------------------------------------------------------
diff --git a/src/chapters/openid-auth.xml b/src/chapters/openid-auth.xml
new file mode 100644
index 0000000..7d9365a
--- /dev/null
+++ b/src/chapters/openid-auth.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="openid-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>OpenID Connect Authentication</title>
+    <indexterm>
+        <primary>OpenID Connect Authentication</primary>
+    </indexterm>
+    <para><link xlink:href="http://openid.net/connect/";>OpenID Connect</link> 
is a widely-adopted
+        open standard for implementing single sign-on (SSO). <link
+            xlink:href="https://oauth.net/articles/authentication/";>Not to be 
confused with
+            OAuth</link>, which is <emphasis>not</emphasis> an authentication 
protocol, OpenID
+        Connect defines an authentication protocol in the form of a simple 
identity layer on top of
+        OAuth 2.0.</para>
+    <para>Guacamole's OpenID Connect support implements the "<link
+            
xlink:href="https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth";
+            >implicit flow</link>" of the OpenID Connect standard, and allows 
authentication of
+        Guacamole users to be delegated to an identity provider which 
implements OpenID Connect,
+        removing the need for users to log into Guacamole directly. This 
module must be layered on
+        top of other authentication extensions that provide connection 
information, such as the
+            <link linkend="jdbc-auth">database authentication 
extension</link>, as it only provides
+        user authentication.</para>
+    <section xml:id="openid-downloading">
+        <title>Downloading the OpenID Connect authentication extension</title>
+        <para>The OpenID Connect 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 OpenID Connect authentication extension is packaged as a
+                <filename>.tar.gz</filename> file containing only the 
extension itself,
+                <filename>guacamole-auth-openid-0.9.14.jar</filename>, which 
must ultimately be
+            placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+    </section>
+    <section xml:id="installing-openid-auth">
+        <title>Installing support for OpenID Connect</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 OpenID Connect 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-openid-0.9.14.jar</filename> within
+                        <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+            </step>
+            <step>
+                <para>Configure Guacamole to use OpenID Connect 
authentication, as described
+                    below.</para>
+            </step>
+        </procedure>
+        <section xml:id="guac-openid-config">
+            <title>Configuring Guacamole for single sign-on with OpenID 
Connect</title>
+            <indexterm>
+                <primary>configuring OpenID Connect authentication</primary>
+            </indexterm>
+            <indexterm>
+                <primary>OpenID Connect authentication</primary>
+                <secondary>configuration</secondary>
+            </indexterm>
+            <para>Guacamole's OpenID connect support requires several 
properties which describe both
+                the identity provider and the Guacamole deployment. These 
properties are
+                    <emphasis>absolutely required in all cases</emphasis>, as 
they dictate how
+                Guacamole should connect to the identity provider, how it 
should verify the identity
+                provider's response, and how the identity provider should 
redirect users back to
+                Guacamole once their identity has been confirmed:</para>
+            <variablelist>
+                <varlistentry>
+                    
<term><property>openid-authorization-endpoint</property></term>
+                    <listitem>
+                        <para>The authorization endpoint (URI) of the OpenID 
service.</para>
+                        <para>This value should be provided to you by the 
identity provider. For
+                            identity providers that implement <link
+                                
xlink:href="https://openid.net/specs/openid-connect-discovery-1_0.html";
+                                >OpenID Connect Discovery</link>, this value 
can be retrieved from
+                            the "<property>authorization_endpoint</property>" 
property of the JSON
+                            file hosted at
+                                
<uri><replaceable>https://identity-provider</replaceable>/.well-known/openid-configuration</uri>,
+                            where 
<uri><replaceable>https://identity-provider</replaceable></uri> is
+                            the base URL of the identity provider.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-jwks-endpoint</property></term>
+                    <listitem>
+                        <para>The endpoint (URI) of the JWKS service which 
defines how received ID
+                            tokens (<link xlink:href="https://jwt.io/";>JSON 
Web Tokens</link> or
+                            JWTs) shall be validated.</para>
+                        <para>This value should be provided to you by the 
identity provider. For
+                            identity providers that implement <link
+                                
xlink:href="https://openid.net/specs/openid-connect-discovery-1_0.html";
+                                >OpenID Connect Discovery</link>, this value 
can be retrieved from
+                            the "<property>jwks_uri</property>" property of 
the JSON file hosted at
+                                    
<uri><replaceable>https://identity-provider</replaceable>/.well-known/openid-configuration</uri>,
+                            where 
<uri><replaceable>https://identity-provider</replaceable></uri> is
+                            the base URL of the identity provider.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-issuer</property></term>
+                    <listitem>
+                        <para>The issuer to expect for all received ID 
tokens.</para>
+                        <para>This value should be provided to you by the 
identity provider. For
+                            identity providers that implement <link
+                                
xlink:href="https://openid.net/specs/openid-connect-discovery-1_0.html";
+                                >OpenID Connect Discovery</link>, this value 
can be retrieved from
+                            the "<property>issuer</property>" property of the 
JSON file hosted at
+                                    
<uri><replaceable>https://identity-provider</replaceable>/.well-known/openid-configuration</uri>,
+                            where 
<uri><replaceable>https://identity-provider</replaceable></uri> is
+                            the base URL of the identity provider.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-client-id</property></term>
+                    <listitem>
+                        <para>The OpenID client ID which should be submitted 
to the OpenID service
+                            when necessary. This value is typically provided 
to you by the OpenID
+                            service when OpenID credentials are generated for 
your
+                            application.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-redirect-uri</property></term>
+                    <listitem>
+                        <para>The URI that should be submitted to the OpenID 
service such that they
+                            can redirect the authenticated user back to 
Guacamole after the
+                            authentication process is complete. This must be 
the full URL that a
+                            user would enter into their browser to access 
Guacamole.</para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+            <para>Additional optional properties are available to control how 
claims within received
+                ID tokens are used to derive the user's Guacamole username, 
the OpenID scopes
+                requested when user identities are confirmed, and to control 
the maximum amount of
+                time allowed for various aspects of the conversation with the 
identity
+                provider:</para>
+            <variablelist>
+                <varlistentry>
+                    
<term><property>openid-username-claim-type</property></term>
+                    <listitem>
+                        <para>The claim type which contains the authenticated 
user's username within
+                            any valid JWT. By default, the 
"<constant>email</constant>" is
+                            used.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-scope</property></term>
+                    <listitem>
+                        <para>The space-separated list of OpenID scopes to 
request.  OpenID scopes
+                            determine the information returned within the 
OpenID token, and thus
+                            affect what values can be used as an authenticated 
user's username. To
+                            be compliant with OpenID, at least 
"<constant>openid profile</constant>"
+                            must be requested. By default, "<constant>openid 
email
+                                profile</constant>" is used.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-allowed-clock-skew</property></term>
+                    <listitem>
+                        <para>The amount of clock skew tolerated for timestamp 
comparisons between
+                            the Guacamole server and OpenID service clocks, in 
seconds. By default,
+                            clock skew of up to 30 seconds is tolerated.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-max-token-validity</property></term>
+                    <listitem>
+                        <para>The maximum amount of time that an OpenID token 
should remain valid,
+                            in minutes. By default, each OpenID token remains 
valid for 300 minutes
+                            (5 hours).</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>openid-max-nonce-validity</property></term>
+                    <listitem>
+                        <para>The maximum amount of time that a nonce 
generated by the Guacamole
+                            server should remain valid, in minutes. As each 
OpenID request has a
+                            unique nonce value, this imposes an upper limit on 
the amount of time
+                            any particular OpenID request can result in 
successful authentication
+                            within Guacamole. By default, each generated nonce 
expires after 10
+                            minutes.</para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </section>
+        <section xml:id="completing-openid-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 OpenID Connect 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/cfe8863d/src/gug.xml
----------------------------------------------------------------------
diff --git a/src/gug.xml b/src/gug.xml
index 56e9123..a953f40 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -163,6 +163,7 @@
         <xi:include href="chapters/duo-auth.xml"/>
         <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/using.xml"/>
         <xi:include href="chapters/administration.xml"/>
         <xi:include href="chapters/troubleshooting.xml"/>

Reply via email to