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 “firstname.lastname@example.org”. 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@example.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”).
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; bayunCore = new BayunCore(appContext);
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
- 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 “firstname.lastname@example.org”.
- 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.
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.
To deauthenticate user and stop background Bayun services, use
This method can be used at the time of logging out of app.
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
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.