Documentation 3.0 Beta
Authentication and Authorization Overview
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:
|User||An individual that can be authenticated by the Akula Server.||Realm|
|Group||A collection of users, where users can be in multiple groups. For example, you can define groups called Managers, Employees, and Customers.||Realm|
|Realm||A collection of users and groups, maintained outside of the Akula Server. For example, you can use Active Directory as your realm.||Authentication backend|
|Principal/secret||The credentials used to authenticate the user against the realm. One example of a principal/secret pair is a username/password, but you can specify any information required by the realm.||Realm|
|Security manager||Contains the configuration information for a realm, as well as session caching and session timeout information.||Akula Server|
|App scope||A server-side app running on the Akula Server. The name of the app scope name is the name of the AKZ file that represents the app scope. Every app scope requires a security manager.||AKZ file|
|Endpoint||A URL paired with an HTTP access method, such as GET, PUT, POST, or DELETE.||App scope|
|Resource||An entity, such as a data source, whose access is controlled by an app scope. 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.||App scope|
|Action||An operation that can be performed against an endpoint. Examples of actions for an endpoint that corresponds to a data source include create, read, update, and delete. Examples of actions for an endpoint that manages users include log in and log out.||App scope|
|Permission||An allowed action. For example, one permission could allow a read action, while another allows a delete action. Note that a permission simply defines an allowed action but it does not define who can perform the action.||App scope|
|Role||An association of groups and permissions that defines the actions that a user is allowed to perform.||App scope|
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.
Perform the following steps to configure authentication for a realm such as Active Directory:
- 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.
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 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.
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:
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.
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.
- 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.
- 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.
- 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.