Configuring REST Permission Roles
REST permission roles are assigned to administrators by selecting an available role from the drop-down list to the right of the REST administrator role check box at the bottom of the Site > Administration tab. This list is populated by roles defined in PermissionRoles.json and are read every time the list control is clicked. Refer to Enabling REST API for Remote Admin for details of enabling the REST API.
Server-level administrators can define a set of permissions for operations on one or more REST endpoints as a permissions role (aka policy) which can subsequently be assigned to one or more EFT administrators. These roles, not linked to existing administration access modes, allow precise control over what each administrator can and cannot do within the context of REST. Having roles defined in JSON gives server-level administrators maximum flexibility in the number, kinds, and granularity of permissions assigned to a role. The PermissionRoles.json file is created at installation (C:\ProgramData\Globalscape\EFT Server) with the default roles server_read and server_full_access:
[
{
"name": "server_read",
"enabled": true,
"permissions": [
"server:*:*:*:read",
"sites:*:*:*:read"
]
},
{
"name": "server_full_access",
"enabled": true,
"permissions": [
"server:*:*:*:*",
"sites:*:*:*:*"
]
}
]
Each role composed of a name (maximum length 255 UTF-8 characters), a flag denoting whether the role is enabled, and a list of permissions strings. You can add additional permissions to the file as described below.
Permissions String
The "permissions" string has five sections separated by colons (:). The sections, ordered from left to right, are Primary Area, Area, Sub Area, Item, and Action. For example, the sections of the permissions strings for the default "server_read" role above are:
|
Primary Area |
Area |
Sub Area |
Item |
Action |
|---|---|---|---|---|
|
server: |
*: |
*: |
*: |
read |
|
sites: |
*: |
*: |
*: |
read |
The use of the wildcard ‘*’ is explained below.
Primary Area, Area, Sub Area
Values for each section are:
|
Primary Areas |
Areas |
Sub Areas |
|---|---|---|
|
server |
server |
settings |
|
sites |
sites |
metrics |
|
settings |
||
|
users |
settings |
|
|
personaldata |
||
|
eventrules |
settings |
|
|
folders |
settings |
|
|
ram |
settings |
Item:
Values that go in the Items section are names of name-value pairs used in JSON requests and responses. This provides permissions granularity down to the individual configuration setting level. Several items can be listed in this section with a comma between them.
Refer to Item list below.
Action:
-
create
-
read
-
update
-
delete
-
execute
Several actions can be listed with commas between them. Not all actions are applicable to all items. Please refer to the endpoint documentation to know which actions are applicable to any given item.
An asterisk (*), meaning all, can be used for any section after the primary area. If an asterisk has been used for area or sub area an asterisk must be used for the item. If an item must be specific, that is no (*), then the area and sub area must also be specific. An exclamation mark (!) preceding a value means all values except the specified value. For example, this permission string allows an administrator to create users for any site and read all their settings but not delete the user or update their settings:
"sites[*]:users[*]:*:*:create,read"
Filters
Filters can be used with the sites primary area and all areas to target permissions to very specific cases and are defined by including an appropriate string inside brackets []. If (*) is used instead of a string it means all, or no filtering, and can be omitted if desired. So, if building a permissions string that applies to only one user, JaneDoe, for all sites you would use:
"sites[*]:users[JaneDoe]…"
Multiple filters can be specified by adding bracketed strings. A permissions string that applies only to two rules for all sites would look like:
"sites[*]:eventrules[MyFolderMonitor][MyTimer]…"
Matching filter strings to the area they are applied to is the default. That is, the default filter behavior for the users area is to apply the filter string against user names, for the folders area is to apply the filter string against folder names, etc. Filters can be applied to special filter areas other than their default area. The special filter areas are:
-
usergroup
-
usertemplate
-
eventrulefolder
-
eventrules
-
node
To apply a filter to one of these special filter areas the area must prefix the filter string with a colon (:) separating them. For instance, a permissions string that applies only to users belonging to the Guest user group on the site MySite would start this way:
"sites[MySite]:users[usergroup:Guest]:……"
In addition to using filters to single out a few special cases in which to apply the permission string, they can also be used to exclude special cases. By prefixing the string with "*,!" exceptions can be specified. So, a permissions string that is intended to apply to every user on a site except for JohnDoe would begin like this:
"sites[MySite]:users[*,!JohnDoe]:……"
Examples
Below are examples of permissions strings categorized by general use case:
User-Related Permissions:
Admin can create users and configure everything about those users:
"sites[*]:users[*]:*:*:create,read,update"
Admin can create users except for a user name matching "Administrator":
"sites[*]:users[*,!Administrator]:*:*:create"
Admin can read all the configuration for all users for a given site named "MeeTooSite":
"sites[MeeTooSite]:users[*]:*:*:read"
Admin can read the AllowSecureFolderSharing value for users in the Guest Users template, but cannot read any other values or do anything else:
"sites[*]:users[settingstemplate:Guest Users]:settings:AllowSecureFolderSharing:read"
Note: When an admin with only this users permission does a GET on users, the response will contain only the users belonging to the Guest Users template. If the admin does a get on a user belonging to Guest Users, only the UUID and the value for AllowSecureFolderSharing is returned. Since name isn’t allowed per this permission then name will not be returned.
Admin can read the configuration to find out everything about all users in Site "MySite" under template "Guest Users" but not make any changes to those users:
"sites[MySite]:users[settingstemplate:Guest Users]:*:*:read"
Admin can update everything about any user:
"sites[*]:users[*]:*:*:update"
Admin can update everything about any user except for changing their SFTP key:
"sites[*]:users[*]:connection:*,!sftpkey:update"
Admin can update all users except for a user matching a specific name of "John":
"sites[*]:users[*,!John]:*:*:read,update"
Admin can update users but not create them or delete them:
"sites[*]:users[*]:*:*:read,update"
Admin can delete users:
"sites[*]:users[*]:*:*:delete"
Admin can delete all users except for a user named "John":
"sites[*]:users[*,!John]:*:*:delete"
VFS-Related Permissions:
Admin can read and create maps for the folder "bin":
"site[MySite]:folders[/bin/]:folders:maps:create,read"
Admin can create, update, and read folder names for the "usr" folder:
"site[MySite]:folders [/usr/]:folders:folder:create,read,update"
Admin can read and update permissions for the folder "bin":
"site[MySite]:folders [/bin/]:folders:permissions:read,update"
Admin can read and change the encrypt setting for folders in the folder "bin":
"site[MySite]:folders [/bin/]:folders:encrypt:read,update"
|
server:server:metrics: |
activeclientdownloadbytespersecond activeclientdownloadcount activeclientuploadbytespersecond activeclientuploadcount activeserverdownloadbytespersecond activeserverdownloadcount activeserveruploadbytespersecond activeserveruploadcount connectedadmincount connectedusercount runningawtaskcount runningeventrulecount isnodemaster isnodestarted licensemodules localtime nodename uptime |
|
server:server:settings: |
ha.enabled smtp smtp.login smtp.password smtp.port smtp.senderaddr smtp.sendername smtp.server smtp.useauthentication smtp.useimplicittls general.configfilepath general.lastmodifiedby general.lastmodifiedtime general.useutcinlistings listenersettings.adminport listenersettings.allowremoteadministration listenersettings.listenips listenersettings.localips logs.audit logs.audit logs.audit logs.audit logs.audit logs.audit logs.logfilepath logs.audit.password logs.audit.connected version nodename |
|
sites[ ]:sites:settings |
dmz.enabled dmz.server.ipaddresses dmz.server.nodename dmz.server.port general.authtype general.disabledusercount general.lastmodifiedby general.lastmodifiedtime general.rootfolder general.usercount listenersettings listenersettings.httpdomain listenersettings.accountmanagementurl listenersettings.listenips listenersettings.ftpsimplicitport listenersettings.ftpport listenersettings.ftpsport listenersettings.httpsport listenersettings.httpport listenersettings.sftpport name workspacessettings.enabled |
|
sites[ ] :sites:metrics: |
definedusers isdmzgatewayconnected isrunning name activeclientdownloadbytespersecond activeclientdownloadcount activeclientuploadbytespersecond activeclientuploadcount activeserverdownloadbytespersecond activeserverdownloadcount activeserveruploadbytespersecond activeserveruploadcount connectedusercount node.name runningawtaskcount runningeventrulecount starttime state dmzconnected |
|
sites[ ]:users:connections: |
as2.inbound.enabled as2.outbound.enabled ftp.enabled ftp.value.banner.message ftp.value.banner.usage ftp.value.enablecomb ftp.value.enablefxp ftp.value.enablenoop ftp.value.enablexcrc ftp.value.enablezlib ftps.enabled http.enablehttp http.enablehttps http.enablesendmessage http.enablesharefolder http.enablewtc sftp.enabled sftp.value.authenticationtype ssl.authenticationtype transferspeedlimit.enabled transferspeedlimit.value.maxkbps uploadsizelimit.enabled uploadsizelimit.value.maxkbytes uploadspersessionlimit.enabled uploadspersessionlimit.value.maxnumber downloadsizelimit.enabled downloadsizelimit.value.maxkbytes downloadspersessionlimit.enabled downloadspersessionlimit.value.maxnumber connectiontimeout.enabled connectiontimeout.value.maxsec connectionsfromsameiplimit.enabled connectionsfromsameiplimit.value.maxnumber totalconnectionslimit.enabled totalconnectionslimit.value.maxnumber sshkeys.data sslcertificate.data |
|
sites[ ]:users:settings: |
accountenabled agreementtotermsofservice changepassword.enabled changepassword.value.changeadminprovidedpassworduponfirstuse changepassword.value.mustchangepassword changepassword.value.passwordexpiration.enabled changepassword.value.passwordexpiration.emailupon changepassword.value.passwordexpiration.maxagedays changepassword.value.passwordexpiration.remindprior consenttoprivacypolicy expiration.enabled expiration.value.date externalauthentication hashomefolderasroot homefolder.enabled homefolder.value.path inactivitylimit.enabled inactivitylimit.value.action inactivitylimit.value.days invalidloginlimit.enabled invalidloginlimit.value.action invalidloginlimit.value.actiondurationmin invalidloginlimit.value.maxcount invalidloginlimit.value.periodmin iseudatasubject loginname passwordcomplexity.enabled passwordcomplexity passwordhistory.enabled passwordhistory.value.historydepth ipaccesslimit.enabled ipaccesslimit.value.defaultrule ipaccesslimit.value.rules settingstemplate.data permissiongroups.data |
|
sites[ ]:users:personaldata |
personal.duns personal.comments personal.company personal.custom1 personal.custom2 personal.custom3 personal.description personal.email personal.fax personal.mobile personal.name personal.pager personal.partnerid personal.phone |
|
sites[ ]:users:as2in: |
mdnsendattemptdelayseconds mdnsendattemptretries mdnsendattempttimeoutseconds micalgorithm allowedencryptionalgorithms allowedsignaturealgorithms authenticationtype contentcollision donotsend100continue foldertomovedatato myid partnercertificatefilepath partnerid rejectidmismatch rejectmessageidcollision rejectnotencrypted rejectnotsigned rejectpartneridmismatch renamefilesto transactionfailedcommandsettings transactionfailedcommandsettings.parameters transactionfailedcommandsettings.workingdirectory transactionfailedemail.bcc transactionfailedemail.body transactionfailedemail.cc transactionfailedemail.ccuser transactionfailedemail.from transactionfailedemail.subject transactionfailedemail.to transactionsuccesscommandsettings transactionsuccesscommandsettings.parameters transactionsuccesscommandsettings.workingdirectory transactionsuccessemail transactionsuccessemail.bcc transactionsuccessemail.body transactionsuccessemail.cc transactionsuccessemail.ccuser transactionsuccessemail.from transactionsuccessemail.subject transactionsuccessemail.to transactionfailedcommand.data transactionsuccesscommand.data |
|
sites[ ]:users:as2out: |
asyncmdntimeoutminutes compress contenttype deletefileafteroffload encrypt encryptionalgorithm fileexclude fileinclude headers hotfolderpath myid partnercertificatefilepath partnerid proxy.enable proxy.value proxy.value.httpproxy.host proxy.value.httpproxy.port proxy.value.httpproxy.username receipt receiptdelivery sendattemptdelayseconds sendattemptretries sendattempttimeoutseconds serverhost serverpath serverport serverusername sign signaturealgorithm subject transactionfailedcommandsettings.parameters transactionfailedcommandsettings.workingdirectory transactionfailedemail.bcc transactionfailedemail.body transactionfailedemail.cc transactionfailedemail.ccuser transactionfailedemail.from transactionfailedemail.subject transactionfailedemail.to transactionsuccesscommandsettings.parameters transactionsuccesscommandsettings.workingdirectory transactionsuccessemail.bcc transactionsuccessemail.body transactionsuccessemail.cc transactionsuccessemail.ccuser transactionsuccessemail.from transactionsuccessemail.subject transactionsuccessemail.to transactionfailedcommand.data transactionsuccesscommand.data |
|
sites[ ]:folders:settings: |
name target |
|
sites[ ]:eventrules:settings: |
info.description info.enabled info.folder info.name info.next info.remote info.type info statements trigger folder |