guacd chapter 16

12/6/2015 Chapter16.guacamoleext

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

Chapter16.guacamoleextWhilenotstrictlypartoftheJavaAPIprovidedbytheGuacamoleproject,guacamoleextisanAPIexposedbytheGuacamolewebapplicationwithinaseparateprojectsuchthatextensions,specificallyauthenticationproviders,canbewrittentotweakGuacamoletofitwellinexistingdeployments.

ExtensionstoGuacamolecan:

1. Providealternativeauthenticationmethodsandsourcesofconnection/userdata.

2. ThemeorbrandGuacamolethroughadditionalCSSfilesandstaticresources.

3. ExtendGuacamole'sJavaScriptcodebyprovidingJavaScriptthatwillbeloadedautomatically.

4. Addadditionaldisplaylanguages,oralterthetranslationstringsofexistinglanguages.

GuacamoleextensionformatGuacamoleextensionsarestandardJava.jarfileswhichcontainallclassesandresourcesrequiredbytheextension,aswellastheGuacamoleextensionmanifest.Thereisnosetstructuretoanextensionexceptthatthemanifestmustbeintherootofthearchive.Javaclassesandpackages,ifany,willbereadfromthe.jarrelativetotheroot,aswell.

Beyond this, the semantics and locations associated with all other resources within the extension aredeterminedbytheextensionmanifestalone.

Extensionmanifest

TheGuacamoleextensionmanifestisasingleJSONfile,guacmanifest.json,whichdescribesthelocationofeachresource,thetypeofeachresource,andtheversionofGuacamolethattheextensionwasbuiltfor.Themanifestcancontainthefollowingproperties:

Property Description

guacamoleVersion

Theversionstringof theGuacamole release that thisextension iswrittenfor.Thisproperty is required forallextensions. The special version string"*"canbeusediftheextensiondoesnotdependonaparticularversionofGuacamole,butbecareful thiswill bypass version compatibility checks,andshouldneverbeusediftheextensiondoesmorethanbasicthemingorbranding.

name

Ahumanreadablenamefortheextension.Thispropertyisrequiredforallextensions. When your extension is successfully loaded, a messageacknowledging the successful loading of your extension by namewill belogged.

namespace

Auniquestringwhichidentifiesyourextension.Thispropertyisrequiredforall extensions. This string should be unique enough that it is unlikely tocollidewiththenamespaceofanyotherextension.

Ifyourextensioncontainsstaticresources,thoseresourceswillbeservedatapathderivedfromthenamespaceprovidedhere.



authProviders

An array of the classnames of all AuthenticationProvider subclassesprovided by this extension. Guacamole currently only supports oneAuthenticationProvider being loaded at a time, thus this array mustonlycontainoneelement,ifitispresentatall.

js

An array of all JavaScript files within the extension. All paths within thisarraymustberelativepaths,andwillbe interpreted relative to the rootofthearchive.

JavaScript files declared herewill be automatically loadedwhen thewebapplicationloadswithintheuser'sbrowser.

css

An array of all CSS files within the extension. All paths within this arraymust be relative paths, and will be interpreted relative to the root of thearchive.

CSS files declared here will be automatically applied when the webapplicationloadswithintheuser'sbrowser.

translations

An array of all translation files within the extension. All paths within thisarraymustberelativepaths,andwillbe interpreted relative to the rootofthearchive.

Translationfilesdeclaredherewillbeautomaticallyaddedtothe availablelanguages.IfatranslationfileprovidesalanguagethatalreadyexistswithinGuacamole,itsstringswilloverridethestringsoftheexistingtranslation.

resources

Anobjectwhereeachpropertyname is thenameofaweb resource file,and each value is the mimetype for that resource. All paths within thisobjectmustberelativepaths,andwillbeinterpretedrelativetotherootofthearchive.

Web resourcesdeclaredherewill bemadeavailable to theapplicationatapp/ext/ NAMESPACE / PATH , where NAMESPACE is the value of thenamespaceproperty,and PATH isthedeclaredwebresourcefilename.

TheonlyabsolutelyrequiredpropertiesareguacamoleVersion,name,andnamespace,astheyareusedtoidentify the extension and for compatibility checks. The most minimal guacmanifest.json will looksomethinglikethis:

{"guacamoleVersion":"0.9.7","name":"MyExtension","namespace":"myextension"}

