12/6/2015

Chapter16.guacamoleext

Chapter16.guacamoleext
WhilenotstrictlypartoftheJavaAPIprovidedbytheGuacamoleproject,guacamoleextisanAPIexposed
bytheGuacamolewebapplicationwithinaseparateprojectsuchthatextensions,specificallyauthentication
providers,canbewrittentotweakGuacamoletofitwellinexistingdeployments.
ExtensionstoGuacamolecan:
1. Providealternativeauthenticationmethodsandsourcesofconnection/userdata.
2. ThemeorbrandGuacamolethroughadditionalCSSfilesandstaticresources.
3. ExtendGuacamole'sJavaScriptcodebyprovidingJavaScriptthatwillbeloadedautomatically.
4. Addadditionaldisplaylanguages,oralterthetranslationstringsofexistinglanguages.

Guacamoleextensionformat
GuacamoleextensionsarestandardJava.jarfileswhichcontainallclassesandresourcesrequiredbythe
extension,aswellastheGuacamoleextensionmanifest.Thereisnosetstructuretoanextensionexceptthat
themanifestmustbeintherootofthearchive.Javaclassesandpackages,ifany,willbereadfromthe.jar
relativetotheroot,aswell.
Beyond this, the semantics and locations associated with all other resources within the extension are
determinedbytheextensionmanifestalone.

Extensionmanifest
TheGuacamoleextensionmanifestisasingleJSONfile,guacmanifest.json,whichdescribesthelocation
ofeachresource,thetypeofeachresource,andtheversionofGuacamolethattheextensionwasbuiltfor.
Themanifestcancontainthefollowingproperties:
Property

Description

guacamoleVersion

The version string of the Guacamole release that this extension is written
for.This property is required for all extensions. The special version string
"*"canbeusediftheextensiondoesnotdependonaparticularversionof
Guacamole, but be careful this will bypass version compatibility checks,
andshouldneverbeusediftheextensiondoesmorethanbasicthemingor
branding.

name

Ahumanreadablenamefortheextension.Thispropertyisrequiredforall
extensions. When your extension is successfully loaded, a message
acknowledging the successful loading of your extension by name will be
logged.

namespace

Auniquestringwhichidentifiesyourextension.Thispropertyisrequiredfor
all extensions. This string should be unique enough that it is unlikely to
collidewiththenamespaceofanyotherextension.
Ifyourextensioncontainsstaticresources,thoseresourceswill be served
atapathderivedfromthenamespaceprovidedhere.

http://guacdev.org/doc/gug/guacamoleext.html

1/7

12/6/2015

authProviders

js

Chapter16.guacamoleext

An array of the classnames of all AuthenticationProvider subclasses

provided by this extension. Guacamole currently only supports one
AuthenticationProvider being loaded at a time, thus this array must
onlycontainoneelement,ifitispresentatall.

An array of all JavaScript files within the extension. All paths within this
array must be relative paths, and will be interpreted relative to the root of
thearchive.
JavaScript files declared here will be automatically loaded when the web
applicationloadswithintheuser'sbrowser.

css

An array of all CSS files within the extension. All paths within this array
must be relative paths, and will be interpreted relative to the root of the
archive.
CSS files declared here will be automatically applied when the web
applicationloadswithintheuser'sbrowser.

An array of all translation files within the extension. All paths within this
array must be relative paths, and will be interpreted relative to the root of
thearchive.
translations
Translationfilesdeclaredherewillbeautomaticallyaddedtothe available
languages.Ifatranslationfileprovidesalanguagethatalreadyexistswithin
Guacamole,itsstringswilloverridethestringsoftheexistingtranslation.

resources

An object where each property name is the name of a web resource file,
and each value is the mimetype for that resource. All paths within this
objectmustberelativepaths,andwillbeinterpretedrelativetotherootof
thearchive.
Web resources declared here will be made available to the applicationat
app/ext/ NAMESPACE / PATH , where NAMESPACE is the value of the
namespaceproperty,and PATH isthedeclaredwebresourcefilename.

TheonlyabsolutelyrequiredpropertiesareguacamoleVersion,name,andnamespace,astheyareusedto
identify the extension and for compatibility checks. The most minimal guacmanifest.json will look
somethinglikethis:
{
"guacamoleVersion":"0.9.7",
"name":"MyExtension",
"namespace":"myextension"
}
Thiswillallowtheextensiontoload,butdoesabsolutelynothingotherwise.Lackingthesemanticinformation
provided by the other properties, no other files within the extension will be used. A typical guac
manifest.jsonforanextensionprovidingthemingorbrandingwouldbemoreinvolved:
{
http://guacdev.org/doc/gug/guacamoleext.html

2/7

12/6/2015

Chapter16.guacamoleext

"guacamoleVersion":"0.9.7",
"name":"MyExtension",
"namespace":"myextension",
"css":["theme.css"],
"resources":{
"images/logo.png":"image/png",
"images/cancel.png":"image/png",
"images/delete.png":"image/png"
}
}

