HYPR Documentation Portal

HYPR is the leading provider of True Passwordless Security with millions of users deployed across the Global 2000.

Shared secrets are the #1 cause of enterprise breaches, fraud and phishing attacks.

HYPR is the first Authentication Platform designed to eliminate passwords and shared secrets - effectively removing the hackers’ primary target while eliminating fraud, phishing and credential reuse for consumers and employees across the enterprise.

FIDO Client Adapter

Overview

Describes the steps for integrating the HYPR FIDO Client Adapter into an iOS Application to facilitate decentralized registration, authentication, and deregistration.

HyprFidoClientAdapter class can be used separately from the HyprUserAgent for FIDO Client registration, authentication and deregistration operations.

Requirements:

  • HyprFidoClientAdapter is a part of the HyprCore SDK and can be used separately from HyprUserAgent
  • HYPR SDK supports the iOS 11+, iPhone 5S and all latest models.
  • Minimum deployment target - iOS 10.0
  • Valid architectures: arm64
  • Minimum Xcode version of 9.2
  • Objective-C or Swift

Project Setup instructions

  1. Copy all frameworks from the HyprFidoClientAdapterSampleApp folder to your project folder.
  1. Add all frameworks files to your Xcode project with Add Files To ...
  1. On the general tab of your project file add all frameworks to the Embedded Binaries section
  1. Set bitcode enabled = NO
  1. Set Valid Architectures = arm64

HYPR SDK frameworks are ready for usage in your Xcode project.

Running instructions

Before running the HYPR SDK version with HYPR ADP included on the device - the developer should perform 2 simple steps:

  • Go to Edit Scheme... menu
  • Uncheck the Debug executable checkmark for the appropriate target.
    The simulator works without this workaround

HYPR SDK Setup

Initialize and set the parentViewController. parentViewController will be used for presenting authenticators on it.
Also you need to register the authenticators to be used in your app before the initialization.
By default, interstitial view is enabled and if 'interstitialViewDelegate' is not set, a default interstitial view will be provided. If interstitial view is not desired, disable it by calling 'enableInterstitialView:' function.

//register authenticators
[HYPRUAFClient registerAuthenticatorModule:[HYPRFaceAsm class]];
[HYPRUAFClient registerAuthenticatorModule:[HYPRFingerprintAsm class]];
//add another ones if needed

//set custom timeout in miliseconds. 30000 is default value
[HYPRFaceAsm setTimeout:10000];

//initialize
HYPRFidoClientAdapter* adapter = [HYPRFidoClientAdapter new];
//set parent view controller
[adapter setParentViewController:self];
// disable interstitial view
[adapter enableInterstitialView:NO];
//register authenticators
HYPRUAFClient.registerAuthenticatorModule(HYPRFaceIDAsm.self)
HYPRUAFClient.registerAuthenticatorModule(HYPRFingerprintAsm.self)
//add another ones if needed

//initialize
let fidoAdapter = HYPRFidoClientAdapter()
//set parent view controller
fidoAdapter.setParentViewController(self)
// disable interstitial view
fidoAdapter.enableInterstitialView(false)

FIDO Operations

Registration

[adapter registerRequest:fidoPayload
                  completion:^(NSString * _Nullable resultString, NSError * _Nullable error) {
      //create a call to server with successPayload or handle the error
}];

//after receiving server response notify the adapter was it successful or not
NSError* error = nil;
BOOL isSuccessful = [adapter registerDidComplete:YES error:&error];
fidoAdapter.registerRequest(requestString!) { (resultString, error) in
                self.textView.text = resultString != nil ? 
                resultString : "\(String(describing: error))"
                //create a call to server with successPayload or handle the error
            }
            
//after receiving server response notify the adapter was it successful or not
let isSuccess = fidoAdapter.registerDidComplete(true)

Authentication

πŸ“˜

Note

Use the same username, as in the fidoPayload for register request

[adapter authenticateRequest:fidoPayload username:username
                  completion:^(NSString * _Nullable resultString, NSError * _Nullable error) {
      //create a call to server with successPayload or handle the error
}];

//after receiving server response notify the adapter was it successful or not
NSError* error = nil;
BOOL isSuccessful = [adapter authenticateDidComplete:YES error:&error];
fidoAdapter.authenticateRequest(requestString!, username: username!) { (resultString, error) in
                self.textView.text = resultString != nil ? 
                resultString : "\(String(describing: error))"
                //create a call to server with successPayload or handle the error
            }
            
//after receiving server response notify the adapter was it successful or not
let isSuccess = fidoAdapter.authenticateDidComplete(true)

Deregistration

πŸ“˜

Note

Use the same username, as in the fidoPayload for register request

[adapter deregisterRequest:fidoPayload username:username
                                completion:^(NSString * _Nullable resultString, NSError * _Nullable error) {
        //nothing to send to server here
}];
fidoAdapter.deregisterRequest(requestString!, username: username!) { (resultString, error) in
                self.textView.text = resultString != nil ? 
                resultString : "\(String(describing: error))"
                //nothing to send to server here
            }

