Grant ​

A Grant specifies the permissions assigned to a user, group, or role over a particular resource. It is essentially a directive that determines what actions can be performed by which entities on specific resources. This object helps enforce access control policies by defining who can access what and in what manner.

Description ​

The Grant object serves to manage and enforce permissions within an RBAC system. It allows administrators to specify which roles or users have the authority to perform particular actions on resources.

It is an essential element in RBAC systems for defining and managing permissions, ensuring that access to resources is controlled, and aligning with organizational security policies.

Types ​

grant() ​

The object used to create a new grant. The representation of the grant is also returned by the read operations.

The object represents as overview of the all grant properties but the available properties are detailed in each particular operation.

Actions ​

Below the actions (WAMP Permissions) which can be configured on the resources:

• wamp.register
• wamp.unregister
• wamp.call
• wamp.cancel
• wamp.subscribe
• wamp.unsubscribe
• wamp.publish
• wamp.disclose_caller
• wamp.disclose_publisher

Procedures ​

These procedures facilitate the management of permissions in an RBAC system by allowing administrators to create, revoke, and review access rights for users, groups, and roles.

• Granting permissions (role, resource, permission): creates a grant to allow the specified role to access the specified resource with the given permission.
• Revoking permissions (role, resource, permission): removes a grant that allows the specified role to access the specified resource with the given permission.
• Listing permissions (realm|role): retrieves a list of permissions granted to the specified role (user or group) or even to the realm.

Create a new grant ​

bondy.grant.create(realm_uri(), input_data()) -> grant() ​

This procedure is used to create a new grant, which assigns specific permissions to a user, group, or role for a particular resource. By invoking bondy.grant.create, administrators can specify who (the principal) is being granted access, what resources they can access, and what actions they are permitted to perform.

It creates a new grant and add it on the given realm uri.

Use cases:

• grant permissions on any to all | {user | group [,...]}
• grant permissions on {resource, exact | prefix | wildcard} to all | {user | group [,...]}

Positional Args ​

Keyword Args ​

None.

Result ​

Positional Results ​

None

Keyword Results ​

None.

Errors ​

• wamp.error.no_such_realm: when the given realm uri does not exist.
• bondy.error.unknown_roles: when the given roles do not exist.
• bondy.error.invalid_data: when there validation failures on the given data.

Examples ​

session.call("bondy.grant.create", [
   "com.leapsight.test",
   {
        "permissions": [
            "wamp.subscribe",
            "wamp.unsubscribe",
            "wamp.call",
            "wamp.cancel"
        ],
        "resources": [
            {
                "uri": "com.leapsight.example.",
                "match": "prefix"
            },
            {
                "uri": "com.leapsight.test.echo",
                "match": "exact"
            }
        ],
        "roles": [
            "client"
        ]
    }
])

./wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.grant.create \
"com.leapsight.test" \
'{
    "permissions": [
        "wamp.subscribe",
        "wamp.unsubscribe",
        "wamp.call",
        "wamp.cancel"
    ],
    "resources": [
        {
            "uri": "com.leapsight.example.",
            "match": "prefix"
        },
        {
            "uri": "com.leapsight.test.echo",
            "match": "exact"
        }
    ],
    "roles": [
        "client"
    ]
}' | jq

Revoke an existing grant ​

bondy.grant.revoke(realm_uri(), input_data()) -> grant() ​

This procedure is used to remove an existing grant. When bondy.grant.revoke is called, it removes the permissions previously granted to a user, group, or role for a specific resource. This helps in managing and adjusting access control by revoking rights that are no longer needed or are being altered.

Positional Args ​

Keyword Args ​

None.

Result ​

Positional Results ​

None

Keyword Results ​

None.

Errors ​

• wamp.error.no_such_realm: when the given realm uri does not exist.
• bondy.error.unknown_roles: when the given roles do not exist.
• bondy.error.invalid_data: when there validation failures on the given data.

