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

Initializing Change Pin Flow

In order to start the change pin flow a user has to call the -[ONGUserClient changePin:] method, which expects the following argument:

  • delegate - the object that conforms to the ONGChangePinDelegate protocol.

Objective-C

[[ONGUserClient sharedClient] changePin:delegate];

Swift

ONGUserClient.sharedClient().changePin(delegate)

Important: The SDK should have an authenticated user (-[ONGUserClient authenticatedUserProfile] can not be nil), otherwise an error will be returned.

In case of a successful invocation the SDK will immediately notify the delegate method -[ONGChangePinDelegate userClient:didStartPinChangeForUser:] this receives the following arguments:

  • userClient - the instance of the ONGUserClient that is responsible for pin change. It is corresponds to the -[ONGUserClient changePin:] recevier.
  • userProfile - the instance of the ONGUserProfile 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 the -[ONGUserClient authenticatedUserProfile] method.

Objective-C

- (void)userClient:(ONGUserClient *)userClient didStartPinChangeForUser:(ONGUserProfile *)userProfile 
{
    // handle change pin start if needed
}

Swift

func userClient(userClient: ONGUserClient, didStartPinChangeForUser userProfile: ONGUserProfile)
{
    // handle change pin start if needed
}

However if there is no authenticated user found or something else went wrong the SDK notifies you about the raised error by calling the -[ONGChangePinDelegate userClient:didFailToChangePinForUser:error:] method. It receives the following arguments:

  • userClient - the instance of the ONGUserClient that is responsible for the PIN change. It is the same as the -[ONGUserClient changePin:] receiver.
  • userProfile - an instance of the ONGUserProfile 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 the -[ONGUserClient authenticatedUserProfile] method.
  • error - an instance of the NSError class. The Possible error domains are ONGGenericErrorDomain, ONGChangePinErrorDomain or ONGPinAuthenticationErrorDomain.

Objective-C

- (void)userClient:(ONGUserClient *)userClient didFailToChangePinForUser:(ONGUserProfile *)userProfile error:(NSError *)error
{
    // handle change pin failure
}

Swift

func userClient(userClient: ONGUserClient, didFailToChangePinForUser userProfile: ONGUserProfile, error: NSError)
{
    // handle change pin failure
}

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 -[ONGChangePinDelegate userClient:didReceivePinChallenge:] which is required. It receives the following arguments:

  • userClient - the instance of the ONGUserClient that is responsible for the PIN change. It is the same as the -[ONGUserClient changePin:] receiver.
  • challenge - an instance of the ONGPinChallenge. 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 topic guide.

Objective-C

- (void)userClient:(ONGUserClient *)userClient didReceivePinChallenge:(ONGPinChallenge *)challenge
{
    if (challenge.error) {
        //show remaining pin attempts
        NSLog(@"%d", challenge.remainingFailureCount);
    }

    // assume that we have method that dispay input and responds by either a cancel or pin
    [self presentPinViewController:^(NSString *pin, BOOL cancelled) {
        if (cancelled) {
            // user declined pin change for some reason
            [challenge.sender cancelChallenge:challenge];          
        } else {
            // provide pin to the SDK 
            [challenge.sender respondWithPin:pin challenge:challenge];    
        }
    }];
}

Swift

func userClient(userClient: ONGUserClient, didReceivePinChallenge challenge: ONGPinChallenge) 
{
    if challenge.error != nil {
        //show remaining pin attempts
        print(challenge.remainingFailureCount)
    }

    // assume that we have method that dispay input and responds by either a cancel or pin
    presentPinViewController { pin, cancelled in
        if cancelled {
            // user declined pin change for some reason
            challenge.sender.cancelChallenge(challenge)
        } else {
            // provide pin to the SDK 
            challenge.sender.respondWithPin(pin, challenge: challenge)
        }
    }
}

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 -[ONGChangePinDelegate userClient:didReceiveCreatePinChallenge:] method that receives following arguments:

  • userClient - the instance of the ONGUserClient that is responsible for the PIN change. It is the same as the -[ONGUserClient changePin:] receiver.
  • challenge - an instance of the ONGCreatePinChallenge.

Lets take a more details look at the ONGCreatePinChallenge. This class provides the required information for creating a new PIN and also a sender awaiting for the response:

  • userProfile - the instance of the ONGUserProfile for which the change PIN action was started.
  • pinLength - the required length for a new PIN.
  • error - the NSError that describes the previous failure reason (if any). Possible error domains are ONGPinValidationErrorDomain and ONGGenericErrorDomain.
  • sender - the object that conforms to the ONGCreatePinChallengeSender protocol. Once the PIN has been entered you have to provide it to the sender 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:

