OpenID Connect Auth

Instructions for authenticating users with OpenID Connect

This documentation assumes that you already have access to an OpenID Connect identity provider, such as Google, Okta, Azure, etc. If you do not already have Guacamole installed, please see the installation instructions.

Installing OpenID Connect support for Guacamole

Keeper Connection Manager packages Guacamole’s OpenId Connect support within the kcm-guacamole-auth-sso-openid package:

$ sudo yum install kcm-guacamole-auth-sso-openid

Connecting Guacamole to OpenID Connect

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the OpenID Connect installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “OPENID-1” and defines the IdP configuration. Uncomment the properties in this section and edit them according to your identity provider setup.

##
## [OPENID-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP. THIS INFORMATION IS REQUIRED if the OpenID
## extension will be used.
##
## If your IdP implements "OpenID Connect Discovery", these values can be
## found within the JSON file hosted at:
##
##   https://identity-provider/.well-known/openid-configuration
##
## where "https://identity-provider" is the base URL of the IdP.
##

#openid-authorization-endpoint: https://myprovider.example.net/sso/openid/auth
#openid-jwks-endpoint: https://myprovider.example.net/sso/openid/certs
#openid-issuer: https://myprovider.example.net

The second section contains the Keeper Connection Manager server information that is used by the IdP.

##
## [OPENID-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the OpenID
## Connect IdP when authenticating the user. This information defines how the
## OpenID Connect IdP should send identity assertions back to the Guacamole
## server if their identity is confirmed. THESE PROPERTIES ARE REQUIRED if
## the OpenID extension will be used.
##

#openid-client-id: abcd1234-xyz.apps.myprovider.example.net
#openid-redirect-uri: https://myserver.example.net

The 3rd section contains the OpenID Connect identity mappings.

##
## [OPENID-3] Identity mapping
##
## How identity assertions received form the OpenID Connect IdP should be
## mapped back to user and group identities. Mapping users and groups is
## flexible within OpenID, with the definition of user/group identity left
## to the application to determine from the various assertions ("claims")
## returned by the OpenID IdP in response to successful authentication.
##
## By default, Guacamole will use the "email" claim as the username and the
## content of the "groups" claim (if present) as the set of associated user
## groups. OpenID IdP implementations may support additional claims that may
## be more appropriate for your use case. If using different claims from the
## defaults, the "openid-scope" property must be adjusted so that Guacamole
## knows to request those claims from the IdP.
##

#openid-scope: openid email profile
#openid-username-claim-type: email
#openid-groups-claim-type: groups

The 4th section contains optional parameters that can be set.

##
## [OPENID-4] Clock skew and timeouts
##
## By default, clock skew between the Guacamole server and the OpenID IdP of up
## to 30 seconds is tolerated, tokens generated by the OpenID IdP are valid for
## no longer than 5 hours, and the "nonce" generated for each OpenID request by
## Guacamole will remain valid for no longer than 10 minutes.
##
## If necessary, these values can be overridden. Clock skew is specified in
## seconds, and token/nonce validity is specified in minutes.
##

#openid-allowed-clock-skew: 30
#openid-max-token-validity: 300
#openid-max-nonce-validity: 10
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole