linkRoleWithPrivileges

The "linkRoleWithPrivileges" action assigns privileges to one role. It can permit, deny, and remove privileges. It can recursively deny a "manage" privilege and its descendants, or it can deny just the privilege. 

Important

Changing role-based privileges does not affect open data files because their privileges are cached. When you are done modifying privileges, you must run the "applyPrivileges" action to apply your changes to open data files.
A denied privilege overrides all other privileges that permit it. Thus, when an account has a role with a denied privilege, the account cannot perform that privilege's action – even if other privileges permit it.
When a privilege is not assigned to a role or when it is removed from a role, the role is neutral about that privilege. It does not permit or deny it. 

 

All-or-nothing

When an error occurs, the entire action fails, assigns no privileges, and returns the error.

 

Works on one role

The action specifies the "roleName" once at the beginning of the action and can apply privileges to one role at a time. This helps the user see and manage the privileges applied to a role which mitigates some security problems. 

The action specifies the database and namespace once at the beginning of the action and can apply privileges to one database and namespace at a time. By changing the action's database and namespace, the user can apply a role's privileges to a different database or namespace, such as development, test, stage, and production environments.

 

Assigns and removes privileges from one role

You can permit or deny a privilege assigned to a role. When a privilege does not exist, the action returns the following error: "Privilege PPP does not exist. You may have misspelled it." 

You can remove all privileges from a role.

You can remove specific privileges from a role.

You may assign a privilege to a role only once. A privilege cannot exist in a role in multiple ways, such as a permission and a recursive denial. If you assign a privilege to a role that already contains the privilege, the new privilege replaces the previous one. For example, if a  role has the manageAnyTableInAnyDatabase permission, and the action recursively denies it, the new privilege replaces the old one. If you include a privilege more than once in the "linkRoleWithPrivileges" action, it returns the following error: "You must not include privilege PPP more than once in the \"linkRoleWithPrivileges\" action."

Each privilege applies to one type of object. For example, the manageAnyDatabase privilege applies to all database objects, and the describeOneTable privilege applies to a named table object.

 

Permits and denies privileges

A permission allows the role to perform the action described by the privilege.

A denial causes the role to actively deny the privilege – even if other roles permit it. 

Denials always override permissions.

If you never assign a privilege to a role or you remove it from the role, the role is neutral and neither permits or denies the privilege.

If a role does not have a permission, it cannot authorize an account to perform the action, but it does not stop other roles from permitting it.

If a role denies a permission, it prevents an account from performing the action — even if other roles permit it.

The following properties are optional but at least one must be included in the action: 

  • "permissions" assigns permissions to the role.
  • "shallowDenials" assigns shallow denials to the role.
  • "recursiveDenials" assigns recursive denials to the role.
  • "removals" removes privileges from the role.
  • "resetPrivileges": true removes all privileges from the role before it assigns privileges.

If the action does not include one of the following properties, it returns the error:  "The linkRoleWithPrivileges action requires you to specify one of the following properties: \"permissions\", \"denyShallow\", "recursiveDenials", "removals", or "resetPrivileges": true."

 

Optionally replaces existing privileges

The "linkRoleWithPrivileges" action replaces a role's existing privileges.

If a privilege is already assigned to a role and you use the "linkRoleWithPrivileges" action to assign it again, the action removes the previous assignment and replaces it with the new one.

For example, if a privilege is assigned to a role as a permission and you use the "linkRoleWithPrivileges" action to assign it as a shallow denial, the action replaces the permission with the shallow denial. The role will now deny the privilege.

For example, if a privilege is assigned to a role as a recursive denial and you use the "linkRoleWithPrivileges" action to remove it from the role, the role is neutral and no longer denies or permits the privilege.

 

Optionally remove all privileges assigned to the role

Include the "resetPrivileges": true setting to remove all privileges from the role.

This step occurs first, followed by the permissions, deny shallow, and deny recursive assignments.

This setting ensures a role contains only the privileges assigned by the action.

