Authorization API details

The AppConnect for iOS API provides properties 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:

typedef enum {
    ACAUTHSTATE_UNAUTHORIZED    =  0, // The user is not authorized to access sensitive
                                      // data or views in this app.
    ACAUTHSTATE_AUTHORIZED      =  1, // This is the only state in which the user is
                                      // authorized to access sensitive data or views.
    ACAUTHSTATE_RETIRED         =  2, // The app must erase all sensitive data, 
                                      // including any stored authentication
                                      // credential. 
} ACAuthState;

The authState and authMessage properties

The following read-only properties on the AppConnect singleton relate to authorization:

Table 1. Authorization properties on the AppConnect singleton

Property	Description
authState	An ACAuthState value that indicates the current authorization status of the device user for using the app.
authMessage	A string value that indicates the reason for the current authorization status.

When your app launches:

•

Get the singleton AppConnect object and call its -startWithLaunchOptions: method.

•

Wait for the -appConnectIsReady: callback method before accessing the authState and the authMessage properties.

While waiting, indicate in the user interface that the app is initializing if the app requires the AppConnect singleton’s instance properties 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 singleton is ready, because until that time, the app cannot determine whether it is authorized. Only an authorized app should show sensitive data.

After the -appConnectIsReady: callback method is called, check the value of the authState property. Do the following:

•

Remove the indication that the app is initializing.

•

If the status is not ACAUTHSTATE_AUTHORIZED, do not allow the user to see or access sensitive data.

•

If the status is not ACAUTHSTATE_AUTHORIZED, display the authMessage string.

•

If the status is ACAUTHSTATE_AUTHORIZED, allow the user to see and access sensitive data. Typically, the app does not display the authMessage string when the status is ACAUTHSTATE_AUTHORIZED.

On any updates to authorization status while the app is running, the AppConnect library updates the properties, and then calls the -appConnect:authStateChangedTo:withMessage: method.

Authorization methods

Your app uses the following methods to receive updates to the authorization status and report how the app handled the updates.

•

The -appConnect:authStateChangedTo:withMessage: callback method

•

The -authStateApplied:message: acknowledgment method

•

The -displayMessage: method

The -appConnect:authStateChangedTo:withMessage: callback method

You are required to implement this method, which is in the AppConnectDelegate protocol:

-(void) appConnect:(AppConnect *) appConnect
           authStateChangedTo:(ACAuthState)newAuthState 
           withMessage:(NSString *)message;

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

1.

Sets the authState property on the AppConnect object to the new ACAuthState value.

2.

Sets the authMessage property on the AppConnect object to a string explaining the new authorization status.

3.

Calls the -appConnect:authStateChangedTo:withMessage: method.

The method provides the following in its parameters:

•

the new authorization status as a ACAuthState value

•

an NSString, which is a message explaining the new authorization status

Your app then handles the new status as follows:

Table 2. Authorization status handling

New status	App actions
ACAUTHSTATE_UNAUTHORIZED	• Exits any sensitive part of the application. • Stops allowing the user to access sensitive data and views. • Displays the message received in the callback method that explains the authorization status change. • Calls the -authStateApplied:message: method.
ACAUTHSTATE_AUTHORIZED	• Allows the user to access sensitive data and views. • Calls the -authStateApplied:message: method.
ACAUTHSTATE_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 callback method that explains the authorization status change. • Calls the -authStateApplied:message: method.

NOTE:

The AppConnect library can call the callback method when only the explanatory string, but not the authorization status, has changed. When the status is ACAUTHSTATE_UNAUTHORIZED or ACAUTHSTATE_RETIRED, the message typically contains a new reason for the status. Display the new message.

The -authStateApplied:message: acknowledgment method

After your app processes the information provided in the callback method, it must call this acknowledgment method on the AppConnect singleton:

 

-(void)authStateApplied:(ACPolicyState)policyState message:(NSString *)message;

Your app passes the following parameters to this method:

•

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

Pass the value ACPOLICY_APPLIED if the app successfully handled the new status. Otherwise, pass the value ACPOLICY_ERROR. Passing the value ACPOLICY_UNSUPPORTED is not allowed, because every app must handle authorization status changes.

•

an NSString explaining the 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 MobileIron server log files.

The -displayMessage: method

The following method on the AppConnect singleton causes the MobileIron client app to display the current authorization status message:

 

-(void)displayMessage:(NSString *)message withCompletion:(void(^)(BOOL success))completion;

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 notification method 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 ACAUTHSTATE_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 -displayMessage: method until you are able to fully develop your app.