Change PIN
This topic guide explains all the steps required to add the change PIN functionality to your app. In case you didn't add the SDK to your application project yet, please follow the steps in the Setting up the project topic guide.
Changing Pin
In some cases the end-user may want to change his/her pin to a different one. For this purpose the SDK provides an API. The SDK requires that the end-user is authenticated before he/she can change the PIN. The new PIN that the end-user chooses will get validated against the PIN policy and either accepted by the SDK or declined (based on the policy rules). In case of an invalid current PIN a new attempt to enter the PIN is given.
Changing PIN is not possible for a stateless user
Initializing Change Pin Flow
In order to start the change pin flow a user has to call the changePin
method, which expects the following argument:
delegate
- the object that conforms to theChangePinDelegate
protocol.
The SDK should have an authenticated user (
SharedUserClient.instance.authenticatedUserProfile
can not benil
), otherwise an error will be returned.
In case of a successful invocation the SDK will immediately notify the delegate method ChangePinDelegate userClient(_:didStartPinChangeForUser:)
this
receives the following arguments:
userClient
- the instance of theUserClient
that is responsible for pin change. It is corresponds to theSharedUserClient.instance.changePin
recevier.userProfile
- the instance of theUserProfile
for whom the PIN is going to be changed. It is the same profile as the profile of the currently authenticated user returned by invoking theSharedUserClient.instance.authenticatedUserProfile
method.
However if there is no authenticated user found or something else went wrong the SDK notifies you about the raised error by calling
the ChangePinDelegate userClient(_:didFailToChangePinForUser:error:)
method. It receives the following arguments:
userClient
- the instance of theUserClient
that is responsible for the PIN change. It is the same as the-SharedUserClient.instance.changePin
receiver.userProfile
- an instance of theUserProfile
for whom the PIN is going to be changed. It is the same profile as the profile of the currently authenticated user returned by invoking theSharedUserClient.instance.authenticatedUserProfile
method.error
- an instance of theNSError
class. The Possible error domains areONGGenericErrorDomain
,ONGChangePinErrorDomain
orONGPinAuthenticationErrorDomain
.
Both methods mentoined above are optional.
Authentication
Once the change PIN flow has been started it asks the delegate to let the end-user provide the current PIN. This can be done by implementing the
ChangePinDelegate
userClient(_:didReceivePinChallenge:)`` which is required. It receives the following arguments:
userClient
- the instance of theUserClient
that is responsible for the PIN change. It is the same as theSharedUserClient.instance.changePin
receiver.challenge
- an instance of thePinChallenge
. This object encapsulates all required information for successful authentication. An In-depth object usage description is given in the Provide PIN authentication paragraph of the User authentication.
Creating a new Pin
After the current PIN has been successfully entered the SDK forces the end-user to create a new one by calling the
ChangePinDelegate
userClient(_:didReceiveCreatePinChallenge:)`` method that receives following arguments:
userClient
- the instance of theUserClient
that is responsible for the PIN change. It is the same as theSharedUserClient.instance.changePin
receiver.challenge
- an instance of theCreatePinChallenge
.
Lets take a more details look at the CreatePinChallenge
. This class provides the required information for creating a new PIN and also a sender awaiting for
the response:
userProfile
- the instance of theUserProfile
for which the change PIN action was started.pinLength
- the required length for a new PIN.error
- theError
that describes the previous failure reason (if any). Possible error domains areONGPinValidationErrorDomain
andONGGenericErrorDomain
.sender
- the object that conforms to theCreatePinChallengeSender
protocol. Once the PIN has been entered you have to provide it to thesender
object in order to proceed.
Generally, creation of a new PIN is quite similar to create PIN step of the registration process.
Here is sample code that demonstrates the implementation of the create PIN challenge:
See the Pin handling recommendations for more information about handling the user PIN correctly.
Validation
The new pin always gets validated by the SDK using the PIN policy, provided on the Token Server Admin Panel. A policy can include the following elements:
- max number of similar digits
- whether sequences are allowed or not
- pin length
- blacklisted pins
Before the new PIN is passed to the SDK, you may validate the provided PIN with the policy by calling the SharedUserClient.validatePolicyCompliance
method which expects the following arguments:
pin
-String
the PIN that is going to be validated.completion
- completion block((Error?) -> Void))
that is invoked by the SDK once validation is completed. The Possible error domains are:ONGPinValidationErrorDomain
andONGGenericErrorDomain
.
Lets take a look a the sample code of validating a PIN with the PIN policy:
Error Handling
Various errors may occur during the change PIN proccess: from PIM validation to generic SDK errors.
Validate current PIN
The most common error during validating the current PIN ChangePinDelegate
userClient(:didReceivePinChallenge:)` is the
PinAuthenticationErrorInvalidPinof the
PinAuthenticationErrorDomainthat happens in case of an invalid pin. However, it doesn't complete the change
PIN flow. The SDK gives several attempts for the end-user to provide the correct PIN. The information on the max failure count and attempt count are reflected
in the
PinChallenge#maxFailureCountand
PinChallenge#previousFailureCount. In case the user has entered an invalid PIN for too many times,
the SDK deregisters the end-user and completes the change PIN flow with the
GenericErrorUserDeregisterederror of the
GenericErrorDomainand will
notify the delegate via the
ChangePinDelegate userClient(:didFailToChangePinForUser:error:)` method. When this happens you must also clean up any local
data that you might have stored about this user profile because the user is no longer registered on the device and he must register again.
Other errors such as ONGGenericErrorNetworkConnectivityFailure
or ONGGenericErrorServerNotReachable
do not affect on the PIN attempts counter and thus can
not lead to a user deregistration error.
Create PIN
During create PIN ChangePinDelegate
userClient:didReceive:` the most common errors come from the
ONGPinValidationErrorDomain.
Other errors such as
ONGGenericErrorNetworkConnectivityFailureor
ONGGenericErrorServerNotReachable` needs to be handled appropriately by notifying the
end-user about a missing internet connection.