Thiswillallowtheextensiontoload,butdoesabsolutelynothingotherwise.Lackingthesemanticinformationprovided by the other properties, no other files within the extension will be used. A typical guacmanifest.jsonforanextensionprovidingthemingorbrandingwouldbemoreinvolved:

{



"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"}

}

AccessingtheserverconfigurationTheconfigurationof theGuacamoleserver isexposed through theEnvironment interface,specifically theLocalEnvironment implementationof this interface.ThroughEnvironment, you canaccessall propertiesdeclared within guacamole.properties, determine the proper hostname/port of guacd, and access thecontentsofGUACAMOLE_HOME.

Customproperties

If your extension requires generic, unstructured configuration parameters, guacamole.properties is areasonable and simple location for them. The Environment interface provides direct access toguacamole.propertiesandsimplemechanismsforreadingandparsingthepropertiestherein.ThevalueofapropertycanberetrievedcallinggetProperty(),whichwill returnnulloradefaultvalue forundefinedproperties,orgetRequiredProperty(),whichwillthrowanexceptionforundefinedproperties.

Forconvenience,guacamoleextcontainsseveralpredefinedpropertybaseclassesforcommontypes:

ClassName ValueType Interpretation

BooleanGuacamoleProperty BooleanThevalues"true"and"false"areparsedastheir corresponding Boolean values. Anyothervalueresultsinaparseerror.

IntegerGuacamoleProperty IntegerNumeric strings are parsed as Integervalues.Nonnumericstringswill result inaparseerror.

LongGuacamoleProperty LongNumericstringsareparsedasLongvalues.Nonnumeric strings will result in a parseerror.

StringGuacamoleProperty StringThe property value is returned as anuntouched String. No parsing isperformed,andparseerrorscannotoccur.

FileGuacamoleProperty File

The property is interpreted as a filename,andanewFilepointingtothatfilenameisreturned. If thefilenameis invalid,aparseerrorwillbethrown.Notethatthefileneednotexistorbeaccessible for the filenametobevalid.

Tousethesetypes,youmustextendthebaseclass, implementingthegetName() functionto identifyyourproperty. Typically, you would declare these properties as static members of some class containing allpropertiesrelevanttoyourextension:



publicclassMyProperties{

publicstatic MY_PROPERTY =newIntegerGuacamoleProperty(){

@OverridepublicStringgetName(){return" myproperty ";}

};

}

YourpropertycanthenberetrievedwithgetProperty()orgetRequiredProperty():

Integervalue=environment.getProperty( MyProperties.MY_PROPERTY );

Ifyouneedmoresophisticatedparsing,youcanalsoimplementyourownpropertytypesbyimplementingtheGuacamoleProperty interface.Theonlyfunctionsto implementaregetName(),whichreturns thenameoftheproperty,andparseValue(),whichparsesagivenstringandreturnsitsvalue.

Advancedconfiguration

Ifyouneedmorestructureddatathanprovidedbysimpleproperties,youcanplacecompletelyarbitraryfilesinahierarchyofyourchoosinganywherewithinGUACAMOLE_HOMEaslongasyouavoidplacingyourfilesindirectoriesreservedforotherpurposesasdescribedabove.

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 ordirectorieswithinGUACAMOLE_HOME:

FilemyConfigFile=newFile(environment.getGuacamoleHome(),"myconfig.xml");

There is no guarantee that GUACAMOLE_HOME or your file will exist, and you should verify this beforeproceedingfurtherinyourextension'sconfigurationprocess,butoncethisisdoneyoucansimplyparseyourfileasyouseefit.

AuthenticationprovidersThe main use of guacamoleext is to provide custom authentication for Guacamole through theimplementation of authentication providers. An authentication provider is any class which implements theAuthenticationProvider interface, implementing the only function defined by that interface:getUserContext().Thisfunctionisrequiredtoreturna"context"whichprovidesaccesstoonlythoseusersandconfigurationsaccessiblewiththegivencredentials,andenforcesitsownsecuritymodel.

The credentials given are abstract and while Guacamole the web application implements ausername/password driven login screen, you are not required to user usernames and passwords theCredentialsclassgiventotheauthenticationproviderprovidesaccesstoallHTTPparametersingeneral,aswellascookiesandSSLinformation.

