Inherits from NSObject
Declared in L7SClientManager.h

Overview

The SDK acts as an API management engine on iOS that helps to abstract and encapsulate the complexity of credential management, defines a set of workflows and streamlines the processes. It aims to address the security concerns of BYOD (Bring-Your-Own-Device) including but not limited to single sign-on, PKI provisioning, mutual SSL, soical login, QR code authentication, etc..

The SDK uses an open-source project, AFNetworking, a top-ranked networking library for iOS and Mac OS X, as an underlying networking component. Therefore, the SDK inherits all the features that are provided by AFNetworking. To find more details of what AFNetworking can do, please check here.

Highlights of some key features

1. Easy control:

The SDK exposes a set of class methods to configure and control the SDK. The class methods are per-app based, meaning that they are controlling all L7SHTTPClient instances within the same app. Typically a developer will configure and initialize the SDK by calling the following method in AppDelegate:

[L7SClientManager configureClientManagerWithEndpoint:@"https://www.example.com"
                                              apiKey:@"PUT_YOUR_CLIENT_ID_HERE"
                                               group:@"YOUR_APP_ID_PREFIX.com.yourcompany.singleSignOn"
                               certificatePiningMode:AFSSLPinningModeNone
                                    startImmediately:YES];

The available pinning modes are: AFSSLPinningModeNone, AFSSLPinningModePublicKey, and AFSSLPinningModeCertificate.

Other convenient methods provided are “logoutDevice”, “logoffApp”, and “deRegister”.

2. Streamlined workflows:

Whenever there is an attempt to make a HTTP request to a protected endpoint, or when the configured app becomes active (if startImmediately parameter is set to YES), the SDK will be triggered to take pre-defined actions and workflows dependent on the device registration status and the user authentication status. For example, if the device is not registered, or the user is not authenticated, the User will be prompted for an authentication challenge, and then a workflow will be triggered to start the registration and authentication processes.

3. Non-blocking requests:

An app may create any number of L7SHTTPClient instances and make any number of requests simultaneously, the SDK will queue all the requests in a non-blocking mode without blocking UIs, and send them asynchronously once authentication challenges are resolved.

4. Abstraction and encapsulation:

The SDK encapsulates and abstracts the complexity of authentication protocol and the details of the credential management. For example, if a credential session is expired, it will automatically start a process to refresh a new user session if possible without prompting the User.

5. Single Sign-On and mutual SSL

The SDK provides an API to enable or disable single sign-on. When single sign-on is enabled, a login session will be shared by the apps within the same group across the device. The SDK also supports certificate pinning for validating server trust. In addition, the SDK also supports mutual SSL by default.

6. Error handling and status updates:

The SDK is responsible for handling all errors and status updates at the protocol levels and callback to notify the apps.

7. HTTP responses with success and failure:

The SDK also provides success and failure callback blocks as parameters to allow developers to tailor the actions to HTTP responses.

Delegate

An app can implement a L7SClientProtocol to receive callback, for example system errors, from the SDK. Please refer to L7SClientProtocol for details.

Notifications

An app can subscribe to a notification for important status updates from the SDK. The followings are the notification key and status key:

extern NSString * const L7SStatusUpdateKey;  //status key for retrieving status from the userinfo
extern NSString * const L7SDidReceiveStatusUpdateNotification;   //notification key

The following is a list of possible status:

typedef enum{
    L7SDidFinishRegistration,
    L7SDidFinishAuthentication,
    L7SDidFinishDeRegistration,
    L7SDidLogout,
    L7SDidLogoff,
    L7SLocationServiceAuthorized,
    L7SLocationServiceDenied,
    L7SQRAuthenticationPollingStopped
} L7SClientState;

The following is an example of subscribing for the notification:

[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(didReceiveStatusUpdate:)
                                             name:L7SDidReceiveStatusUpdateNotification
                                           object:nil];

 //retrieve the the state from the notification
 L7SClientState state = (L7SClientState)[[notification.userInfo objectForKey:L7SStatusUpdateKey] intValue];

Tasks

Properties

delegate

delegate that impelemnts L7SClientProtocol

@property id<L7SClientProtocol> delegate

Discussion

delegate that impelemnts L7SClientProtocol

Declared In

L7SClientManager.h

Class Methods

configureClientManagerWithEndpoint:apiKey:apiSecret:group:certificatePiningMode:startImmediately:

This is an initializer. It initializes and configures an instance of L7SClientManager with apiKey(clientId) and apiSecret(clientSecret).

+ (id)configureClientManagerWithEndpoint:(NSString *)apiEndpoint apiKey:(NSString *)apiKey apiSecret:(NSString *)apiSecret group:(NSString *)appGroup certificatePiningMode:(L7SAFURLConnectionOperationSSLPinningMode)pinningMode startImmediately:(BOOL)startImmediately

Parameters

apiEndpoint

the endpoint responsible for authenicating user and authorizing resources access.

apiKey

the client key issued to the app by an authorization server.

apiSecret

the client key issued to the app by an authorization server.

appGroup

the group identifier that the single-sign-on apps share.

pinningMode

the certificate pinning mode that SDK uses to determine how to responds to server trust validation.

startImmediately

the flag to indicate SDK whether it should start service immediately when the app becomes active.

Return Value

an instance of the L7SClientManager

Discussion

This is an initializer. It initializes and configures an instance of L7SClientManager with apiKey(clientId) and apiSecret(clientSecret).

