Chapter 12. OpenID Connect Authentication

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.

Downloading the OpenID Connect authentication extension

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.1.0.jar, which must ultimately be placed in GUACAMOLE_HOME/extensions.

Installing support for OpenID Connect

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:

  1. Create the GUACAMOLE_HOME/extensions directory, if it does not already exist.

  2. Copy guacamole-auth-openid-1.1.0.jar within GUACAMOLE_HOME/extensions.

  3. Configure Guacamole to use OpenID Connect authentication, as described below.

Configuring Guacamole for single sign-on with OpenID Connect

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-configuration, where https://identity-provider is the base URL of the 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-configuration, where https://identity-provider is the base URL of the 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-configuration, where https://identity-provider is the base URL of the 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.

Completing the installation

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.