For example, you can use this setting to create an official definition of a role's privileges. When you run the "linkRoleWithPrivileges" action in multiple environments, this setting ensures each role's privileges match the official definition.

For example, you can use this setting by itself to nullify a role to stop a malicious attacker who is using it to gain elevated access.

When the "resetPrivileges": true setting is present, the action ignores the "removals" property because the setting has already removed all preexisting privileges from the role.

The optional "resetPrivileges" property is a boolean with a true or false value. When it is omitted or set to null, it defaults to false.

 

Recursive and shallow denials

A recursive denial denies the privilege and its descendants.

You can shallowly deny any privilege.

  • A shallow denial denies only the specified privilege – not its descendants. For example, you can shallowly deny a role from managing all tables in all databases, and you can permit the role to read all records in all databases.

You can recursively deny privileges with descendants.

  • For example, you can recursively deny a role from managing all tables in all databases, and the server will ignore a permission to read all records in all databases because it is a child privilege of the denied privilege.

Tip If a privilege contains the word "manage", it has descendants.

 

Global and object scopes

A privilege either has global or object scope.

A globally scoped privilege applies to many objects, such as createAnyTableInAnyDatabase.

  • Global privileges do not apply to a specific object.
  • If a privilege does not have the word "One" in it, it is a global privilege.
  • For example, the readAnyRecordInAnyTableInAnyDatabase privilege is a global privilege that applies to all records. The manageAnyDatabase privilege is a global privilege that applies to all databases.
  • The action returns the following error if the "objectName" property is included in a global privilege's object definition: "Privilege PPP is a global privilege. You must remove the \"objectName\" property from its definition."

An object-scoped privilege applies to a named object. 

  • For example, a describeOneTable privilege applies to a named table. It cannot apply to other types of objects.
  • If a privilege has the word "One" in it, it is an object privilege.
  • In a privilege object, you can use the "objectName" property to assign a named object to a privilege, such as 
  • { "privilege": "manageOneTable", "objectName": "t1" }.
  • Object-scoped privileges require you to specify named objects and these objects must match the type required by the privilege, such as  
  • { "privilege": "alterOneTable", "objectName": "my_table" }.
    • The action returns the following error if the "objectName" property is omitted on an object-scoped privilege: "You must include the \"objectName\" property for privilege PPP in the [permissions, denyShallow, denyRecursive, or remove] section."
    • The action returns the following error if no objects are specified on an object privilege: "You must assign an object to the \"objectName\" property for privilege PPP in the [permissions, denyShallow, denyRecursive, or remove] section."
  • Each specified object must be the type required by the privilege.
    • The action returns the following error if one or more specified objects are the wrong type for privilege: "Objects OOO, OOO, OOO… are the wrong type for privilege PPP in the [permissions, denyShallow, denyRecursive, or remove] section."

 

How to use "databaseName", "namespace" and their defaults

Because most object names have a three-part name that includes the object's database and namespace, the action provides the following properties to specify them:

  • "defaultDatabaseName"
  • "defaultNamespace"
  • "databaseName"
  • "namespace"

The "defaultDatabaseName" and "defaultNamespace" properties apply to all privileges by default.

Privileges ignore the "defaultDatabaseName" and "defaultNamespace" properties when they do not need a named database or namespace, such as:

{ "privilege": "readAnyRecordInAnyTableInAnyDatabase" }

You can override them by supplying "databaseName" and "namespace" properties in each privilege object.

Examples:

The following privilege object uses the default database name.

{ "privilege": "manageOneDatabase" }

The following privilege object uses the "databaseName" property to assign  "db47" to the "manageOneDatabase" privilege. The "databaseName"  property overrides the default database name.

{ "privilege": "manageOneDatabase", "databaseName": "db47" }

The following privilege uses "objectName" to assign a database to the privilege. The "objectName"  property overrides the default database name.

{ "privilege": "manageOneDatabase", "objectName": "db1" }

