Table of Contents
OpenID Connect is a widely-adopted open standard for implementing single sign-on (SSO). Not to be confused with OAuth, which is not an authentication protocol, OpenID Connect defines an authentication protocol in the form of a simple identity layer on top of OAuth 2.0.
Guacamole's OpenID Connect support implements the "implicit flow" 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 database authentication extension, as it only provides user authentication.
The OpenID Connect authentication extension is available separately from the main
guacamole.war. 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: http://guacamole.apache.org/releases/.
The OpenID Connect authentication extension is packaged as a
.tar.gz file containing only the extension itself,
guacamole-auth-openid-1.0.0.jar, which must ultimately be
placed in GUACAMOLE_HOME/extensions.
Guacamole extensions are self-contained .jar files which are
located within the GUACAMOLE_HOME/extensions directory.
If you are unsure where GUACAMOLE_HOME is located on
your system, please consult Chapter 5, Configuring Guacamole before
proceeding.
To install the OpenID Connect authentication extension, you must:
Create the
GUACAMOLE_HOME/extensionsdirectory, if it does not already exist.Copy
guacamole-auth-openid-1.0.0.jarwithinGUACAMOLE_HOME/extensions.Configure Guacamole to use OpenID Connect authentication, as described below.
Guacamole's OpenID connect support requires several properties which describe both the identity provider and the Guacamole deployment. These properties are absolutely required in all cases, 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:
- openid-authorization-endpoint
The authorization endpoint (URI) of the OpenID service.
This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "authorization_endpoint" property of the JSON file hosted at
https://identity-provider/.well-known/openid-configurationhttps://identity-provider- openid-jwks-endpoint
The endpoint (URI) of the JWKS service which defines how received ID tokens (JSON Web Tokens or JWTs) shall be validated.
This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "jwks_uri" property of the JSON file hosted at
https://identity-provider/.well-known/openid-configurationhttps://identity-provider- openid-issuer
The issuer to expect for all received ID tokens.
This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "issuer" property of the JSON file hosted at
https://identity-provider/.well-known/openid-configurationhttps://identity-provider- openid-client-id
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.
- openid-redirect-uri
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.
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:
- openid-username-claim-type
The claim type which contains the authenticated user's username within any valid JWT. By default, the "
email" is used.- openid-scope
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 "
openid profile" must be requested. By default, "openid email profile" is used.- openid-allowed-clock-skew
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.
- openid-max-token-validity
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).
- openid-max-nonce-validity
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.
Guacamole will only reread guacamole.properties and load
newly-installed extensions during startup, so your servlet container will need to be
restarted before OpenID Connect authentication can be used. Doing this
will disconnect all active users, so be sure that it is safe to do so prior to
attempting installation. When ready, restart your servlet container
and give the new authentication a try.