TheGuacamoleweb application includes a basic authentication provider implementationwhich parses anXMLfiletodeterminewhichusersexist,theircorrespondingpasswords,andwhatconfigurationsthoseusershaveaccess to.This is thepartofGuacamole that reads theusermapping.xml file. Ifyouuseacustomauthenticationproviderforyourauthentication,thisfilewillprobablynotberequired.

The community has implemented authentication providers which access databases, use LDAP, or evenperform no authentication at all, redirecting all users to a single configuration specified inguacamole.properties.

A minimal authentication provider is implemented in the tutorials later, and the upstream authentication



provider implemented within Guacamole, as well as the authentication providers implemented by thecommunity,aregoodexamplesforhowauthenticationcanbeextendedwithouthavingtoimplementawholenewwebapplication.

SimpleAuthenticationProvider

TheSimpleAuthenticationProviderclassprovidesamuchsimplermeansofimplementingauthenticationwhenyoudonot require theability toaddand removeusersandconnections. It is anabstract classandrequiresonlyonefunctionimplementation:getAuthorizedConfigurations().

This function isrequiredtoreturnaMapofunique IDs toconfigurations,where theseconfigurationsareallconfigurationsaccessiblewiththeprovidedcredentials.Asbefore,thecredentialsgivenareabstract.Youarenotrequiredtouseusernamesandpasswords.

The configurations referred to by the function name are instances of GuacamoleConfiguration (part ofguacamolecommon), which is just a wrapper around a protocol name and set of parameter name/valuepairs.ThenameoftheprotocoltouseandasetofparametersistheminimuminformationrequiredforotherpartsoftheGuacamoleAPItocompletethehandshakerequiredbytheGuacamoleprotocol.

WhenaclassthatextendsSimpleAuthenticationProviderisaskedformoreadvancedoperationsbythewebapplication,SimpleAuthenticationProvidersimplyreturnsthatthereisnopermissiontodoso.Thiseffectivelydisablesalladministrativefunctionalitywithinthewebinterface.

If you choose to go the simple route, most of the rest of this chapter is irrelevant. Permissions, securitymodel, and various classes will be discussed that are all handled for you automatically bySimpleAuthenticationProvider.

TheUserContext

The UserContext is the root of all operations. It is used to list, create, modify, or delete users andconnections,aswellastoqueryavailablepermissions.

The Guacamole web application uses permissions queries against the UserContext to determine whatoperationstopresent,butbewarethatitisuptotheUserContexttoactuallyenforcetheserestrictions.TheGuacamolewebapplicationwillnotenforcerestrictionsonbehalfoftheUserContext.

TheUserContext is the solemeansof entry and the solemeans ofmodification available to a loggedinuser.IftheUserContextrefusestoperformanoperation(bythrowinganexception),theusercannotperformtheoperationatall.

Directoryclasses

AccesstousersandconnectionsisgiventhroughDirectoryclasses.TheseDirectoryclassesaresimilarto Java collections, but they also embody object update semantics. Objects can be retrieved from aDirectory using its get() function and added or removed with add() and remove() respectively, butobjectsalreadyinthesetcanalsobeupdatedbypassinganupdatedobjecttoitsupdate()function.

An implementation of a Directory can rely on these functions to define the semantics surrounding alloperations.Theadd()functioniscalledonlywhencreatingnewobjects,theupdate()functioniscalledonlywhen updating an object previously retrievedwithget(), andremove() is called onlywhen removing anexistingobjectbyitsidentifier.

When implementinganAuthenticationProvider,youmustensure that theUserContextwill only returnDirectoryclassesthatautomaticallyenforcethepermissionsassociatedwithallobjectsandtheassociateduser.

Permissions

The permissions system within guacamoleext is an advisory system. It is the means by which anauthenticationmoduledescribestothewebapplicationwhatauserisallowedtodo.Thebodyofpermissionsgrantedtoauserdescribeswhichobjectsthatusercanseeandwhattheycandotothoseobjects,andthussuggestshowtheGuacamoleinterfaceshouldappeartothatuser.



Permissionsarenotthemeansbywhichaccessisrestrictedtheyarepurelyameansofdescribingaccesslevel. An implementation may internally use the permission objects to define restrictions, but this is notrequired. It is up to the implementation to enforce its own restrictions by throwing exceptions when anoperation is not allowed, and to correctly communicate the abilities of individual users through thesepermissions.