The following privilege object uses the "databaseName" and "namespace" properties to override the default database name and namespace properties.

{ "privilege": "describeOneTable", "objectName": "t1", "databaseName": "d3", "namespace": "n5" }

The following privilege object uses the value of the action's "roleName" property to assign a role to the "manageOneRole" privilege.

{ "privilege": "manageOneRole" }

The following privilege object uses "objectName" to assign one or more roles to the privilege. The "objectName"  property overrides the "roleName" property.

{ "privilege": "manageOneRole", "objectName": "role99" }

 

Request examples

Typical

{
  "action": "linkRoleWithPrivileges",
  "params": {
    "roleName": "role2",
    "defaultDatabaseName": "faircom",
    "defaultNamespace": "admin",
    "resetPrivileges": true,
    "permissions": [
      {
        "privilege": "readAnyRecordInAnyTableInAnyDatabase"
      },
      {
        "privilege": "describeOneTable",
        "objectName": "athlete"
      }
    ],
    "shallowDenials": [
      {
        "privilege": "manageAnyServer"
      },
      {
        "privilege": "manageAnyDatabase"
      },
      {
        "privilege": "manageAnyTableInAnyDatabase"
      },
      {
        "privilege": "manageAnyExternalBrokerConnection"
      }
    ],
    "recursiveDenials": [
      {
        "privilege": "manageTheSecurityOfAnyServer"
      },
      {
        "privilege": "manageOneDatabase"
      }
    ],
    "removals": [
      {
        "privilege": "listAnyCodePackageInAnyDatabase"
      }
    ]
  },
  "authToken": "",
  "requestId": ""
}
 
 

Remove all privileges

