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

Guacamole’s SSO extensions are 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 SSO extensions are packaged together in a .tar.gz file containing one extension for each supported SSO method:

SSO Method	Extension
CAS	`cas/guacamole-auth-sso-cas-1.5.0.jar`
OpenID Connect	`openid/guacamole-auth-sso-openid-1.5.0.jar`
SAML	`saml/guacamole-auth-sso-saml-1.5.0.jar`

The extension for the desired SSO method, in this case guacamole-auth-sso-openid-1.5.0.jar from within the openid/ subdirectory, 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 Configuring Guacamole before proceeding.

To install the OpenID Connect authentication extension, you must:

Create the GUACAMOLE_HOME/extensions directory, if it does not already exist.
Copy guacamole-auth-sso-openid-1.5.0.jar within GUACAMOLE_HOME/extensions.
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, 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:

openid-username-claim-type: The claim type within any valid JWT that contains the authenticated user’s username. By default, the “email” claim type is used.
openid-groups-claim-type: The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type 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.

Controlling login behavior

Guacamole loads authentication extensions in order of priority, and evaluates authentication attempts in this same order. This has implications for how the Guacamole login process behaves when an SSO extension is present:

If the SSO extension has priority:: Users that are not yet authenticated will be immediately redirected to the configured identity provider. They will not see a Guacamole login screen.
If a non-SSO extension has priority:: Users that are not yet authenticated will be presented with a Guacamole login screen. Additionally, links to the configured identity provider(s) will be available for users that wish to log in using SSO.

The default priority of extensions is dictated by their filenames, with extensions that sort earlier alphabetically having higher priority than others. This can be overridden by setting the extension-priority property within guacamole.properties.

Automatically redirecting all unauthenticated users

To ensure users are redirected to the OpenID identity provider immediately (without a Guacamole login screen), ensure the OpenID extension has priority over all others:

extension-priority: openid

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.