Systempermissions

System permissions describe access to operations that manipulate the system as a whole, rather thanspecificobjects.Thisincludesthecreationofnewobjects,asobjectcreationdirectlyaffectsthesystem,andperobjectcontrolscannotexistbeforetheobjectisactuallycreated.

ADMINISTER

The user is a superuser theGuacamole equivalent of root. They are allowed tomanipulate ofsystemlevelpermissionsandallotherobjects.Thispermissionimpliesallothers.

CREATE_CONNECTION

The user is allowed to create new connections. If a user has this permission, the managementinterfacewilldisplaycomponents related toconnectioncreation,suchas the "Manage"and "NewConnection"buttons.

CREATE_CONNECTION_GROUP

Theuserisallowedtocreatenewconnectiongroups.Ifauserhasthispermission,themanagementinterfacewilldisplaycomponentsrelated toconnectiongroupcreation,suchas the"Manage"and"NewGroup"buttons.

CREATE_USER

Theuserisallowedtocreateotherusers.Ifauserhasthispermission,themanagementinterfacewilldisplaycomponentsrelatedtousercreation,suchasthe"Manage"and"NewUser"buttons.

Objectpermissions

Objectpermissionsdescribeaccesstooperationsthataffectaparticularobject.Guacamolecurrentlydefinesthreetypesofobjectswhichcanbeassociatedwithpermissions:users,connections,andconnectiongroups.Eachobjectpermissionassociatesasingleuserwithanactionthatmaybeperformedonasingleobject.

ADMINISTER

Theusermaygrantor revokepermissions involving thisobject. "Involving", in thiscase, refers toeither side of the permission association, and includes both the user to whom the permission isgrantedandtheobjectthepermissionaffects.

DELETE

Theusermaydeletethisobject.ThisisdistinctfromtheADMINISTERpermissionwhichdealsonlywithpermissions.Auserwiththispermissionwillseethe"Delete"buttonwhenapplicable.

READ

Theusermayseethatthisobjectexistsandreadthepropertiesofthatobject.

Notethattheimplementationisnotrequiredtodivulgethetrueunderlyingpropertiesofanyobject.Theparametersofaconnection,thetypeorcontentsofaconnectiongroup,thepasswordofauser,etc.allneednotbeexposed.

Thisisparticularlyimportantfromtheperspectiveofsecuritywhenitcomestoconnections,astheparametersofaconnectionareonly trulyneededwhenaconnection isbeingmodified,and likelyshouldnotbeexposedotherwise.Theactualconnectionoperationisalwaysperformedinternallybytheauthenticationprovider,andthusdoesnotrequireclientsideknowledgeofanythingbeyondthe



connection'sexistence.

UPDATE

Theusermaychangethepropertiesofthisobject.

Inthecaseofusers,thismeanstheuser'spasswordcanbealtered.Permissionsarenotconsideredpropertiesofauser,norobjects in theirownright,but ratherassociationsbetweenauserandanactionwhichmayinvolveanotherobject.

Thepropertiesofaconnectionincludeitsname,protocol,parentconnectiongroup,andparameters.Thepropertiesofaconnectiongroupincludeitsname,type,parentconnectiongroup,andchildren.

Connectionsandhistory

AuthenticationmodulesmustreturnConnectionobjectswhicheachimplementaconnect()function.Whenthisfunctioniscalled,theconnectionmustbemadeifpermissionisavailable.

Thisnewseparationofconcernsmakesmoresensewhenyouconsiderthatasconnectingisanoperationona Connection, access to performing that operation must be restricted through theAuthenticationProvider, and thus must be enforced within the AuthenticationProvider. Thisseparationalsoopensthedoorforthingslikeloadbalancingofconnectionsandrestrictingconcurrentaccesstoconnections.

Whenaconnection ismadeor terminated, it isalso thedutyof theauthenticationmodule tomaintain theconnectionhistory.EachconnectionhasacorrespondinglistofConnectionRecordobjects,eachofwhichisassociatedwithapastconnectionoracurrentlyactiveconnection.Thisinformationwillultimatelybeexposedtotheuserasahistorylistwhentheyviewaconnectioninthemanagementinterfaceorasasimpleactiveusercountontheconnection,advisingtheuserofexistingactivity.

guacd chapter 16

Documents