{
  "action": "linkRoleWithPrivileges",
  "params": {
    "roleName": "role2",
    "resetPrivileges": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Remove select privileges

{
  "action": "linkRoleWithPrivileges",
  "params": {
    "roleName": "readOnlyOperator",
    "defaultDatabaseName": "db1",
    "defaultNamespace": "app1",
    
    "removals": [
      { "privilege": "listAnyCodePackageInAnyDatabase" },
      { "privilege": "manageOneDatabase", "objectName": "my_database" }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Permit privileges

{
  "action": "linkRoleWithPrivileges",
  "params": {
    "roleName": "role2",
    "defaultDatabaseName": "faircom",
    "defaultNamespace": "admin",
    "resetPrivileges": true,
    "permissions": [
      {
        "privilege": "readAnyRecordInAnyTableInAnyDatabase"
      },
      {
        "privilege": "describeOneTable", "objectName": "athlete"
      }
    ]
  },

  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Typical

{
  "authToken": "",
  "result": {
    "permissions": [
      {
        "privilege": "readAnyRecordInAnyTableInAnyDatabase"
      },
      {
        "privilege": "describeOneTable",
        "objectName": "athlete"
      }
    ],
    "removals": [
      {
        "privilege": "listAnyCodePackageInAnyDatabase"
      }
    ],
    "recursiveDenials": [
      {
        "privilege": "manageTheSecurityOfAnyServer"
      },
      {
        "privilege": "manageOneDatabase"
      }
    ],
    "shallowDenials": [
      {
        "privilege": "manageAnyServer"
      },
      {
        "privilege": "manageAnyDatabase"
      },
      {
        "privilege": "manageAnyTableInAnyDatabase"
      },
      {
        "privilege": "manageAnyExternalBrokerConnection"
      }
    ],
    "resetPrivileges": true,
    "roleName": "role2"
  },
  "requestId": "",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Remove all privileges

{
  "authToken": "",
  "result": {
    "resetPrivileges": true,
    "roleName": "role2"
  },
  "requestId": "",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Remove select privileges

{
  "authToken": "",
  "result": {
    "removals": [
      {
        "privilege": "listAnyCodePackageInAnyDatabase"
      },
      {
        "privilege": "manageOneDatabase",
        "objectName": "faircom"
      }
    ],
    "roleName": "role2"
  },
  "requestId": "",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Permit privileges

{
  "authToken": "",
  "result": {
    "permissions": [
      {
        "privilege": "readAnyRecordInAnyTableInAnyDatabase"
      },
      {
        "privilege": "describeOneTable",
        "objectName": "athlete"
      }
    ],
    "resetPrivileges": true,
    "roleName": "role2"
  },
  "requestId": "",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

defaultDatabaseName

The "defaultDatabaseName" property contains the name of an existing database for the server to use when the "databaseName" property is required but omitted. 

FairCom DB defaults to "ctreeSQL"

FairCom Edge defaults to "faircom"

FairCom MQ defaults to "faircom"

string 1 to 64 bytes

defaultNamespace

The "defaultNamespace" property contains the name of an existing namespace for the server to use when the "namespace" property is required but omitted.  Optional with default of "" string 1 to 64 bytes

permissions

The "permissions" property specifies which permissions to assign to a role. Optional with default of [] array of objects One or more privilege objects. This applies to permissions, shallow, recursive, and removals as well. 

permissions

.databaseName

The "databaseName" property specifies the database that contains an object.  Required when a privilege contains the word "one" and specifies an object in a database string 1 to 64 bytes

permissions

.namespace

The "namespace" property specifies the name of an existing namespace.  Required when a privilege contains the word "one" and specifies the object type as "table", "codepackage", "procedure", "sequence", "synonym", or "view". string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

permissions

.objectName

The "objectName" property is the name of an object, such as a table name.  Required when a privilege contains the word "one" and specifies the object type as "server", "database", "table", "record", "codepackage", "view", "procedure", "mqsession", "mqtopic", "brokerconnection", "connector", "account", or "role". string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

permissions

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  Required - No default value string 1 to 64 bytes

shallowDenials

The "shallowDenials" property denies a role from having the specified privileges but does not deny the descendants of those privileges. For example, you could deny a role from managing a server while permitting the role to manage one of its databases. Optional with default of [] array of objects 0 or more privilege objects

shallowDenials

.databaseName

The "databaseName" property specifies the database that contains an object.  Required when a privilege contains the word "one" and specifies an object in a database string 1 to 64 bytes

shallowDenials

.namespace

The "namespace" property specifies the name of an existing namespace.  Required when a privilege contains the word "one" and specifies the object type as "table", "codepackage", "procedure", "sequence", "synonym", or "view". string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

shallowDenials

.objectName

The "objectName" property is the name of an object, such as a table name.  Required when a privilege contains the word "one" and specifies the object type as "server", "database", "table", "record", "codepackage", "view", "procedure", "mqsession", "mqtopic", "brokerconnection", "connector", "account", or "role". string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

shallowDenials

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  Required - No default value string 1 to 64 bytes

recursiveDenials

The "recursiveDenials" property denies a role from having the specified privileges and their descendants. For example, if you deny a role from managing a server, it also denies all its descendant privileges which includes all non-security privileges. 

Note Only privileges with "manage" in their name have descendants. Because of this, "recursiveDenials" is different from "shallowDenials" only for "manage" privileges.

Optional with default of [] array of objects 0 or more privilege objects

recursiveDenials

.databaseName

The "databaseName" property specifies the database that contains an object.  Required when a privilege contains the word "one" and specifies an object in a database string 1 to 64 bytes

recursiveDenials

.namespace

The "namespace" property specifies the name of an existing namespace.  Required when a privilege contains the word "one" and specifies the object type as "table", "codepackage", "procedure", "sequence", "synonym", or "view". string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

recursiveDenials

.objectName

The "objectName" property is the name of an object, such as a table name.  Required when a privilege contains the word "one" and specifies the object type as "server", "database", "table", "record", "codepackage", "view", "procedure", "mqsession", "mqtopic", "brokerconnection", "connector", "account", or "role". string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

recursiveDenials

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  Required - No default value string 1 to 64 bytes

removals

The "removals" privilege lists the privileges to be removed from the specified roles.  Optional with default of [] array of objects 0 or more privilege objects

removals

.databaseName

The "databaseName" property specifies the database that contains an object.  Required when a privilege contains the word "one" and specifies an object in a database string 1 to 64 bytes

removals

.namespace

The "namespace" property specifies the name of an existing namespace.  Required when a privilege contains the word "one" and specifies the object type as "table", "codepackage", "procedure", "sequence", "synonym", or "view". string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

removals

.objectName

The "objectName" property is the name of an object, such as a table name.  Required when a privilege contains the word "one" and specifies the object type as "server", "database", "table", "record", "codepackage", "view", "procedure", "mqsession", "mqtopic", "brokerconnection", "connector", "account", or "role". string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

removals

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  Required - No default value string 1 to 64 bytes

resetPrivileges

The "resetPrivileges" property removes all existing privileges before applying new ones when set to true. Optional with default of false Boolean

true

false

roleName

The "roleName" property specifies the name of the role to which privileges and restrictions are being assigned.  Required - No default value string 1 to 30 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

defaultDatabaseName

The "defaultDatabaseName" property contains the name of an existing database for the server to use when the "databaseName" property is required but omitted.  string 1 to 64 bytes

defaultNamespace

The "defaultNamespace" property contains the name of an existing namespace for the server to use when the "namespace" property is required but omitted.  string 1 to 64 bytes

permissions

The "permissions" property specifies which permissions to assign to a role. array of objects

"objectName"

"privilege"

permissions

.databaseName

The "databaseName" property specifies the database that contains an object.  string 1 to 64 bytes

permissions

.namespace

The "namespace" property specifies the name of an existing namespace.  string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

permissions

.objectName

The "objectName" property is the name of an object, such as a table name.  string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

permissions

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  string 1 to 64 bytes

shallowDenials

The "shallowDenials" property denies a role from having the specified privileges but does not deny the descendants of those privileges. For example, you could deny a role from managing a server while permitting the role to manage one of its databases. array of objects 0 or more privilege objects

shallowDenials

.databaseName

The "databaseName" property specifies the database that contains an object.  string 1 to 64 bytes

shallowDenials

.namespace

The "namespace" property specifies the name of an existing namespace.  string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

shallowDenials

.objectName

The "objectName" property is the name of an object, such as a table name.  string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

shallowDenials

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  string 1 to 64 bytes

recursiveDenials

The "recursiveDenials" property denies a role from having the specified privileges and their descendants. For example, if you deny a role from managing a server, it also denies all its descendant privileges which includes all non-security privileges. 

Note Only privileges with "manage" in their name have descendants. Because of this, "recursiveDenials" is different from "shallowDenials" only for "manage" privileges.

array of objects 0 or more privilege objects

recursiveDenials

.databaseName

The "databaseName" property specifies the database that contains an object.  string 1 to 64 bytes

recursiveDenials

.namespace

The "namespace" property specifies the name of an existing namespace.  string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

recursiveDenials

.objectName

The "objectName" property is the name of an object, such as a table name.  string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

recursiveDenials

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  string 1 to 64 bytes

removals

The "removals" privilege lists the privileges to be removed from the specified roles.  array of objects 0 or more privilege objects

removals

.databaseName

The "databaseName" property specifies the database that contains an object.  string 1 to 64 bytes

removals

.namespace

The "namespace" property specifies the name of an existing namespace.  string Matches the limits of the object type specified by the privilege. 1 to 64 bytes

removals

.objectName

The "objectName" property is the name of an object, such as a table name.  string Matches the limits of the object type specified by the privilege. 1 to 65,500 bytes

removals

.privilege

The "privilege" property specifies one of FairCom's predefined privilege names.  string 1 to 64 bytes

resetPrivileges

The "resetPrivileges" property removes all existing privileges before applying new ones when set to true. Boolean

true

false

roleName

The "roleName" property specifies the name of the role to which privileges and restrictions are being assigned.  string 1 to 30 bytes