Activation

Enrollment process of pairing identity of user with integrating application is called activation in CM SDK. During this process, data needed for account instance are created (or received) and stored to storage.

Process of activation consists of multiple steps. At least 3 steps are required to perform an activation, but it can contain more optional steps.

Usually, identity of an user is verified using an activation code, that is delivered by some independent channel and can have multiple parts. Additional verification steps of user's device or credentials may be applied. Also, in the activation process, user should enter his PIN, that will be used as knowledge factor for authentication later in activated application.

Activation

Class that is responsible for activation process is called Activation. It has method for both mandatory and optional activation steps. All steps have to be performed in proper order and on the same instance of the class. Mandatory steps are changing the state of an instance, optional steps do not have to.

Mandatory steps are:

• initiate - initializes session
• confirm - verifies last part of activation code
• finish - checks if all generated data are correct and stores them

Optional steps are (can be used between init and finish):

• verifyPin - perform user authentication (usable only if user already has PIN)
• verifyPassword - perform user authentication (with a password from external system)
• verifyActivationCode - verifies part of activation code
• requestSmsCode - requests sending of SMS with one-time code to user's phone
• getVerificationSmsText - requests text that will be sent as SMS from user's phone to backend
• requestActivationTransaction - creates transaction that will be authorized by user's another CASE mobile instance
• verifyPasswordWithActivationCode - verifies two factors simultaneously - external password and activation code
• verifyPinWithActivationCode - verifies two factors simultaneously - pin and activation code)
• cancelActivation - cancels activation process
• canProceedWithActivation - check if activation can continue if it was waiting for something
• establishDeviceSigningKey - generates & attest additional keypair for special form of signature

Android:

val type: CMAccountType = ... // get account type instance
val act = CMActivation.instance(context)

val nickname: String = ... // get nickname from user
val listener: CMInitListener = ...
act.init(nickname, type, null, listener)

val pin: ByteArray = ... // derive value from user pin
val pinAuthentication = CMPinAuthentication.instanceForPin(pin)
val listener: CMUpdateListener = ...
act.verifyPin(pinAuthentication, listener)

val password: ByteArray = ... // derive value from user password
val pwdAuthentication = CMPasswordAuthentication.instanceForPassword(password)
val listener: CMUpdateListener = ...
act.verifyPassword(pwdAuthentication, listener)

val listener: CMRequestSmsCodeListener = ...
act.requestSmsCode(listener)

val listener: CMVerificationSmsListener = ...
act.getVerificationSmsText(listener)

val listener: CMUpdateListener = ...
act.canProceedWithActivation(listener)

val listener: CMUpdateListener = ...
act.requestActivationTransaction(listener)

val activationCode: String = ... // get activation code from user
val listener: CMVerifyACListener = ...
act.verifyActivationCode(activationCode, CMConstants.ACTIVATION_CODE_TYPE_AC_CC, listener)

val activationCode: String = ... // get activation code from user
val password: ByteArray = ... // derive value from user password
val pwdAuthentication = CMPasswordAuthentication.instanceForPassword(password)
val listener: CMVerifyPasswordWithActivationCodeListener = ...
act.verifyPasswordWithActivationCode(pwdAuthentication, activationCode, CMConstants.ACTIVATION_CODE_TYPE_AC_CC, listener)

val activationCode: String = ... // get activation code from user
val pin: ByteArray = ... // derive value from user pin
val pinAuthentication = CMPinAuthentication.instanceForPin(pin)
val listener: CMVerifyPinWithActivationCodeListener = ...
act.verifyPinWithActivationCode(pinAuthentication, activationCode, CMConstants.ACTIVATION_CODE_TYPE_AC_CC, listener)

val listener: CMCancelActivationListener = ...
act.cancelActivation(listener)

val activationCode: String = ... // get activation code from user
val listener: CMConfirmListener = ...
act.confirm(null, activationCode,  CMConstants.ACTIVATION_CODE_TYPE_OTP, EnumSet.of(AuthenticationMethod.PIN, AuthenticationMethod.FINGERPRINT), listener)

val listener: CMFinishListener = ...
act.finish(cmPinAuthentication, listener)

iOS:

let accountType = ... // see AccountTypes
let act = Activation.instance()
 
let nickname: String = ... // get nickname from user
act.initiateActivation(nickname: nickname, accountType: accountType, clientCertificateConfiguration: nil) { (result) in /*...*/ }

let clientId: String = ... // define value for app
let appAttestationId: String = ... // define value for app
act.establishDeviceSigningKey(clientId: clientId, appAttestationId: appAttestationId) { (result) in /*...*/ }

let pin: Data = ... // derive value from user pin
act.verifyPin(pin: pin) { (result) in /*...*/ }

let password: String = ... // derive value from user password
act.verifyPassword(password: password) { (result) in /*...*/ }

let activationCode: String = ... // get activation code from user
act.verifyActivationCode(activationCode: activationCode, activationCodeType: ActivationCodeType.acCc) { (result) in /*...*/ }

let password: String = ... // derive value from user password
let activationCode: String = ... // get activation code from user
act.verifyPasswordWithActivationCode(password: password, activationCode: activationCode, activationCodeType: ActivationCodeType.acCc) { (result) in /*...*/ }

let pin: Data = ... // derive value from user pin
let activationCode: String = ... // get activation code from user
act.verifyPinWithActivationCode(pin: pin, activationCode: activationCode, activationCodeType: ActivationCodeType.acCc) { (result) in /*...*/ }

act.requestSmsCode(/*sendOverVoice: true*/) { (result) in /*...*/ }

act.getVerificationSmsText { (result) in /*...*/ }

act.canProceedWithActivation { (result) in /*...*/ }

act.requestActivationTransaction { (result) in /*...*/ }

let requestedAuthenticationMethods: [AuthenticationMethod] = [.pin]
act.confirm(appId: nil, activationCode: activationCode, activationCodeType: ActivationCodeType.acCc, requestedAuthenticationMethods: requestedAuthenticationMethods) { (result) in /*...*/ }

let pin: Data = ... // derive value from user pin
act.finish(pin: pin) { (result) in /*...*/ }

AppData

In few cases, there is an appData parameter in method or in callback method. It is used to transfer data - not related to activation of an account, but required by application - from server to application.

Continue to Deactivation