This document contains an overview of the authentication and authorization configuration process, and contains the following sections:

Authentication and authorization terminology

The following table lists the terms used to describe the Akula authentication and authorization mechanism:

Authentication

Authentication determines a user's identity, typically through credentials passed to the realm. Credentials consist of a principal/secret pair, such as a username/password.

The Akula Server lets you connect to a realm, such as an Active Directory server, that maintains these credentials. You then use the Akula client APIs for Android, iOS, and JavaScript to log in and log out a user, where the user's credentials are validated against the realm.

Authentication configuration

Perform the following steps to configure authentication for a realm such as Active Directory:

1. Define a security manager to configure a connection from the Akula Server to the realm, such as an Active Directory server. The realm maintains the user credentials, which for Active Directory are a username and password.
   
   The realm also maintains user groups, which are collections of one or more users. All authorization to Akula Server endpoints controlled by the Akula Server is based on groups, not on individual users.
   
   
2. From within your client app, authenticate the user on a specific app scope by using the appropriate client API for the devices (Android, iOS, JavaScript).
   
   To authenticate a user, the client app calls the login method on the app scope, passing to the method the user's credentials. If the credentials are valid, the Akula Server returns a session token as a UUID value and a log-in timeout value in milliseconds. The session token is then passed on subsequent requests to identify the user. The timeout is refreshed on every request.
   
   After a user successfully logs in, they can then perform any authorized actions against the endpoints managed by the app scope.
   

   To end an authentication session, the app calls the logout method on the app scope. Log out can be triggered by a direct user action, occur automatically after a timeout period expires, or for other reasons.

For more information, see Authenticating Users.

Authorization

Authorization determines if a user is allowed to perform an action on an endpoint managed by an app scope. For example, if the endpoint corresponds to a data source, the user might only be authorized to read data from the data source but might not be allowed to write data to it.

Authorization to perform an action on an endpoint is determined by the user's role, and the permissions associated with that role.

Authorization configuration

The process of configuring authorization requires that you edit files on the Akula Server to define permissions and endpoints, and then use the Akula Command-line Management Utility or REST APIs to associate permissions and groups with roles. The following steps provide an overview of this process:

1. Define the set of permissions.

   A permission defines an allowed action. For example, permissions can allow create, read, update and delete actions. You define permissions in the permissions.xml file either at the Akula Server level or in an individual AKZ file for an app scope.
   
   

2. Associate permissions with an endpoint controlled by the app scope.
   
   When you define an endpoint controlled by the app scope, you also associate permissions with the endpoint. The permissions specify the actions permitted on the endpoint.
   
   An endpoint might support multiple actions. For example, an endpoint that corresponds to a data source might support read, write, update, and delete actions. For each action, you can associate one or more permissions. Only users with the correct permission can perform the corresponding action on the endpoint. For example, one user could have read permission on the endpoint, while another has read and delete permission.
   
   For information on defining an endpoint, see Using Endpoints.
   
   

3. Create roles on the Akula Server.
   
   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.
   
   
4. Associate permissions with roles.
   
   Use the Akula Command-line Management Utility or REST API to associate permissions with roles. This association determines the actions that the role is allowed to perform.
   
   
5. Associate groups with roles.
   
   Use the Akula Command-line Management Utility or REST API to associate groups with roles. This association determines the users assigned to the role and, therefore, the actions that the user is allowed to perform.

For more information, see Authorizing Users.

Access rights required to configure authorization

To configure authorization, you use XML files in an app scope to define endpoints and permissions, and the REST API or the Akula Command-line Management Utility to define roles.

Anyone with file access to the Akula Server can edit the XML files that define permissions and endpoints. However, modifying the permissions.xml file for the Akula Server requires a restart of the Akula Server, and modifying the permissions.xml file for a AKZ file requires that you redeploy the AKZ file.

As part of managing roles, you use the REST API or the Akula Command-line Management Utility to:

• Create roles
• Delete roles
• Assign groups to roles and remove groups from roles
• Assign permissions to roles and remove permissions from roles
• Perform other actions

Typically, you limit the ability to create and modify roles to users who are also Akula Server administrators. You define administrators when you first install and configure the Akula Server. For more information, see Define Akula Server Administrators.