Documentation

Authentication determines a user's identity. To authenticate a user, the client app calls the log in method, passing to the method the user's credentials as a principal/secret pair. The contents of the principal/secret pair are determined by your authentication realm. For example, many realms use strings containing a username/password pair as the credentials. To support the many different types of possible realms, the Android and JavaScript SDKs represent the principal/secret pair as JSON objects. The iOS SDK uses an NSDictionary object.

The log in method passes the credentials to an app scope running on the Akula Server for validation against an authentication realm, such as an Active Directory server. For an Active Directory realm, the user credentials consist of string values containing a username and password.

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

This document describes the user authentication mechanism, and contains the following sections:

Authentication mechanism

The Akula Server requires the client to pass authentication credentials as a principal/secret pair. If the credentials are valid, the Akula Server returns a session token as a UUID value, a log-in timeout value in milliseconds, and optionally other information about the user. The session token is then passed on subsequent requests to identify the user. The timeout is refreshed on every request.

Authentication can fail for several reasons, including:

  • Invalid user credentials
  • Locked or expired credentials
  • Server timeout

When authentication fails, the Akula Server returns a response object describing the reason for the failure.

Synchronous and asynchronous calls

The Akula Server supports both synchronous and asynchronous requests from Android and iOS client apps. The JavaScript client, however, only supports asynchronous requests. A best practice is to use asynchronous requests from a client app. You should only use synchronous requests when you want to perform your own thread management.

Authentication process in a client app

The general steps for authenticating a user for all clients is:

  1. Log in as a user by calling a log in method of the session class, AKSession for Android and iOS and AK.Session for JavaScript, passing the user's credentials to the app scope. If the credentials are valid, the Akula Server returns a session token, log-in timeout value, and other information about the user and automatically writes that information to AKSession, AKUser, and AKPermissions objects (Android and iOS) and AK.Session, AK.User, and AK.Permissions objects (JavaScript).
  2. If the log in attempt fails, the Akula Server returns a response object that contains error information.
  3. After a successful log in, you can access the endpoints controlled by the app scope by making HTTP GET, PUT, POST, and DELETE requests. Each request passes the session token to identify the user to the app scope.
  4. When the user's session is over, log out the user by calling the log out method of the session object. The log out method deletes the session token on the client and on the Akula Server.

The following image shows this process:

On an online or offline log out, the client performs the following:

  • Deletes the session token
  • Stores the data in the AKSession, AKUser, and AKPermissions objects (Android and iOS) or AK.Session, AK.User, and AK.Permissions objects (JavaScript)
  • Deletes the AKSession, AKUser, and AKPermissions objects (Android and iOS) or the AK.Session, AK.User, and AK.Permissions objects (JavaScript) from memory

If the user then logs in offline, the AKSession, AKUser, and AKPermissions objects or the AK.Session, AK.User, and AK.Permissions objects are restored. If the user logs in online, then new information is downloaded from the Akula Server, and the old values are discarded.

If defined, the Akula Server can also return app properties in the response object for a successful log in. For more information, see Using App Properties

Handling authentication success

On a successful authentication, the Akula Server returns a response object that contains the information in the following table, and writes this information to the AKSession and AKUser objects (Android and iOS) and AK.Session and AK.User objects (JavaScript):

InformationStored inDescription
token

AKSession

AK.Session

A UUID representing the session token. The session token is stored in a property named sessionId (Android and JavaScript) or sessionID (iOS) (note the difference in capitalization).
timeout

AKSession

AK.Session

The authentication timeout, in milliseconds. The default value is 1,800,000 ms, corresponding to 30 minutes. You can configure the timeout value on the Akula Server. For more information, see Defining a Security Manager.
time of last request

AKSession

(Android only) The timestamp of the last request.

id
realm

custom realm information

AKUser

AK.User

The Akula Server response always contains the user's id and the name of the authentication realm.

Any custom information optionally returned by the realm, such as first name, last name, and full name, is stored as key/value pairs. That information is specific to your authentication realm.

permissions

AKPermissions

AK.Permissions

The set of permissions for the user. This is the set of permissions associated with all of the roles that contain the user. For more information on using permissions on the client, see Checking User Permissions on the Client.
app properties

AKAppProperties

AK.AppProperties

Key/value pairs that contain information defined on the Akula Server and returned to the client on a successful log in. For more information on defining and using app properties, see Using App Properties.

The way you access information about the current session and user depends on your client. The following example shows how to access this information from an Android client app:

For an iOS client app:

For a JavaScript client app:

Handling authentication failure

Regardless of whether you use synchronous or asynchronous authentication, the Akula Server returns a response object to describe an authentication failure. In an asynchronous invocation, the response object is passed to the callback method that you specified to handle a failure. For synchronous authentication, you can access the response object in a try/catch block.

For more information, see Handling Exceptions and Errors.

Online and offline authentication

The authentication mechanism works when a device is online or offline. The Android and iOS client apps can detect when a device is online and when the device is offline. The JavaScript client is not able to detect when the device is offline. All offline requests to the Akula Server from the JavaScript client fail after a timeout interval.

