4. Authenticating with Bayun

BayunCore class provides methods to authenticate with the Lockbox Management Server, and then lock/unlock data of different types (file, text, byteArray, etc). Locking/Unlocking routines automatically use correct encryption keys from appropriate lockboxes etc, based on the context that was established with the authenticate call.

The Bayun SDK (in conjunction with Lockbox Management Server) handles the encryption/decryption keys and lockboxes based on the logged-in employee, and the company this employee belongs to. So an enterprise application developer should choose the companyName and the employeeId below, using the same criteria that are used inside the application to distinguish between different companies and the employees. For example, for the gmail app (or any other GSuite App), the login-id of the user is the email address in the form of “username@bayunsystems.com”. In this case, “bayunsystems.com” (the domain-name part of the email address) determines the company uniquely, and GSuite server will use policies applicable for that company. The “username” (or the complete email address “username@bayunsystems.com” itself) is the unique user-id, and determines the policies applicable to the logged-in user. So the developer should use “bayunsystems.com” as companyName, and “username” as employeeId. For a consumer application, or consumer use-case in a hybrid application, the developer can use a single companyName for all consumer users (e.g. “gmail.com”), and the employeeId can be the unique username of the user (e.g. “firstName.lastName” if the email-id of the user is “firstName.lastName@gmail.com”).

4.1 Authenticate

You first need to authenticate with the Bayun's Lockbox Management Server before you can make use of any Bayun features in your app. Make sure Bayun's authenticate is called only if, and after, your own app's authentication succeeds. Bayun relies on your own app's authentication to ensure correct password is used for a given companyName/employeeId combination, and the given user indeed has access to a specific companyName/employeeId, especially for the first time a user authenticates with Bayun. The user is on-boarded onto Bayun system after the first successful authentication (which can optionally require explicit approval from an admin). Once the user has been on-boarded, Bayun system requires shadow authentication using the same credentials as your own app's authentication for all further authentication attempts (so make sure to call appropriate password-change functions in Bayun-SDK when-ever any user changes their app password for your app).

The authenticateWithCredentials function is the instance method that initialises your access to Bayun. The method takes the following parameters :

Let's say an employee has loginId username@bayunsystems.com.

  • credentials : NSDictionary mapping the following parameters
    • companyName : Unique name of the company the authenticating employee belongs to or logs-in with, e.g. “bayunsystems.com” if the login-id is “username@bayunsystems.com”.
    • companyEmployeeId : EmployeeId unique within the company. E.g. "username" username portion from loginId
    • password : password of the user. Used to keep user secret keys protected. Never stored or transmitted by BayunSDK in clear. If the developer wishes, it can be a cryptographic hash of the password instead of the cleartext password itself. Bayun just needs a unique secret known to the user only, or something unique generated from it, for keeping the user lockboxes protected in such a way that nobody other than the user has access to it (similar to how iPhone does it with user’s device PIN).
    • appId : Unique appId for the app obtained by creating an application through Bayun developer dashboard. This appId needs to be kept secure.
    • appSecret : Unique appSecret for the app obtained by creating an application through Bayun developer dashboard. This appSecret needs to be kept secure.
  • securityQuestions : Most developers can just leave it null for default functionality. It is used for taking answers of Security Questions from the User when extra security with two-factor authorization is enabled. By default, the SDK uses AlertView to take User’s input for the answers of the Security Questions, if two-factor authorization is enabled is enabled for the user trying to authenticate. The developer can optionally provide a custom UI block for taking User’s input, to match with the look-and-feel of the app, instead of relying on the default alert-view. If non-null, this block will need to take user answers to the security questions as an input and call validateSecurityQuestions API method in the SDK. The callback is triggered when two-factor authorization is enabled for the user authenticating with Bayun. The Security Questions and QuestionIds are returned through data of the callback, in the form of an ArrayList of HashMap with key "securityQuestions".
  • passphrase : Optional block if passphrase is enabled. Most developers can just leave it nil for default functionality. It is used for taking user passphrase input for extra security when passphrase is explicitly enabled by the user. By default, the SDK uses AlertView to take user input for passphrase if it is enabled for a user. However the developer can optionally provide a custom UI block to match with the look-and-feel of the app instead of relying on the default alert-view. If non-nil, this block will need to take user passphrase as input and call Bayun validatePassphrase method for Passphrase validation.
  • autoCreateEmployee : Determines whether or not an employee should be created on LMS if not exists in the given company.
  • success : Success block to be executed after successful user authentication.
  • failure : Failure block to be executed if user authentication fails, returns BayunError.
