4. Authenticating with Bayun

BayunCore class provides functions 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 Initialise BayunCore

Initialise BayunCore with appId and appSecret

import BayunCore

bayunCore = BayunCore.BayunCore("<appId>", "<appSecret>")

4.2 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 authenticate function is the instance function that initialises your access to Bayun. The function takes the following parameters :

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

  • sessionId : Unique sessionId.

    You can provide a unique sessionId to the authenticate function call. If an empty sessionId i.e " " is provided, Bayun creates and returns a unique sessionId in the successful authentication response.

    Same sessionId should be provided in all the subsequent calls to the Bayun APIs as an argument.

  • 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).

  • autoCreateEmployee : Determines whether or not an employee should be created on LMS if not exists in the given company.

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

The authenticate function returns sessionId and responseCode of type enum BayunAuthResponseCode as the authentication response.

Following are the possible values of BayunAuthResponseCode :

  • Success : Authentication is successful.

  • VerifySecurityQuestions : When two-factor authorization is enabled for the user authenticating with Bayun. The Security Questions and QuestionIds are returned in the authenticate response.

    Authentication completes when answers are validated for the security questions.

  • VerifySecurityQuestionsOrPassphrase : When two-factor authorization is enabled for the user authenticating with Bayun. The authenticating user has both Passphrase and Security Questions Answers set.

    Authentication completes when either of the two passphrase or answers for the security questions are validated.

  • AppNotLinked : Application is not linked. Authenticating user has to login to the Admin Panel/App and link the application.

Use validatePassphrase function to validate the passphrase.

The function takes the following parameters :

  • sessionId : Unique SessionId which is received in the authenticate function response.

  • passphrase : Passphrase to validate.

Use validateSecurityQuestions function to validate the security questions' answers.

The function takes the following parameters :

  • sessionId : Unique SessionId which is received in the authenticate function response.

  • answers : Security questions' answers of type SecurityQuestionAnswerVector.

try:

    companyName = "bayunsystems.com" # company portion from loginId
    companyEmployeeId = "username" #username portion from loginId
    password = "<employeePassword>"
    autoCreateEmployee = True

    authResponse = bayunCore.authenticate("<sessionId>", companyName, companyEmployeeId, password, autoCreateEmployee)
    sessionId = authResponse.sessionId
    responseCode = authResp.responseCode

    if responseCode == BayunAuthResponseCode.Success.value:
        #Authentication is Successful. Perform Bayun Operations
    
    elif responseCode == BayunAuthResponseCode.VerifySecurityQuestions.value:
        securityQuestions = authResponse.getSecurityQuestions()
        for securityQuestion in securityQuestions:
            print("\nQuestionId : " + securityQuestion.questionId)
            print("QuestionText : " + securityQuestion.questionText)
    
        answer1 = bayunCore.SecurityQuestionAnswer("<questionId>", "<answer>")
        answer2 = bayunCore.SecurityQuestionAnswer("<questionId>", "<answer>")
        answer3 = bayunCore.SecurityQuestionAnswer("<questionId>", "<answer>")
        answer4 = bayunCore.SecurityQuestionAnswer("<questionId>", "<answer>")
        answer5 = bayunCore.SecurityQuestionAnswer("<questionId>", "<answer>")

        securityQuestionAnswerVector = bayunCore.SecurityQuestionAnswerVector()
        securityQuestionAnswerVector.push_back(answer1)
        securityQuestionAnswerVector.push_back(answer2)
        securityQuestionAnswerVector.push_back(answer3)
        securityQuestionAnswerVector.push_back(answer4)
        securityQuestionAnswerVector.push_back(answer5)

        response = bayunCore.validateSecurityQuestions(sessionId, securityQuestionAnswerVector)
        sessionId = response.sessionId
        responseCode = authResp.responseCode
    
        if responseCode == BayunAuthResponseCode.Success.value:
            #Authentication is Successful. Perform Bayun Operations.

    elif responseCode == BayunAuthResponseCode.VerifySecurityQuestionsOrPassphrase.value:
        #Validating Passphrase for demonstration.
        response = bayunCore.validatePassphrase(sessionId, "<passphrase>")
        sessionId = response.sessionId
        responseCode = response.responseCode
        if responseCode == BayunAuthResponseCode.Success.value:
            #Authentication is Successful. Perform Bayun Operations.
    
    elif responseCode == BayunAuthResponseCode.AppNotLinked.value:
        #Application is not linked. Authenticating user has to login to the Admin Panel/App and link the application.
except bayunCore.BayunCoreException as exception:
    print("BayunException : ", exception.getErrMsg())

4.3 Deauthenticate

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

The function takes the following parameters :

  • sessionId : Unique SessionId which is received in the authenticate function response.

bayunCore.deauthenticate("<sessionId>")

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

4.4 Change Password

To change password for Bayun, use changePassword function.

The function takes the following parameters :

  • sessionId : Unique SessionId which is received in the authenticate function response.

    • dataType : string

  • currentPassword : Current Password.

    • dataType : string

  • newPassword : New Password.

    • dataType : string

response = bayunCore.changePassword("<sessionId>", "<currentPassword>", "<newPassword>")

Previous3. Installing Bayun LibraryNext5. BayunCoreSDK Operations

Last updated