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 “[email protected]”. 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 “[email protected]” 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 “[email protected]”).

4.1 Authenticate

Class: BayunCore

Import: import com.bayun_module.BayunCore

You first need to authenticate with 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).

First you will make a static instance of BayunCore in Application class.

public static BayunCore bayunCore = new BayunCore(appContext);

val bayunCore = BayunCore(applicationContext)

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

Let's say an employee has loginId [email protected].

• activity : Activity Context.
• basicBayunCredentials : BasicBayunCredentials 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 “[email protected]”.
  • employeeId : 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 : It is used for taking passphrase input from the User when the User has enabled two-factor authorization and has created a passphrase. A passphrase is an alternative to entering answers for security questions. However, a passphrase is not compulsory. By default, the SDK uses AlertView to take User’s input for passphrase, if it 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 passphrase as input and call validatePassphrase API method in the SDK. The callback is triggered when passphrase is required.
• 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.

String appId = "0102030405060708090a0b0c0d0e0f"; //appId obtained from developer dashboard
String appSecret = "0102030405060708090a0b0c0d0e0f"; //appSecret obtained from the developer dashboard
String companyName = "bayunsystems.com"; //company portion from loginId
String employee = "username"; //username portion from loginId
String password = "employeePassword";
boolean autoCreateEmployee = true;

// Callbacks to authenticate user with Bayun.
Handler.Callback success = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
       Log.d(TAG, "Authentication successful.");
       return false;
    }
};

Handler.Callback failure = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        String error = message.getData().getString("BayunError", "");
        if (error.equalsIgnoreCase(BayunError.ERROR_USER_INACTIVE)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_INVALID_PASSPHRASE)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_INVALID_CREDENTIALS)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_AUTHENTICATION_FAILED)) {

        }
        return false;
    }
};
    
BasicBayunCredentials basicBayunCredentials = new BasicBayunCredentials(appId, companyName, employee, password, appSecret);
    
bayunCore.authenticateWithCredentials(activity, basicBayunCredentials, null, null, autoCreateEmployee, success, failure);

val appID = "0102030405060708090a0b0c0d0e0f" //appId obtained from developer dashboard
val appSecret = "0102030405060708090a0b0c0d0e0f" //appSecret obtained from the developer dashboard
val companyName = "bayunsystems.com" //company portion from loginId
val employee = "username" //username portion from loginId
val password = "employeePassword"
val autoCreateEmployee = true

// Callbacks to authenticate user with Bayun.
val success = Handler.Callback {
    Log.d(TAG, "Authentication successful.")
    false
}

val failure = Handler.Callback {
    val error: String = it.data.getString("BayunError", "")
    if (error.equals(BayunError.ERROR_USER_INACTIVE)) {

    } else if (error == BayunError.ERROR_INVALID_PASSPHRASE) {

    } else if (error == BayunError.ERROR_INVALID_CREDENTIALS) {

    } else if (error == BayunError.ERROR_AUTHENTICATION_FAILED) {

    }
    false
}

val basicBayunCredentials = BasicBayunCredentials(appID, companyName, employee, password, appSecret)

bayunCore.authenticateWithCredentials(
    this,
    basicBayunCredentials,
    null,
    null,
    autoCreateEmployee,
    success,
    failure
)

If custom UI is used to take user passphrase/answers to Security Questions, use the Bayun validatePassphrase method to validate the passphrase, and validateSecurityQuestions method to validate the answers to security questions.

String appId = "0102030405060708090a0b0c0d0e0f"; //appId obtained from developer dashboard
String appSecret = "0102030405060708090a0b0c0d0e0f"; //appSecret obtained from the developer dashboard
String companyName = "bayunsystems.com"; //company portion from loginId
String employee = "username"; //username portion from loginId
String password = "employeePassword";
boolean autoCreateEmployee = true;

// Callbacks to authenticate user with Bayun.
Handler.Callback success = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        Log.d(TAG, "Authentication successful.");
        return false;
    }
};

Handler.Callback failure = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        String error = message.getData().getString("BayunError", "");
        if (error.equalsIgnoreCase(BayunError.ERROR_USER_INACTIVE)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_INVALID_PASSPHRASE)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_INVALID_CREDENTIALS)) {

        } else if (response.equalsIgnoreCase(BayunError.ERROR_INTERNET_CONNECTION)) {

        }
        return false;
    }
};
    