Accessingtheserverconfiguration
The configuration of the Guacamole server is exposed through the Environment interface, specifically the
LocalEnvironment implementation of this interface. Through Environment, you can access all properties
declared within guacamole.properties, determine the proper hostname/port of guacd, and access the
contentsofGUACAMOLE_HOME.

Customproperties
If your extension requires generic, unstructured configuration parameters, guacamole.properties is a
reasonable and simple location for them. The Environment interface provides direct access to
guacamole.propertiesandsimplemechanismsforreadingandparsingthepropertiestherein.Thevalueof
a property can be retrieved calling getProperty(), which will return null or a default value for undefined
properties,orgetRequiredProperty(),whichwillthrowanexceptionforundefinedproperties.
Forconvenience,guacamoleextcontainsseveralpredefinedpropertybaseclassesforcommontypes:
ClassName

ValueType

Interpretation

BooleanGuacamoleProperty

Boolean

Thevalues"true"and"false"areparsedas
their corresponding Boolean values. Any
othervalueresultsinaparseerror.

IntegerGuacamoleProperty

Integer

Numeric strings are parsed as Integer

values. Nonnumeric strings will result in a
parseerror.

LongGuacamoleProperty

Long

NumericstringsareparsedasLongvalues.
Nonnumeric strings will result in a parse
error.

String

The property value is returned as an

untouched String. No parsing is
performed,andparseerrorscannotoccur.

File

The property is interpreted as a filename,

andanewFilepointingtothatfilenameis
returned.Ifthefilenameisinvalid,aparse
errorwillbethrown.Notethatthefileneed
not exist or be accessible for the filename
tobevalid.

StringGuacamoleProperty

FileGuacamoleProperty

Tousethesetypes,youmustextendthebaseclass,implementingthegetName()functiontoidentifyyour
property. Typically, you would declare these properties as static members of some class containing all
propertiesrelevanttoyourextension:
http://guacdev.org/doc/gug/guacamoleext.html

3/7

12/6/2015

Chapter16.guacamoleext

publicclassMyProperties{
publicstatic MY_PROPERTY =newIntegerGuacamoleProperty(){
@Override
publicStringgetName(){return" myproperty ";}
};
}
YourpropertycanthenberetrievedwithgetProperty()orgetRequiredProperty():
Integervalue=environment.getProperty( MyProperties.MY_PROPERTY );
Ifyouneedmoresophisticatedparsing,youcanalsoimplementyourownpropertytypesbyimplementingthe
GuacamoleProperty interface. The onlyfunctionstoimplementaregetName(), which returns the name of
theproperty,andparseValue(),whichparsesagivenstringandreturnsitsvalue.

Advancedconfiguration
Ifyouneedmorestructureddatathanprovidedbysimpleproperties,youcanplacecompletelyarbitraryfiles
inahierarchyofyourchoosinganywherewithinGUACAMOLE_HOMEaslongasyouavoidplacingyourfilesin
directoriesreservedforotherpurposesasdescribedabove.
The Environment interface exposes the location of GUACAMOLE_HOME through the getGuacamoleHome()
function. This function returns a standard Java File which can then be used to locate other files or
directorieswithinGUACAMOLE_HOME:
FilemyConfigFile=newFile(environment.getGuacamoleHome(),"myconfig.xml");
There is no guarantee that GUACAMOLE_HOME or your file will exist, and you should verify this before
proceedingfurtherinyourextension'sconfigurationprocess,butoncethisisdoneyoucansimplyparseyour
fileasyouseefit.