Enabling HYPRADP framework

Go to HYPR ADP integration page:
https://dash.readme.io/project/hyprdev/v3.0.0/docs/hypr-adp-integration

Error Handling

Errors may occur during registration, authentication, deregistration.

HYPR SDK returns the NSError in case of an error. You can check the error code and it's localized description as in standard NSError. Also in the HyprError.h interface you can find the method in NSError category which also could be checked for error code and localized description.

-(NSError*)rootError;

Please see Error Handling for more info on the possible errors.

Offline mode

The HYPRFidoClientAdapter can perform any FIDO operations such as: registration, authentication and deregistration in offline mode.

The point of failure - facets check. If the payload includes the facets check and the facets url is not reachable of any reason in that moment and no cached facets values exist - the operation will fail.
All other cases, including:

  1. no facets url specified in payload
  2. facets are cached because of previous successful facets url check
    will work correct.

Policy handling

If SDK matches more than one set of the authenticators on registration or authentication request - the Hypr Fido Client Adapter presents the ViewController with UITableView, which include 1 set per cell. Set may include one or many authenticators. The SDK will proceed the registration or authentication process with the chosen set after it.

This feature could be turned off by passing NO to -(void)setAAIDPickerViewEnabled:(BOOL)enabled method of HyprFidoClientAdapter. Also if picker view is enabled you can enable/disable it separately for authentication with -(void)setAAIDPickerViewEnabledForAuthentication:(BOOL)enabled method.

// Enables/disables the AAID Picker for the Fido Client Adapter
-(void)setAAIDPickerViewEnabled:(BOOL)enabled;
// Enables/disables the AAID picker for authentication only if it is enabled with previous method
-(void)setAAIDPickerViewEnabledForAuthentication:(BOOL)enabled;

Implementing HYPRInterstitialDelegateProtocol

HYPRFidoClientAdapter provides the ability to specify the custom interstitialViewDelegate:

@property (nonatomic, weak) _Nullable id<HYPRInterstitialDelegateProtocol> interstitialViewDelegate;

Currently only UIAlertController is supported and the user can specify text string only. Here is the implementation example:

-(HYPRInterstitialViewModel* _Nullable)interstitialViewModelForUserInfo:(NSDictionary *)userInfo {
    HYPRInterstitialViewModel *customModel = [[HYPRInterstitialViewModel alloc] init];
    customModel.viewMode = HYPRInterstitialViewModeAlert;
    NSString *previousDescription = userInfo[kHYPRInterstitialDelegateProtocolPreviousDescription];
    NSString *nextDescription = userInfo[kHYPRInterstitialDelegateProtocolNextDescription];
    
    NSNumber *currentStep = userInfo[kHYPRInterstitialDelegateProtocolAuthenticatorIndex];
    NSNumber *totalSteps = userInfo[kHYPRInterstitialDelegateProtocolTotalAuthenticators];
    
    NSString *title = [NSString stringWithFormat:@"Step %@ of %@ Complete",
                       currentStep, totalSteps];
    
    NSString *operationString;
    if ([userInfo[kHYPRInterstitialDelegateProtocolOperation] isEqualToString:kHYPRInterstitialDelegateProtocolOperationRegistration]) {
        operationString = @"registration";
    } else if ([userInfo[kHYPRInterstitialDelegateProtocolOperation] isEqualToString:kHYPRInterstitialDelegateProtocolOperationAuthentication]) {
        operationString = @"authentication";
    } else {
        operationString = @"operation"; // fallback, but should not be used
    }
    NSString *message = [NSString stringWithFormat:@"Completed %@ for %@. Next is %@.",
                         operationString, previousDescription, nextDescription];
    
    customModel.message = message;
    customModel.title = title;
    
    return customModel;
}

If not implemented - the default implementation will be used.

Authentication failing due to Private Key Signing

Authentication can fail if the user has deleted their passcode and created a new one. In order to detect this, call the following method.

let authSigningWillSucceed = HYPRFidoClientAdapter().authenticationSignatureWillSucceedDuringAuth(forUser: "User4e442oqsbi99g31u98rprrvbc3", withFacetId: HYPRUAFClient.facetId())

Note: If you are updating from any version below 6.4.1, then you will need to update your existing users with this following method:

HYPRFidoClientAdapter.createPrivateKeysToCheckIfPasscodeSet(forUser: "User4e442oqsbi99g31u98rprrvbc3", withFacetId: HYPRUAFClient.facetId())

🚧

If the passcode was changed prior to upgrading 6.4.1, HYPRFidoClientAdapter().authenticationSignatureWillSucceedDuringAuth will not be able to detect that the passcode has changed.

Updated 4 months ago

FIDO Client Adapter


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.