| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 12. OpenID Connect Authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="cas-auth.html" title="Chapter 11. CAS Authentication" /><link rel="next" href="radius-auth.html" title="Chapter 13. RADIUS Authentication" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. OpenID Connect Authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cas-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="radius-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="openid-auth"></a>Chapter 12. OpenID Connect Authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="openid-auth.html#openid-downloading">Downloading the OpenID Connect authentication extension</a></span></dt><dt><span class="section"><a href="openid-auth.html#installing-openid-auth">Installing support for OpenID Connect</a></span></dt><dd><dl><dt><span class="section"><a href="openid-auth.html#guac-openid-config">Configuring Guacamole for single sign-on with OpenID Connect</a></span></dt><dt><span class="section"><a href="openid-auth.html#completing-openid-install">Completing the installation</a></span></dt></dl></dd></dl></div><a id="idm46420848363456" class="indexterm"></a><p><a class="link" href="http://openid.net/connect/" target="_top">OpenID Connect</a> is a widely-adopted |
| open standard for implementing single sign-on (SSO). <a class="link" href="https://oauth.net/articles/authentication/" target="_top">Not to be confused with |
| OAuth</a>, which is <span class="emphasis"><em>not</em></span> an authentication protocol, OpenID |
| Connect defines an authentication protocol in the form of a simple identity layer on top of |
| OAuth 2.0.</p><p>Guacamole's OpenID Connect support implements the "<a class="link" href="https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth" target="_top">implicit flow</a>" 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 |
| <a class="link" href="jdbc-auth.html" title="Chapter 6. Database authentication">database authentication extension</a>, as it only provides |
| user authentication.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="openid-downloading"></a>Downloading the OpenID Connect authentication extension</h2></div></div></div><p>The OpenID Connect authentication extension is available separately from the main |
| <code class="filename">guacamole.war</code>. 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: <a class="link" href="http://guacamole.apache.org/releases/" target="_top">http://guacamole.apache.org/releases/</a>.</p><p>The OpenID Connect authentication extension is packaged as a |
| <code class="filename">.tar.gz</code> file containing only the extension itself, |
| <code class="filename">guacamole-auth-openid-1.1.0.jar</code>, which must ultimately be |
| placed in <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-openid-auth"></a>Installing support for OpenID Connect</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are |
| located within the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. |
| <span class="emphasis"><em>If you are unsure where <code class="varname">GUACAMOLE_HOME</code> is located on |
| your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before |
| proceeding.</em></span></p><p>To install the OpenID Connect authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it |
| does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-openid-1.1.0.jar</code> within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use OpenID Connect authentication, as described |
| below.</p></li></ol></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guac-openid-config"></a>Configuring Guacamole for single sign-on with OpenID Connect</h3></div></div></div><a id="idm46420848220640" class="indexterm"></a><a id="idm46420848219712" class="indexterm"></a><p>Guacamole's OpenID connect support requires several properties which describe both |
| the identity provider and the Guacamole deployment. These properties are |
| <span class="emphasis"><em>absolutely required in all cases</em></span>, 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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">openid-authorization-endpoint</span></span></dt><dd><p>The authorization endpoint (URI) of the OpenID service.</p><p>This value should be provided to you by the identity provider. For |
| identity providers that implement <a class="link" href="https://openid.net/specs/openid-connect-discovery-1_0.html" target="_top">OpenID Connect Discovery</a>, this value can be retrieved from |
| the "<span class="property">authorization_endpoint</span>" property of the JSON |
| file hosted at |
| <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em>/.well-known/openid-configuration</code>, |
| where <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em></code> is |
| the base URL of the identity provider.</p></dd><dt><span class="term"><span class="property">openid-jwks-endpoint</span></span></dt><dd><p>The endpoint (URI) of the JWKS service which defines how received ID |
| tokens (<a class="link" href="https://jwt.io/" target="_top">JSON Web Tokens</a> or |
| JWTs) shall be validated.</p><p>This value should be provided to you by the identity provider. For |
| identity providers that implement <a class="link" href="https://openid.net/specs/openid-connect-discovery-1_0.html" target="_top">OpenID Connect Discovery</a>, this value can be retrieved from |
| the "<span class="property">jwks_uri</span>" property of the JSON file hosted at |
| <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em>/.well-known/openid-configuration</code>, |
| where <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em></code> is |
| the base URL of the identity provider.</p></dd><dt><span class="term"><span class="property">openid-issuer</span></span></dt><dd><p>The issuer to expect for all received ID tokens.</p><p>This value should be provided to you by the identity provider. For |
| identity providers that implement <a class="link" href="https://openid.net/specs/openid-connect-discovery-1_0.html" target="_top">OpenID Connect Discovery</a>, this value can be retrieved from |
| the "<span class="property">issuer</span>" property of the JSON file hosted at |
| <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em>/.well-known/openid-configuration</code>, |
| where <code class="uri"><em class="replaceable"><code>https://identity-provider</code></em></code> is |
| the base URL of the identity provider.</p></dd><dt><span class="term"><span class="property">openid-client-id</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">openid-redirect-uri</span></span></dt><dd><p>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.</p></dd></dl></div><p>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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">openid-username-claim-type</span></span></dt><dd><p>The claim type which contains the authenticated user's username within |
| any valid JWT. By default, the "<code class="constant">email</code>" is |
| used.</p></dd><dt><span class="term"><span class="property">openid-scope</span></span></dt><dd><p>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 "<code class="constant">openid profile</code>" |
| must be requested. By default, "<code class="constant">openid email |
| profile</code>" is used.</p></dd><dt><span class="term"><span class="property">openid-allowed-clock-skew</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">openid-max-token-validity</span></span></dt><dd><p>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).</p></dd><dt><span class="term"><span class="property">openid-max-nonce-validity</span></span></dt><dd><p>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.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="completing-openid-install"></a>Completing the installation</h3></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> and load |
| newly-installed extensions during startup, so your servlet container will need to be |
| restarted before OpenID Connect authentication can be used. <span class="emphasis"><em>Doing this |
| will disconnect all active users, so be sure that it is safe to do so prior to |
| attempting installation.</em></span> When ready, restart your servlet container |
| and give the new authentication a try.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cas-auth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="radius-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. CAS Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 13. RADIUS Authentication</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
