Permissions

Permissions determine what a user can do in Fusion. There are two kinds of permissions:

  • UI permissions – Control which parts of the Fusion UI a user can access. These parts show up in menus and the user can view them. But the ability to use the functionality depends on API permissions.

  • API permissions – Control which requests a user can submit to which REST API endpoints.

Permissions can be defined by either a role or a user, or both. Fusion combines permissions for authorization as follows:

  • UI permissions are positive (permission needs to be given) and additive (the user has the sum of all specified permissions. This is true of roles specified in a user definition, roles specified in a security realm, and roles determined dynamically based on groups in an LDAP authentication provider.

  • API permissions specified in roles are positive (permission needs to be given) and additive (the user has the sum of all specified permissions; that is, for a specific endpoint, the most permissive permissions are used). This is true of roles specified in a user definition, roles specified in a security realm, and roles determined dynamically based on groups in an LDAP authentication provider.

  • API permissions specified in the role(s) but not in the user definition are used.

  • If an API permission for a specific endpoint is specified in both a role and in the user definition, then the permissions in the user definition are used, overriding the permissions in the role(s). Use permissions in user definitions to give specific users permissions that are less permissive than the permissions for their role(s).

    For example, say role A allows GET and POST access to a specific endpoint. User X is a member of role A and also has a user definition that allows only GET access to that endpoint. In this case, user X has only GET access to that specific endpoint.

    Alternatively, you could define less permissive roles.

Specify UI Permissions

Specify UI permissions in roles.

Specify API Permissions

A Fusion API permission denotes an allowed request to a Fusion REST API endpoint or endpoints. A permissions specification consists of:

  • HTTP request method or methods allowed. Multiple HTTP methods are separated by commas.

  • REST API services endpoint, which can contain wildcards or named variables. All calls to the REST API start with "api/apollo", followed by the service name and any methods and parameters. The permissions specification includes everything following api/apollo. The endpoint can include wildcards.

    Wildcards make it easy to grant broad access to Fusion services. The wildcard symbol * matches all possible values for a single path segment. Two wildcards match all possible values for any number of path segments. Granting access to a subset of Fusion functionality can require a list of narrowly defined permissions. Carefully defining each Fusion app to address a specific use case can simplify permission sets, by letting you grant access liberally within a single app.

    A path segment can be a named variable enclosed in curly braces: {variable-name}. Variables are used when a wildcard would be too permissive and a single path segment too restrictive.

  • Optionally, the allowed values for any named variables in the endpoint. The variable specification component specifies the restricted value or values for all named variables in the path. Each specification consists of the variable name, followed by "=" (the equals sign), followed by one or more values separated by commas. If the endpoint specification has multiple variable, the semi-colon character ";" is used as the separator between parameter specifications.

A permission specification has three elements: methods, path, and parameters. A permissions specification is written as a string using the colon character ":" as the separator between the elements. The lists of permission specifications are stored in the ZooKeeper User and Roles entries in JSON format.

Example Permission Sets

Admin permissions

The permissions for the admin user can be written in a single line:

GET,POST,PUT,DELETE,PATCH,HEAD:/**

This permission specification uses two wildcards. One wildcard specifies any path segment, and the other specifies any value.

Best practice: Delegate access to a Fusion app

When possible, create a Fusion app for a specific use case and assign permissions on a per-app basis. For example, to configure a Fusion account to be able to run queries against only a certain collection:

  1. Create a Fusion app.

  2. Create a query profile by defining a collection. This lets you change the underlying collection without having to redo permissions.

  3. Assign permissions as follows:

GET:/apps/<myapp>/query/<myprofile>/*

The above permission set allows a user to run queries against the collection specified by <myprofile> under the Fusion app <myapp>.