There are three pinning options:

L7SAFSSLPinningModeNone: no pinning is required.

L7SAFSSLPinningModePublicKey: the pinning will find a match between public keys contained in the certificates provided in the resource bundle with the public keys presented in the server trust.

L7SAFSSLPinningModeCertificate: the pinning will find a match between the certificates provided in the resource bundle with the certificates presented in the server trust.

The pinning certificates must be in DER format ending with .cer, and be included in the app’s resource bundle.

Declared In

L7SClientManager.h

configureClientManagerWithEndpoint:apiKey:group:certificatePiningMode:startImmediately:

This is an initializer. It initializes and configures an instance of L7SClientManager with apiKey(clientId) only. This initializer is prefered to the other initializer which requires apiSecret. With this initialzer, apiSecret will be created dynamically, which enchances the security

+ (id)configureClientManagerWithEndpoint:(NSString *)apiEndpoint apiKey:(NSString *)apiKey group:(NSString *)appGroup certificatePiningMode:(L7SAFURLConnectionOperationSSLPinningMode)pinningMode startImmediately:(BOOL)startImmediately

Parameters

apiEndpoint

the endpoint responsible for authenicating user and authorizing resources access.

apiKey

the client key issued to the app by an authorization server.

appGroup

the group identifier that the single-sign-on apps share.

pinningMode

the certificate pinning mode that SDK uses to determine how to responds to server trust validation.

startImmediately

the flag to indicate SDK whether it should start service immediately when the app becomes active.

Return Value

an instance of the L7SClientManager

Discussion

This is an initializer. It initializes and configures an instance of L7SClientManager with apiKey(clientId) only. This initializer is prefered to the other initializer which requires apiSecret. With this initialzer, apiSecret will be created dynamically, which enchances the security

There are three pinning options:

L7SAFSSLPinningModeNone: no pinning is required.

L7SAFSSLPinningModePublicKey: the pinning will find a match between public keys contained in the certificates provided in the resource bundle with the public keys presented in the server trust.

L7SAFSSLPinningModeCertificate: the pinning will find a match between the certificates provided in the resource bundle with the certificates presented in the server trust.

The pinning certificates must be in DER format ending with .cer, and be included in the app’s resource bundle.

Declared In

L7SClientManager.h

sharedClientManager

the instance of the L7SClientManager if it has been configured and initialized

+ (L7SClientManager *)sharedClientManager

Return Value

the instance of the L7SClientManager if it has been configured and initialized

Declared In

L7SClientManager.h

Instance Methods

authenticateWithUserName:password:

Authenticate with username and passord

- (void)authenticateWithUserName:(NSString *)userName password:(NSString *)password

Discussion

Authenticate with username and passord

This method should be called only when the User presses the login button presented in the SDK prompted login dilag. This allows the SDK to prepare the authenitcation workflows based on the cusrrent status of the app.

Declared In

L7SClientManager.h

cancelAuthentication

Cancel the authentication operatoin.

- (void)cancelAuthentication

Discussion

Cancel the authentication operatoin.

Calling this method will remove the login dialog and clean up all the pending operations

Declared In

L7SClientManager.h

deRegister

De-Registert the device.

- (void)deRegister

Discussion

De-Registert the device.

The method resets the device so that it removes all access credentials and client certificates within the same group across the device. This method can be used when the app is in a state that its current client certificate becomes invalid. In this case, calling this method will reset the device, so that the registration process will be triggered to initiate a new PKI provisioning process.

The app user needs to kill the app to achieve a clean device reset before any other activities on the app, because de-registration process does not clean the TLS cache.

Please note that SDK will callback with a state “L7SDidFinishDeRegistration” once the de-registration process is completed, at this point app user may be prompted for an alert message, such as notifying to kill the app.

Declared In

L7SClientManager.h

enableSingleSignOn:

Enable or disable Single Sign-On

- (void)enableSingleSignOn:(BOOL)enabled

Parameters

enabled

true if enable Single Sign-On

Discussion

Enable or disable Single Sign-On

Declared In

L7SClientManager.h

isAppLogon

Whether the current app has a login session

- (BOOL)isAppLogon

Discussion

Whether the current app has a login session

Declared In

L7SClientManager.h

isDeviceLogin

Whether the device has a login session for the apps within the same group

- (BOOL)isDeviceLogin

Discussion

Whether the device has a login session for the apps within the same group

Declared In

L7SClientManager.h

isRegistered

Whether the device is registered (i.e. client certificate is provisioned)

- (BOOL)isRegistered

Discussion

Whether the device is registered (i.e. client certificate is provisioned)

Declared In

L7SClientManager.h

isSSOEnabled

Whether the Single Sing-On is enabled

- (BOOL)isSSOEnabled

Discussion

Whether the Single Sing-On is enabled

Declared In

L7SClientManager.h

logoffApp

Logoff the APP

- (void)logoffApp

Discussion

Logoff the APP

The method removes access credeintials of the current app

Declared In

L7SClientManager.h

logoutDevice

Logout the device.

- (void)logoutDevice

Discussion

Logout the device.

The method removes access credeintials of all apps within the same group on the device

Declared In

L7SClientManager.h

setLoginViewController:

Provide a custom login dialog

- (void)setLoginViewController:(UIViewController<L7SLoginDialogDelegate> *)loginViewController

Discussion

Provide a custom login dialog

Declared In

L7SClientManager.h