When you registered for the Bayun developer program, we provided you with appID to use for your own app.
To use the code below in your own app, set appID to the appId we allocated for your own app. For example: ```a9af43f7171c64758d98c8ba4547d516```.

Objective-C
Swift 3.0

NSDictionary *credentials = @{@"companyName"  : @"bayunsystems.com", // company portion from loginId
                              @"companyEmployeeId" : @"username", //username portion from loginId
                              @"password" : @"employeePassword", 
                              @"appId"    : @"0102030405060708090a0b0c0d0e0f",//appId obtained from developer dashboard
                              @"appSecret": @"0102030405060708090a0b0c0d0e0f" //appSecret obtained from developer dashboard};
                              
[[BayunCore sharedInstance] authenticateWithCredentials: credentials securityQuestions:nil passphrase:nil autoCreateEmployee:true success:^{ 
    NSLog("Authenticated with Bayun successfully.");     
} failure:^(BayunError errorCode) {
    NSLog("Error authenticating with Bayun.");  
}


let credentials : NSDictionary = ["companyName" : "bayunsystems.com", // company portion from loginId
                                  "companyEmployeeId" : "username",// username portion from loginId
                                  "password" : "employeePassword",
                                  "appId"    : "0102030405060708090a0b0c0d0e0f", // appId obtained from developer dashboard
                                  "appSecret": "0102030405060708090a0b0c0d0e0f" //appSecret obtained from developer dashboard]
]
                                  
BayunCore.sharedInstance().authenticate(withCredentials: credentials as! [AnyHashable: Any], securityQuestions:nil, passphrase: nil, autoCreateEmployee:true, success: {
   NSLog(@"Authenticated with Bayun successfully.");
} , failure:  { (bayunErrorCode) in
   NSLog("Error authenticating with Bayun.");   
})

If custom UI is used to take user passphrase, use the Bayun validatePassphrase method to validate the passphrase.

Objective-C
Swift 3.0

[[BayunCore sharedInstance] validatePassphrase:@"passphrase" success:^{
    NSLog(@"Validated passphrase successfully.");
} failure:^(BayunError errorCode) {
    NSLog(@"Error validating with passphrase.");
}];

BayunCore.sharedInstance().validatePassphrase("passphrase", success: { 
    NSLog("Validated passphrase successfully.");        
 },failure: { (bayunErrorCode) in
    NSLog("Error validating with passphrase.");            
 })

4.2 Deauthenticate

To deauthenticate user and stop background Bayun services, use deautheticate method. This method can be used at the time of logging out of app.

Objective-C
Swift 3.0

[[BayunCore sharedInstance] deautheticate];

 BayunCore.sharedInstance().deautheticate()

Note -
In order to use  Bayun methods after deauthentication, you will need to authenticate the user again.

4.3 Change Password

To change password for Bayun, use changePassword: newPassword: success: failure: method.

The method takes the following parameters :

  • currentPassword : Current Password.
    • dataType : NSString
  • newPassword : New Password.
    • dataType : NSString
  • success : Success block to be executed after password is successfully changed.
  • failure : Failure block to be executed if change password fails, returns BayunError.

Objective-C
Swift 3.0

  [[BayunCore sharedInstance] changePassword:@"currentPassword" newPassword:@"newPassword"       success:^{
      NSLog("Password changed successfully.");    
  } failure:^(BayunError error) {
      NSLog("Change password failed.");
  }];

BayunCore.sharedInstance().changePassword("currentPassword", newPassword: "newPassword", success: {
   NSLog("Password changed successfully.");           
}, failure:  { (bayunErrorCode) in
   NSLog("Change password failed."); 
})

results matching ""

    No results matching ""