Objective-C

- (void)userClient:(ONGUserClient *)userClient didReceiveCreatePinChallenge:(ONGCreatePinChallenge *)challenge
{
    if (challenge.error) {
        // show error description
    }

    // assume that we have method that dispay input and responds with a new pin
    [self presentNewPinViewController:^(NSString *pin, BOOL cancelled) {
        if (cancelled) {
            // user declined pin change for some reason
            [challenge.sender cancelChallenge:challenge];          
        } else {
            // provide pin to the SDK 
            [challenge.sender respondWithPin:pin challenge:challenge];    
        }
    }];
}

Swift

func userClient(userClient: ONGUserClient, didReceiveCreatePinChallenge challenge: ONGCreatePinChallenge) 
{
    if challenge.error != nil {
        // show error description
    }

    // assume that we have method that dispay input and responds with a new pin
    presentNewPinViewController { pin, cancelled in
        if cancelled {
            // user declined pin change for some reason
            challenge.sender.cancelChallenge(challenge)
        } else {
            // provide pin to the SDK 
            challenge.sender.respondWithPin(pin, challenge: challenge)
        }
}

Note: 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 -[ONGUserClient validatePinWithPolicy:completion] method which expects the following arguments:

  • pin - NSString the PIN that is going to be validated.
  • completion - completion block (void (^)(BOOL valid, NSError * _Nullable error)) that is invoked by the SDK once validation is completed. The Possible error domains are: ONGPinValidationErrorDomain and ONGGenericErrorDomain.

Lets take a look a the sample code of validating a PIN with the PIN policy: Objective-C

[[ONGUserClient sharedClient] validatePinWithPolicy:@"1234" completion:^(BOOL valid, NSError * _Nullable error) {
    if (error) {
        // our pin is invalid

        switch (error.code) {
            case ONGPinValidationErrorPinBlackListed:
                // pin has been black listed on the TS and can not be used anymore
                break;

            case ONGPinValidationErrorPinShouldNotBeASequence:
                // pin represents a sequence which is not allowed by policy
                break;

            case ONGPinValidationErrorWrongPinLength:
                // pin lenghts is invalid (too short or too long)
                break;

            case ONGPinValidationErrorPinShouldNotUseSimilarDigits: {
                // pin uses too many similar digits. 
                NSNumber *maxSimilarDigits = error.userInfo[ONGPinValidationErrorMaxSimilarDigitsKey];
                NSLog(@"You can not use more than %@ similar digits in the pin", maxSimilarDigits);
            }
                break;

            default: 
                // we fall into generic error domain
                break;
        }
    } 
}];

Swift

ONGUserClient.sharedClient().validatePinWithPolicy("1234") { valid, error in 
    if let error = error {
        switch error.code {
            case ONGPinValidationError.PinBlackListed:
                // pin has been black listed on the TS and can not be used anymore

            case ONGPinValidationError.PinShouldNotBeASequence:
                // pin represents a sequence which is not allowed by policy

            case ONGPinValidationError.WrongPinLength:
                // pin lenghts is invalid (too short or too long)

            case ONGPinValidationError.PinShouldNotUseSimilarDigits:
                // pin uses too many similar digits.    
                if let maxSimilarDigits = error.userInfo[ONGPinValidationErrorMaxSimilarDigitsKey] as? Int {
                    print("You can not use more than \(maxSimilarDigits) in the pin")
                }

            default:
                // we fall into generic error domain
                break
        }
    }
}

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 (-[ONGChangePinDelegate userClient:didReceivePinChallenge:]) is the ONGPinAuthenticationErrorInvalidPin of the ONGPinAuthenticationErrorDomain that 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 -[ONGPinChallenge maxFailureCount] and -[ONGPinChallenge 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 ONGGenericErrorUserDeregistered error of the ONGGenericErrorDomain and will notify the delegate via the -[ONGChangePinDelegate 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 (-[ONGChangePinDelegate userClient:didReceiveCreatePinChallenge:]) the most common errors come from the ONGPinValidationErrorDomain. Other errors such as ONGGenericErrorNetworkConnectivityFailure or ONGGenericErrorServerNotReachable needs to be handled appropriately by notifying the end-user about a missing internet connection.

results matching ""

    No results matching ""