Authorization determines if a user is allowed to perform an action on a resource, where the resource corresponds to an endpoint controlled by an app scope running on the Akula Server. Authorization to perform an action on a resource is determined by the role that the user is a member of, the permissions that the role is granted, and the resource that the user is trying to access.
This document contains the following sections:
The following image shows the relationship of roles and endpoints:
In Akula, authorization is role based, where a role is associated with one or more groups and one or more permissions. Therefore, all users in a group have all of the permissions associated with the role.
An endpoint corresponds to a resource controlled by the Akula Server and consists of a URL paired with an HTTP access method, such as GET, PUT, POST, or DELETE. When you define an endpoint as part of creating an Akula app scope, you associate permissions with the endpoint. That association specifies the permissions that a user must have to access the endpoint.
For example, shown below is an example endpoint definition that you access by using the HTTP GET method:
<url> attribute defines the URL of the endpoint. In this example, the endpoint URL is
http://server_name/akula/app_scope/data/url_value. For example,
<permissions> attribute of the endpoint specifies the permissions that a user must have to access the endpoint.
For a user to be authorized to access the endpoint, they must be a member of a group that is associated with a role that has permissions that match the endpoint permissions. In this example, the role must therefore be associated with the Marketing.readAccount or Sales.readAccount permission.
For more information about defining endpoints, see Using Endpoints.
Setting Permissions on an Endpoint
A resource is an entity whose access is controlled by an app scope on the Akula Server. Typically, a resource corresponds to an endpoint defined by the app scope. Use the endpoint to access a data source, to perform user authentication, and to set properties on the Akula Server.
If a user has the proper permission, the user can perform actions on an endpoint. This section describes how to create permissions and associate those permissions with an endpoint.
Define permissions in a permissions.xml file. The permissions.xml file is located in the /AKZ-INF/config/scope directory under the root directory of an AKZ file, which means that permissions are specific to a Akula app scope. Editing this file requires you to redeploy the AKZ file and restart the Akula Server.
Use the following tags in the permissions.xml file to define permissions:
|Defines one or more action sets.|
|Defines an action set. An action set is one or more actions.|
|Defines an action that is part of an action set. The name of the action can be descriptive, such as read or write. However, there is no restriction on the name of an action.|
|Defines a set of one or more permissions.|
|Defines a permission and associated action set. The action set determines the list of actions allowed by the permission.|
Shown below is an example permissions file:
An action set is a collection of actions that a user can perform on an endpoint. In this example, you define two action sets: readOnly and readWrite.
You then create two resources from the two action sets. In this example, the Marketing resource has permission for only a read action, while the Sales resource is allowed all read/write actions.
An individual permission is made up of a noun, corresponding to the resource, and a verb, corresponding to an action. From the example above, you define five individual permissions:
Note that the names of an action are not reserved. That is, you can use any names for an action. It is by associating the permission with an endpoint that you control access to the endpoint. For example, you could have rewritten this permissions.xml file as below:
One advantage of action sets is that you can use the same action set to configure multiple resources, as shown below:
Associating permissions with an endpoint
After defining the permissions in permissions.xml, you associate the permissions with an endpoint controlled by the app scope. Endpoints are defined in an XML file in the
/api folder of your app scope. For more information, see Using Endpoints.
In the previous section, you defined five permissions:
As part of defining the endpoint, you associate these permissions with
<permission> tags in the endpoint definition, as the following example shows:
In this example, a user must have the Marketing.readAccount or Sales.readAccount permission to make a GET request on the /Tasks URL. To make a POST request, the user must have the Sales.addAccount permission.
You now have defined the permissions that a user must have to perform an action on an endpoint. The final step is to associate the permissions and user groups with a role, as described below.
Associating Permissions and Groups with Roles
Roles let you control the actions that a user can perform on an endpoint. For example, a user might want to perform a read action on an endpoint, where the endpoint corresponds to a data source of sales data. The user must therefore be in a role that has permission to perform a read action on the endpoint.
Tools for working with roles
To configure roles, you can use the Akula Command-line Management Utility, or make HTTP request to the Akula Server through its REST endpoints. For more information on the Akula Command-line, see Using the Akula Server Management Tool. For more information on the REST endpoints, see Using the REST API.
Creating and Configuring a role
By default, an app scope has no roles. Therefore, your first action is to create the roles required by your app scope.
To create a role:
- Use the Akula Command-line to create the role, or make an HTTP request to the appropriate server REST endpoint to create a role for a specific app scope.
To configure a role, associate two entities with the role:
Associate groups from your realm with a role. Groups define the users associated with the role. All users in a group associated with a role have the access rights of the role. You can associate multiple groups with a single role.
Groups are defined in a realm, such as an Active Directory server, not on the Akula Server.
Associate the same permissions, from permissions.xml, with a role that you used when defining an endpoint. That is, you associate permissions with endpoints, and associate those same permissions with roles. When a user attempts to perform an action on an endpoint, the Akula Server checks to make sure that the permissions associated with the role match the permissions associated with the endpoint. If the permissions match, then the user is allowed to perform the action.
You can associate multiple permissions with a role. All users in a role have all the permissions associated with the role.
Role naming rules
Role names have the following naming conventions:
- Minimum of one character and a maximum of 255 characters in length
- Case sensitive
- Leading space characters and space characters in the name are allowed, but trailing spaces are truncated
- Special characters allowed but are typically limited to UTF-16 characters
Each role name is defined for a specific app scope. However, different app scopes can define the same role name. Therefore, full name of a role includes the name of its associated app scope. For example, the role of "Sales Agent" in the app scope "Inside Sales" is different from the role of "Sales Agent" in the app scope "External Sales".
Example: creating a role
addrole command in the Akula Command-line to add a role to an app scope, as shown below:
Where myServerApp is the app scope and myRole is the name of the role.
After you create the role, you can use the
roles command in the Akula Command-line to see it:
Notice that the Permissions and Group fields of the role are empty.
Alternatively, use the roles REST API to create a role on a specific app scope. To create a role, you make a PUT request to the following URL:
where myServerApp is the name of the app scope on which you create the role.
As part of the request you pass the session token returned from a valid log in. You must pass an session token to ensure that the user performing this request is authorized to create a role. For more information on authentication, see Authenticating Users.
Example: Associating groups and permission with a role
addgroups command in the Akula Command-line to associate a group with a role. The name of the group is the unique ID of the group. For example, if you are using Active Directory as your realm, it is a string in the form:
CN=Group Policy Creator Owners,CN=Users,DC=vvod,DC=com
The following example associates a group with the role. Because groups are defined in a realm, you must have already configured a connection between the Akula Server and a realm before you can associate a group with a role. For more information, see Using Active Directory Server as an Authentication Realm.
The realm name in this example is MyAD, as shown below:
addpermission command to add a permission to the role, as the following example shows:
After you associate the group and permission with the role, you can use the
roles command in the Akula Command-line to see it:
Alternatively, use the roles REST API to associate a user group and a permission with a role. This is actually a two-step process. In the first step, you make a POST request to associate the group with the role. In the second step, you make a POST request to associate the permission with the group.To associate a group with a role, you make a PUT request to the following URL:
- myServerApp is the name of the app scope on which you create the role
- myRole is an existing role on myServerApp
- myAD is the name of the realm containing the group
To associate a permission with a role, you make a PUT request to the following URL:
- myServerApp is the name of the app scope
- myRole is an existing role on myServerApp