Authorization API details

The AppConnect Cordova Plugin provides an enumeration, an event, and methods that allow an app to handle the device user’s authorization status for using the app. For an overview of this feature, see Authorization .

The ACAuthState enumeration

The ACAuthState enumeration provides the possible authorization statuses for the device user to use the application:

AppConnectCordova.prototype.ACAuthState = {
    UNAUTHORIZED: 0, // The user is not authorized to access sensitive
                     // data or views in this app.
 
    AUTHORIZED:   1, // This is the only state in which the user is
                     // authorized to access sensitive data or views.
 
    RETIRED:      2  // The app must erase all sensitive data, 
                     // including any stored authentication
                     // credential.
}

The authState() and authMessage() methods

The authState() method

The following method returns the current authorization status of the device user for using the app:

AppConnectCordova.authState()

Return value: An AppConnectCordova.ACAuthState enumeration value.

The authMessage() method

The following method returns a string value that indicates the reason for the current authorization status:

 

AppConnectCordova.authMessage()

Return value: A string explaining the current authorization status

Calling authState() and authMessage() when your app launches

When your app launches:

1. Upon receiving the Cordova 'deviceready' event, call the method AppConnectCordova.initialize().
2. Wait for the AppConnectCordova event 'appconnect.isReady' before calling the AppConnectCordova.authState() or the AppConnectCordova.authMessage() methods.
3. While waiting, indicate in the user interface that the app is initializing if the app requires AppConnectCordova methods such as AppConnectCordova.authState() to determine what to do. For example, use an activity indicator (spinner).

One reason this indication is important involves when to display sensitive data. Do not show any sensitive data until the AppConnect Cordova Plugin is ready, because until that time, the app cannot determine whether it is authorized. Only an authorized app should show sensitive data.

In the event handler for the 'appconnect.isReady' event, check the return value of the AppConnectCordova.authState() method. Do the following:

1. Remove the indication that the app is initializing.
2. If the status is not the AppConnectCordova.ACAuthState value AUTHORIZED:
- Do not allow the user to see or access sensitive data.
- Display the string returned by the AppConnectCordova.authMessage() method.
3. If the status is the AppConnectCordova.ACAuthState value AUTHORIZED, allow the user to see and access sensitive data. Typically, the app does not display the AppConnectCordova.authMessage() string when the status is AUTHORIZED.

Method return values after updates to authorization status

On any updates to authorization status or message while the app is running, the AppConnect Cordova Plugin generates the 'appconnect.authStateChangedTo' event. Subsequent calls to the AppConnectCordova.authState() and AppConnectCordova.authMessage() methods return the updated authorization status and message.

The 'appconnect.authStateChangedTo' event

The AppConnect Cordova Plugin generates the 'appconnect.authStateChangedTo' event when the authorization state or authorization message changes after the plugin initialization is completed.

The event object passed to the event handler contains:

Event object properties

Description

newAuthState

An AppConnectCordova.ACAuthState enumeration value

authMessage

A string explaining the new authorization status

Event handler for 'appConnect.authStateChangedTo' event

When a change has occurred to the user’s authorization status, the AppConnect Cordova Plugin:

1. Stores the new AppConnectCordova.ACAuthState value so that subsequent calls to the AppConnectCordova.authState() method returns the updated authorization status.
2. Stores the new string value explaining the new authorization status so that subsequent calls to the AppConnectCordova.authMessage() method return the updated authorization message.
3. Generates the 'appconnect.authStateChangedTo' event.

You are required to add an event listener to your document object for the 'appconnect.authStateChangedTo' event. For example:

document.addEventListener('appconnect.authStateChangedTo',
                           this.onAppConnectAuthStateChangedTo, false);

Your app handles the new status as follows:

New status

App actions

UNAUTHORIZED

  • Exits any sensitive part of the application.

  • Stops allowing the user to access sensitive data and views.

  • Displays the message received in the event that explains the authorization status change.

  • Calls the AppConnectCordova.authStateApplied() method.

AUTHORIZED

  • Allows the user to access sensitive data and views.

  • Calls the AppConnectCordova.authStateApplied() method.

RETIRED

  • Exits any sensitive part of the application.

  • Deletes all sensitive data, including any stored authentication credentials, data in files, keychain items, pasteboard data, and any other persistent storage.

  • Displays the message received in the event that explains the authorization status change.

  • Calls the AppConnectCordova.authStateApplied() method.

The AppConnect Cordova Plugin can generate the event when only the explanatory string, but not the authorization status, has changed. When the status is UNAUTHORIZED or RETIRED, the message typically contains a new reason for the status. Display the new message.

The authStateApplied() method

After your event handler processes the information provided in the 'appconnect.authStateChangedTo' event, it must call this acknowledgment method:

AppConnectCordova.authStateApplied(policyState, message)

Your app passes the following parameters to this method:

•the AppConnectCordova.ACPolicyState value that represents the success or failure of handling the new authorization status.

Pass the value APPLIED if the app successfully handled the new status. Otherwise, pass the value ERROR. Passing the value UNSUPPORTED is not allowed, because every app must handle authorization status changes.

•a string explaining the AppConnectCordova.ACPolicyState value.

Typically, you use this string to report the reason the app failed to apply the new authorization status. The string is reported in the Ivanti server log files.

The displayMessage() method

The AppConnect Cordova Plugin provides a method that causes the Ivanti client app to display the current authorization status message:

AppConnectCordova.displayMessage(message)

In most cases, your production app does not use this method. Your production app is responsible for displaying the message that it receives in the event handler for an authorization status change. Your app controls exactly when and how to display the string.

However, you can temporarily use this method when your app is under development. For example, when the status changes to UNAUTHORIZED, your app must exit all sensitive views. This requirement can make displaying the message difficult, depending on the application. In this case, use the AppConnectCordova.displayMessage() method until you are able to fully develop your app.