Examples ​

session.call("bondy.grant.revoke", [
   "com.leapsight.test",
   {
        "permissions": [
            "wamp.subscribe",
            "wamp.unsubscribe"
        ],
        "resources": [
            {
                "uri": "com.leapsight.example.",
                "match": "prefix"
            }
        ],
        "roles": [
            "client"
        ]
    }
])

./wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.grant.revoke \
"com.leapsight.test" \
'{
    "permissions": [
        "wamp.subscribe",
        "wamp.unsubscribe"
    ],
    "resources": [
        {
            "uri": "com.leapsight.example.",
            "match": "prefix"
        }
    ],
    "roles": [
        "client"
    ]
}' | jq

List grants of the realm ​

bondy.realm.grants(realm_uri()) -> [grant()] ​

This procedure retrieves the list of grants applied at the realm level. It provides a comprehensive view of all permissions that are granted within a particular realm, which can include various users, groups, and roles along with their associated permissions on resources.

Positional Args ​

Keyword Args ​

None.

Result ​

Positional Results ​

The call result is a single positional argument containing a list of grants.

Keyword Results ​

None.

Errors ​

• bondy.error.not_found: when the given realm uri does not exist.

Examples ​

session.call("bondy.realm.grants", ["com.leapsight.test"])

./wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.realm.grants \
"com.leapsight.test" | jq

[
  [
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel"
      ],
      "resources": {
        "match": "prefix",
        "uri": "com.leapsight.example."
      },
      "roles": [
        "client"
      ]
    },
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "exact",
        "uri": "com.leapsight.test.echo"
      },
      "roles": [
        "client"
      ]
    },
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "prefix",
        "uri": "com.leapsight.example."
      },
      "roles": [
        "clients"
      ]
    },
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "exact",
        "uri": "com.leapsight.test.echo"
      },
      "roles": [
        "clients"
      ]
    }
  ]
]

List grants of the group ​

bondy.group.grants(realm_uri(), group_name()) -> [grant()] ​

This procedure is used to fetch the grants associated with a specific group. It shows the permissions that have been assigned to the group across various resources, helping administrators understand what access rights are available to the group members.

Positional Args ​

Keyword Args ​

None.

Result ​

Positional Results ​

The call result is a single positional argument containing a list of grants. An empty list is returned when the provided group doesn't exist.

Keyword Results ​

None.

Errors ​

• bondy.error.not_found: when the given realm uri does not exist.

Examples ​

session.call("bondy.group.grants", ["com.leapsight.test", "client"])

./wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.group.grants \
"com.leapsight.test" "client" | jq

[
  [
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "exact",
        "uri": "com.leapsight.test.echo"
      }
    },
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel"
      ],
      "resources": {
        "match": "prefix",
        "uri": "com.leapsight.example."
      }
    }
  ]
]

List grants of the user ​

bondy.user.grants(realm_uri(), username()) -> [grant()] ​

This procedure retrieves the grants associated with a specific user. It provides information on what permissions the user has been granted across different resources, allowing administrators to review and manage individual user access effectively.

Positional Args ​

Keyword Args ​

None.

Result ​

Positional Results ​

The call result is a single positional argument containing a list of grants. An empty list is returned when the provided user doesn't exist.

Keyword Results ​

None.

Errors ​

• bondy.error.not_found: when the given realm uri does not exist.

Examples ​

session.call("bondy.user.grants", ["com.leapsight.test", "john.doe"])

./wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.user.grants \
"com.leapsight.test" "john.doe" | jq

[
  [
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "exact",
        "uri": "com.leapsight.test.echo"
      }
    },
    {
      "permissions": [
        "wamp.call",
        "wamp.cancel",
        "wamp.subscribe",
        "wamp.unsubscribe"
      ],
      "resources": {
        "match": "prefix",
        "uri": "com.leapsight.example."
      }
    }
  ]
]