Authenticationproviders
The main use of guacamoleext is to provide custom authentication for Guacamole through the
implementation of authentication providers. An authentication provider is any class which implements the
AuthenticationProvider interface, implementing the only function defined by that interface:
getUserContext().Thisfunctionisrequiredtoreturna"context"whichprovidesaccesstoonlythoseusers
andconfigurationsaccessiblewiththegivencredentials,andenforcesitsownsecuritymodel.
The credentials given are abstract and while Guacamole the web application implements a
username/password driven login screen, you are not required to user usernames and passwords the
CredentialsclassgiventotheauthenticationproviderprovidesaccesstoallHTTPparametersingeneral,
aswellascookiesandSSLinformation.
The Guacamole web application includes a basic authentication provider implementation which parses an
XMLfiletodeterminewhichusersexist,theircorrespondingpasswords,andwhatconfigurationsthoseusers
have access to. This is the part of Guacamole that reads theusermapping.xml file. If you use a custom
authenticationproviderforyourauthentication,thisfilewillprobablynotberequired.
The community has implemented authentication providers which access databases, use LDAP, or even
perform no authentication at all, redirecting all users to a single configuration specified in
guacamole.properties.
A minimal authentication provider is implemented in the tutorials later, and the upstream authentication
http://guacdev.org/doc/gug/guacamoleext.html

4/7

12/6/2015

Chapter16.guacamoleext

provider implemented within Guacamole, as well as the authentication providers implemented by the
community,aregoodexamplesforhowauthenticationcanbeextendedwithouthavingtoimplementawhole
newwebapplication.

SimpleAuthenticationProvider
TheSimpleAuthenticationProviderclassprovidesamuchsimplermeansofimplementingauthentication
when you do not require the ability to add and remove users and connections. It is an abstract class and
requiresonlyonefunctionimplementation:getAuthorizedConfigurations().
ThisfunctionisrequiredtoreturnaMap of unique IDs to configurations, where these configurations are all
configurationsaccessiblewiththeprovidedcredentials.Asbefore,thecredentialsgivenareabstract.Youare
notrequiredtouseusernamesandpasswords.
The configurations referred to by the function name are instances of GuacamoleConfiguration (part of
guacamolecommon), which is just a wrapper around a protocol name and set of parameter name/value
pairs.Thenameoftheprotocoltouseandasetofparametersistheminimuminformationrequiredforother
partsoftheGuacamoleAPItocompletethehandshakerequiredbytheGuacamoleprotocol.
WhenaclassthatextendsSimpleAuthenticationProviderisaskedformoreadvancedoperationsbythe
webapplication,SimpleAuthenticationProvidersimplyreturnsthatthereisnopermissiontodoso.This
effectivelydisablesalladministrativefunctionalitywithinthewebinterface.
If you choose to go the simple route, most of the rest of this chapter is irrelevant. Permissions, security
model, and various classes will be discussed that are all handled for you automatically by
SimpleAuthenticationProvider.

TheUserContext
The UserContext is the root of all operations. It is used to list, create, modify, or delete users and
connections,aswellastoqueryavailablepermissions.
The Guacamole web application uses permissions queries against the UserContext to determine what
operationstopresent,butbewarethatitisuptotheUserContexttoactuallyenforcetheserestrictions.The
GuacamolewebapplicationwillnotenforcerestrictionsonbehalfoftheUserContext.
TheUserContext is the sole means of entry and the sole means of modification available to a loggedin
user.IftheUserContextrefusestoperformanoperation(bythrowinganexception),theusercannotperform
theoperationatall.

Directoryclasses
AccesstousersandconnectionsisgiventhroughDirectoryclasses.TheseDirectoryclassesaresimilar
to Java collections, but they also embody object update semantics. Objects can be retrieved from a
Directory using its get() function and added or removed with add() and remove() respectively, but
objectsalreadyinthesetcanalsobeupdatedbypassinganupdatedobjecttoitsupdate()function.
An implementation of a Directory can rely on these functions to define the semantics surrounding all
operations.Theadd()functioniscalledonlywhencreatingnewobjects,theupdate()functioniscalledonly
when updating an object previously retrieved with get(), and remove() is called only when removing an
existingobjectbyitsidentifier.
When implementing an AuthenticationProvider, you must ensure that the UserContext will only return
Directoryclassesthatautomaticallyenforcethepermissionsassociatedwithallobjectsandtheassociated
user.

Permissions
The permissions system within guacamoleext is an advisory system. It is the means by which an
authenticationmoduledescribestothewebapplicationwhatauserisallowedtodo.Thebodyofpermissions
grantedtoauserdescribeswhichobjectsthatusercanseeandwhattheycandotothoseobjects,andthus
suggestshowtheGuacamoleinterfaceshouldappeartothatuser.
http://guacdev.org/doc/gug/guacamoleext.html

5/7

12/6/2015

Chapter16.guacamoleext

