L7SClientManager Class Reference
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
-
delegate
delegate that impelemnts
propertyL7SClientProtocol
-
+ configureClientManagerWithEndpoint:apiKey:apiSecret:group:certificatePiningMode:startImmediately:
This is an initializer. It initializes and configures an instance of
L7SClientManager
with apiKey(clientId) and apiSecret(clientSecret). -
+ 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 -
+ sharedClientManager
the instance of the
L7SClientManager
if it has been configured and initialized -
– logoutDevice
Logout the device.
-
– logoffApp
Logoff the APP
-
– deRegister
De-Registert the device.
-
– enableSingleSignOn:
Enable or disable Single Sign-On
-
– isRegistered
Whether the device is registered (i.e. client certificate is provisioned)
-
– isSSOEnabled
Whether the Single Sing-On is enabled
-
– isDeviceLogin
Whether the device has a login session for the apps within the same group
-
– isAppLogon
Whether the current app has a login session
-
– authenticateWithUserName:password:
Authenticate with username and passord
-
– cancelAuthentication
Cancel the authentication operatoin.
-
– setLoginViewController:
Provide a custom login dialog
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
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