// Callback to handle security questions response. Will be triggered if two-factor authorization is enabled for the user
Handler.Callback securityQuestions = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        ArrayList<HashMap<String, String>> questions = message.getData().getSerializable("securityQuestions");
        
        for (HashMap<String, String> question: questions) {
            Log.d(TAG, question.get("questionId"));
            Log.d(TAG, question.get("question"));
        }
        // Developer will add Custom UI to display security questions and get the answers input.
        return false;
    }
};
    
// Callback to handle passphrase response. Will be triggered if passphrase is required
Handler.Callback passphrase = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        // Developer will add Custom UI for passphrase.
        return false;
    }
};

// In this case passphrase or securityQuestions callbacks should not be null.
BasicBayunCredentials basicBayunCredentials = new BasicBayunCredentials(appId, companyName, employee, password, appSecret);
bayunCore.authenticateWithCredentials(activity, basicBayunCredentials, passphrase, securityQuestions, responseCallback);

val appID = "0102030405060708090a0b0c0d0e0f" //appId obtained from developer dashboard
val appSecret = "0102030405060708090a0b0c0d0e0f" //appSecret obtained from the developer dashboard
val companyName = "bayunsystems.com" //company portion from loginId
val employee = "username" //username portion from loginId
val password = "employeePassword"
val autoCreateEmployee = true

// Callbacks to authenticate user with Bayun.
val success = Handler.Callback {
    Log.d(TAG, "Authentication successful.")
    false
}

val failure = Handler.Callback {
    val error = it.data.getString("BayunError", "")
    if (error == BayunError.ERROR_USER_INACTIVE) {

    } else if (error == BayunError.ERROR_INVALID_PASSPHRASE) {

    } else if (error == BayunError.ERROR_INVALID_CREDENTIALS) {

    } else if (error == BayunError.ERROR_INTERNET_CONNECTION) {

    }
    false
}

// Callback to handle security questions response. Will be triggered if two-factor authorization is enabled for the user
val securityQuestions = Handler.Callback {
    val questions = it.data.getSerializable("securityQuestions")
        as ArrayList<HashMap<String, String>>

    for (question in questions) {

        Log.d(TAG, question["questionId"])
        Log.d(TAG, question["question"])
    }
    // Developer will add Custom UI to display security questions and get the answers input.
    false
}

// Callback to handle passphrase response. Will be triggered if passphrase is required
val passphrase = Handler.Callback {
    // Developer will add Custom UI for passphrase.
    false
}

// In this case passphrase or securityQuestions callbacks should not be null.
val basicBayunCredentials =
    BasicBayunCredentials(appID, companyName, employee, password, appSecret)

bayunCore.authenticateWithCredentials(
    this,
    basicBayunCredentials,
    securityQuestions,
    passphrase,
    autoCreateEmployee,
    success,
    failure
)

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.

bayunCore.deauthenticate();

bayunCore.deauthenticate()

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 method.

The method takes the following parameters :

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

String currentPassword = "current";
String newPassword = "new";

// Callbacks to Change User Password with Bayun.
Handler.Callback success = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        Log.d(TAG, "Password changed successfully.");
    }
};

Handler.Callback failure = new Handler.Callback() {
    @Override
    public boolean handleMessage(Message message) {
        String error = message.getData().getString("BayunError", "");
        if (error.equalsIgnoreCase(BayunError.ERROR_INVALID_PASSWORD)) {

        } else if (error.equalsIgnoreCase(BayunError.ERROR_INTERNET_CONNECTION)) {
                
        } 
        return false;
    }
};
    
bayunCore.changePassword(currentPassword, newPassword, success, failure);

val currentPassword = "current"
val newPassword = "new"

// Callbacks to Change User Password with Bayun.
val success = Handler.Callback {
    Log.d(TAG, "Password changed successfully.")
    false
}

val failure = Handler.Callback {
    val error = it.data.getString("BayunError", "")
    if (error == BayunError.ERROR_INVALID_PASSWORD) {

    } else if (error == BayunError.ERROR_INTERNET_CONNECTION) {

    }
    false
}

bayunCore.changePassword(currentPassword, newPassword, success, failure)