Permissionsarenotthemeansbywhichaccessisrestrictedtheyarepurelyameansofdescribingaccess
level. An implementation may internally use the permission objects to define restrictions, but this is not
required. It is up to the implementation to enforce its own restrictions by throwing exceptions when an
operation is not allowed, and to correctly communicate the abilities of individual users through these
permissions.
Systempermissions
System permissions describe access to operations that manipulate the system as a whole, rather than
specificobjects.Thisincludesthecreationofnewobjects,asobjectcreationdirectlyaffectsthesystem,and
perobjectcontrolscannotexistbeforetheobjectisactuallycreated.
ADMINISTER
The user is a superuser the Guacamole equivalent of root. They are allowed to manipulate of
systemlevelpermissionsandallotherobjects.Thispermissionimpliesallothers.
CREATE_CONNECTION
The user is allowed to create new connections. If a user has this permission, the management
interface will display components related to connection creation, such as the "Manage" and "New
Connection"buttons.
CREATE_CONNECTION_GROUP
Theuserisallowedtocreatenewconnectiongroups.Ifauserhasthispermission,themanagement
interfacewilldisplaycomponentsrelated to connection group creation, such as the "Manage" and
"NewGroup"buttons.
CREATE_USER
Theuserisallowedtocreateotherusers.Ifauserhasthispermission,themanagementinterface
willdisplaycomponentsrelatedtousercreation,suchasthe"Manage"and"NewUser"buttons.
Objectpermissions
Objectpermissionsdescribeaccesstooperationsthataffectaparticularobject.Guacamolecurrentlydefines
threetypesofobjectswhichcanbeassociatedwithpermissions:users,connections,andconnectiongroups.
Eachobjectpermissionassociatesasingleuserwithanactionthatmaybeperformedonasingleobject.
ADMINISTER
The user may grant or revoke permissions involving this object. "Involving", in this case, refers to
either side of the permission association, and includes both the user to whom the permission is
grantedandtheobjectthepermissionaffects.
DELETE
Theusermaydeletethisobject.ThisisdistinctfromtheADMINISTERpermissionwhichdealsonly
withpermissions.Auserwiththispermissionwillseethe"Delete"buttonwhenapplicable.
READ
Theusermayseethatthisobjectexistsandreadthepropertiesofthatobject.
Notethattheimplementationisnotrequiredtodivulgethetrueunderlyingpropertiesofanyobject.
Theparametersofaconnection,thetypeorcontentsofaconnectiongroup,thepasswordofauser,
etc.allneednotbeexposed.
Thisisparticularlyimportantfromtheperspectiveofsecuritywhenitcomestoconnections,asthe
parameters of a connection are only truly needed when a connection is being modified, and likely
shouldnotbeexposedotherwise.Theactualconnectionoperationisalwaysperformedinternallyby
theauthenticationprovider,andthusdoesnotrequireclientsideknowledgeofanythingbeyondthe
http://guacdev.org/doc/gug/guacamoleext.html

6/7

12/6/2015

Chapter16.guacamoleext

connection'sexistence.
UPDATE
Theusermaychangethepropertiesofthisobject.
Inthecaseofusers,thismeanstheuser'spasswordcanbealtered.Permissionsarenotconsidered
properties of a user, nor objects in their own right, but rather associations between a user and an
actionwhichmayinvolveanotherobject.
Thepropertiesofaconnectionincludeitsname,protocol,parentconnectiongroup,andparameters.
Thepropertiesofaconnectiongroupincludeitsname,type,parentconnectiongroup,andchildren.

Connectionsandhistory
AuthenticationmodulesmustreturnConnectionobjectswhicheachimplementaconnect()function.When
thisfunctioniscalled,theconnectionmustbemadeifpermissionisavailable.
Thisnewseparationofconcernsmakesmoresensewhenyouconsiderthatasconnectingisanoperationon
a Connection, access to performing that operation must be restricted through the
AuthenticationProvider, and thus must be enforced within the AuthenticationProvider. This
separationalsoopensthedoorforthingslikeloadbalancingofconnectionsandrestrictingconcurrentaccess
toconnections.
When a connection is made or terminated, it is also the duty of the authentication module to maintain the
connectionhistory.EachconnectionhasacorrespondinglistofConnectionRecordobjects,eachofwhichis
associatedwithapastconnectionoracurrentlyactiveconnection.Thisinformationwillultimatelybeexposed
totheuserasahistorylistwhentheyviewaconnectioninthemanagementinterfaceorasasimpleactive
usercountontheconnection,advisingtheuserofexistingactivity.

http://guacdev.org/doc/gug/guacamoleext.html

7/7