Online log in

When you log in online with valid credentials, the Akula Server returns a session token and session timeout value. Online log in also deletes any existing session token and session timeout, if they exist, on the device. 

After successfully logging in when the device is online, you can log out either online or offline.

Online log out

When online, a log out deletes the session token that the client received from the Akula Server and invalidates the session on the Akula Server.

After successfully logging off, you can log in again either online or offline.

Offline log in

If you have previously logged in when online, and logged out either online or offline, then you can log in when the device is offline by using the same credentials that you previously used for the online log in. After a successful offline log in, you can access local resources on the device. You can log out and log in again repeatedly while offline.

No session token or session timeout value is created on the device for an offline log in. When the device goes back online, you must log in again with the Akula Server to receive a valid session token and timeout value before you can access server-side resources.

If you have not successfully logged in to the app while the device is online, and you attempt to log in while offline, then the log in request fails and returns an error.

Offline log out

When offline, a log out deletes the session token that the client received from the Akula Server, if one exists.

There will be no session token to delete if you are logging out after an offline log in.

After an offline log out, you can log in again, either online or offline. For an offline log in, you must use the same credentials as you used for the last successful log in.

When you next attempt to connect to the Akula Server after an offline log out, you are prompted to log in.

Authenticating from a client

The following section describe how to authenticate a user for each client type.

Android client

An Android client supports asynchronous and synchronous authentication. When the user logs in successfully, the user's session token and timeout value are written to the AKSession object accessed by AKSession.getCurrentSession(). An instance of AKUser is created to contain information about the user that you can access at AKSession.getCurrentSession().getUser().

Before you can access an app scope running on the Akula Server from an Android client, you must initialize your connection to the app scope by calling the AK.init() method, passing the application context and the URL of the app scope running on the Akula Server. Typically you access the context by calling the Context.getApplicationContext() method, and the AK.init() method, in the onCreate() handler of the first activity in the app.

The following example authenticates a user asynchronously:

As you can see in this example, the asynchronous call creates two callback methods: one to handle the successful authentication and one to handle an authentication failure.

The log in credentials  are represented by a JSONObject, where the credentials are stored in fields named "principal" and "secret". The values of these fields is determined by the authentication realm. In this example, the realm is defined by an ActiveDirectory server which requires credentials contain string values. A different type of realm might require different types of credentials.  

For synchronous authentication, use a try/catch block to handle an exception generated by the login() method, as the following example shows:

iOS client

An iOS client supports asynchronous and synchronous authentication. When the user logs in successfully, the user's session token and timeout value are written to the AKSession object accessed by [AKSession currentSession]. An instance of AKUser is also created to contain information about the user that you can access at [AKSession currentSession].user.

Before you can access an app scope running on the Akula Server from an iOS client, you must initialize your connection to the app scope by calling the initialize: method of the AK class, passing the URL of the app scope running on the Akula Server.

The following example authenticates a user asynchronously:

In this example, the asynchronous calls to log in and log out methods both use callback methods: one to handle the successful authentication and one to handle an authentication failure.

The log in credentials are represented by an NSDictionary object, where the credentials are stored in key fields named "principal" and "secret". The values of these fields is determined by the authentication realm. In this example, the realm is defined by an ActiveDirectory server which requires credentials contain string values. A different type of realm might require different types of credentials.

The following example shows how to perform a synchronous log in:

JavaScript client

A JavaScript client supports asynchronous authentication only. To log in, use the AK.Session.login()method. When the user logs in successfully, an instance User is created and written to the AK.Session.current property. The AK.Session instance contains the user's session token and timeout value. The getUser() method, accessed as AK.Session.current.getUser(), contains information about the user.

The JavaScript client interface does not support synchronous log in and log out.

Before you can access an app scope on the Akula Server from a JavaScript client, you must initialize your connection to the app scope by calling the AK.init() method. Pass the URL of the app scope to the the AK.init() method.

Shown below is an asynchronous authentication:

Notice that in this example, the app defines callback methods to handle a successful authentication, and an authentication failure.

The log in credentials  are represented by a variable, where the credentials are stored in variable fields named "principal" and "secret". The values of these fields is determined by the authentication realm. In this example, the realm is defined by an ActiveDirectory server which requires credentials contain string values. A different type of realm might require different types of credentials.

REST API

You can bypass the client interfaces (Android, iOS, and JavaScript) and make a REST call to access an app scope directly. To access the app scope, make a POST (log in), DELETE (log out), or GET (query) request to the server. For more information on the authentication REST API, see Authentication REST API.

There are many ways to construct a REST call to the app scope, depending on your device and your preferred way of making REST calls. For example, the following Ajax code makes the REST request to log in and log out a user:

The log in credentials  are represented by a JSONObject, where the credentials are stored in fields named "principal" and "secret". The values of these fields is determined by the authentication realm. In this example, the realm is defined by an ActiveDirectory server which requires credentials contain string values. A different type of realm might require different types of credentials.