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’s 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

Sections

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”

Item list

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