Repository: guacamole-manual Updated Branches: refs/heads/staging/0.9.14 3fa092465 -> e5ffef2d0
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/staging/0.9.14 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"/>
