<?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="saml-auth.html" title="Chapter 13. SAML 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="saml-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="idm46227497717184" 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.3.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.3.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="idm46227495609696" class="indexterm"></a><a id="idm46227495608768" 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, any associated groups,
                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 within any valid JWT that contains the authenticated
                            user's username. By default, the "<code class="constant">email</code>" claim type
                            is used.</p></dd><dt><span class="term"><span class="property">openid-groups-claim-type</span></span></dt><dd><p>The claim type within any valid JWT that contains the list of groups
                            of which the authenticated user is a member. By default, the
                                "<code class="constant">groups</code>" claim type 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="saml-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. SAML Authentication</td></tr></table></div>

            </div></div>
        <!-- Google Analytics -->
        <script type="text/javascript">
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          ga('create', 'UA-75289145-1', 'auto');
          ga('send', 'pageview');
        </script>
        </body></html>