FIDO Only

Do This First

This article assumes you have already completed the HYPR SDK Quick Start before continuing.

FIDO Only SDK is designed for customers who want to use the HYPR SDK to authenticate into their own application without using the HYPR out-of-band mechanism. It establishes direct communication with a HYPR RP Server / HYPR FIDO Server.

The FIDO operations available include registration, authentication, and deregistration.

SDK for Android

SDK Interface

FIDO Only Operations use the HyprApiActionAdapter and HyprDbAdapter SDK interfaces.

HYPR Code Objects

The only HYPR code object used in FIDO Only mode is HyprAppProfileData. It corresponds to a HYPR RP Application Profile.

DB IDs

Most HYPR code objects have a DB ID to uniquely identify them. The SDK interfaces often require a DB ID to indicate which object is being operated on at the time. FIDO Only mode uses the App Profile DB ID.

Basic Architecture


Interface	`HyprInit` HyprApiActionAdapter HyprDbAdapter
Related Components	`UIAdapter` User Agent FIDO Client ASMs Authenticators
Functionality	FIDO Operations

Database Setup

During the Quick Start you created a CustomHyprDbAdapter which extends the HyprDbAdapter class. FIDO Only (out-of-band Off) mode requires the following modifications to that custom class setup:

setting the Application Type, HyprRpAppType, to OobOff
setting your RP URL, BaseDomainUrl
setting your RP Application ID, RpAppId

// FIDO Only Additions
appProfile.setHyprRpAppType(context, HyprRpAppType.OobOff);
appProfile.setBaseDomainUrl(context, "https://your-company-hypr-rp-address.com");
appProfile.setRpAppId(context, "your RP Application Id");

The complete class without those additions is shown here:

public class CustomHyprDbAdapter extends HyprDbAdapter {
    /**
     * Called after a new App Profile is created.
     * Put any DB customizations here for the new App Profile.
     *
     * @param context    current context
     * @param appProfile appProfile object that was just created
     */
    @Override
    public void onNewAppProfileCreated(@NonNull final Context context,
                                       @NonNull HyprAppProfileData appProfile) {
        // FIDO Only Additions
        appProfile.setHyprRpAppType(context, HyprRpAppType.OobOff);
        appProfile.setBaseDomainUrl(context, "https://your-company-hypr-rp-address.com");
        appProfile.setRpAppId(context, "your RP Application Id");
    }
}

FIDO Registration

FIDO Registrations are done on an Application Profile basis. Each Application Profile has a DB ID that typically is used to pass into methods to tell the SDK which Application Profile to use.

FIDO Registration Method

HyprApiActionAdapter.registerAuthenticatorsForAppProfile() is used to launch an activity to initiate FIDO registration via the HyprApiActionAdapter.

The results are returned in onActivityResults with the resultCode of
HYPR_REGISTER_ACT_REQ_CODE.

Using the example below, verify the HYPR Initialization is complete. If you are only using one App Profile, get the current Application Profile and the App Profile DB ID. App Profiles has more details.
Pass that App Profile DB ID into the registerAuthenticatorsForAppProfile method to start a HYPR SDK activity which will perform the registration.

The results are returned in the onActivityResult method described in the FIDO Operation Activity Results section further below. The result code is HYPR_REGISTER_ACT_REQ_CODE.

void startRegistration(Activity activity) {
    if (App.isHyprInitComplete()) {
        try {
            HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
            HyprApiActionAdapter.registerAuthenticatorsForAppProfile(activity, hyprAppProfileData.getDbId());
        } catch (HyprException exception) {
            exception.printStackTrace();
        }
    }
}

FIDO Authentication

FIDO Authentications are done on an Application Profile basis. Each Application Profile has a DB ID that is passed to methods to tell the SDK which Application Profile to use.

FIDO Authentication Method

HyprApiActionAdapter.authenticateAppProfile() is used to launch an activity to initiate FIDO registration via the HyprApiActionAdapter.

The results are returned in onActivityResults with the resultCode of:
HYPR_AUTHENTICATE_ACT_REQ_CODE.

Using the example below, verify the HYPR Initialization is complete. If you are only using one App Profile, then get the current Application Profile and the App Profile DB ID. App Profiles has more information on App Profiles.
Pass that App Profile DB ID into the authenticateAppProfile method to start a HYPR SDK activity which will perform the authentication.
The results are returned in the onActivityResult method described in the FIDO Operation Activity Results section further below. The result code is HYPR_AUTHENTICATE_ACT_REQ_CODE.

void startAuthentication(Activity activity) {
    if (App.isHyprInitComplete()) {
        try {
            HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
            HyprApiActionAdapter.authenticateAppProfile(activity, hyprAppProfileData.getDbId());
        } catch (HyprException exception) {
            exception.printStackTrace();
        }
    }
}

FIDO Deregistration

FIDO deregistrations are done on an Application Profile basis. Each Application Profile has a DB ID that is passed to methods to tell the SDK which Application Profile to use.

FIDO Deregistration Method

HyprApiActionAdapter.deregisterAuthenticatorsForAppProfile() is used to launch an activity to initiate FIDO deregistration via the HyprApiActionAdapter.

The results are returned in onActivityResults with the resultCode of HYPR_DEREGISTER_ACT_REQ_CODE.

Using the example below, verify the HYPR Initialization is complete. If you are only using one App Profile, get the current Application Profile and the App Profile DB ID. Read App Profiles for more details.
Pass that App Profile DB ID into the deregisterAuthenticatorsForAppProfile method to start a HYPR SDK activity which will perform the deregistration.
The results are returned in the onActivityResult method described in the FIDO Operation Activity Results section. The result code is HYPR_DEREGISTER_ACT_REQ_CODE.

void startDeregistration(Activity activity) {
    if (App.isHyprInitComplete()) {
        try {
            HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
            HyprApiActionAdapter.deregisterAuthenticatorsForAppProfile(activity, hyprAppProfileData.getDbId());
        } catch (HyprException exception) {
            exception.printStackTrace();
        }
    }
}

Getting Registered Authenticators

void getRegisteredAuthenticators(Activity activity) throws HyprException {
        HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
        HyprApiActionAdapter.getRegisteredAuthenticatorsForAppProfile(activity, hyprAppProfileData.getDbId());
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if(requestCode == HYPR_ACT_GETREG_REQ_CODE) {
            if(resultCode == HYPR_ACT_RES_CODE_SUCCESS) {
                List<String> registeredAaids = new ArrayList<String>();
                if (data.hasExtra(INTENT_KEY_HYPR_STATUS_RESULT)) {
                    HyprStatusResult statusResult = (HyprStatusResult) data.getSerializableExtra(INTENT_KEY_HYPR_STATUS_RESULT);
                    HyprGetRegistrationsData registrationsData = (HyprGetRegistrationsData) statusResult.getStatusExtraData().getAuthExtraData().get(EXTRA_DATA_KEY_GET_REGISTRATIONS);
                    if (registrationsData != null) {
                        registeredAaids.addAll(registrationsData.getAaids());
                    }
                }
            }
            else {
                // Failure
            }
        }
    }

Add an Additional Authenticator to the Current User

Before you add an authenticator, ensure it is not already registered, or unexpected behaviors might result.

void addAuthenticatorToCurrentUser(Activity activity) {
        HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
        hyprAppProfileData.setRpAppActionIdReg(activity, "<your policy name>");
        HyprApiActionAdapter.registerAuthenticatorsForAppProfile(activity, hyprAppProfileData.getDbId());
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if(requestCode == HYPR_REGISTER_ACT_REQ_CODE) {
            if(resultCode == HYPR_ACT_RES_CODE_SUCCESS) {
                // Handle Success
            }
            else {
                // Handle failure
            }
        }
    }

FIDO Operation Activity Results

The results returned from all HyprApiActionAdapter operations are returned in the onActivityResults method. The standard result code returned for a successful HYPR Android SDK Operation activity result is HYPR_ACT_RES_CODE_SUCCESS.

@Override
protected void onActivityResult(int requestCode,
                                int resultCode,
                                Intent data) {
    if (resultCode == HYPR_ACT_RES_CODE_SUCCESS) {
        handleSuccess(requestCode, data);

    } else {
        handleFailure(requestCode);
    }
}

void handleSuccess(int requestCode,
                   Intent data) {
    switch (requestCode) {
        case HYPR_REGISTER_ACT_REQ_CODE:
            Toast.makeText(this, "Registration Successful", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_AUTHENTICATE_ACT_REQ_CODE:
            Toast.makeText(this, "Authentication Successful", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_DEREGISTER_ACT_REQ_CODE:
            Toast.makeText(this, "Deregistration Successful", Toast.LENGTH_SHORT).show();
            break;

        default:
            Toast.makeText(this, "Unknown Success", Toast.LENGTH_SHORT).show();
    }
}

void handleFailure(int requestCode) {
    switch (requestCode) {
        case HYPR_REGISTER_ACT_REQ_CODE:
            Toast.makeText(this, "Registration Failed", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_AUTHENTICATE_ACT_REQ_CODE:
            Toast.makeText(this, "Authentication Failed", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_DEREGISTER_ACT_REQ_CODE:
            Toast.makeText(this, "Deregistration Failed", Toast.LENGTH_SHORT).show();
            break;

        default:
            Toast.makeText(this, "Unknown Failure", Toast.LENGTH_SHORT).show();
    }
}

SDK for iOS

The FIDO Only SDK for iOS is specifically designed for clients aiming to implement SDK-based authentication directly into their own applications, without relying on out-of-band methods. This facilitates direct communication with an RP Server or HYPR FIDO Server, optimized for iOS platforms.

The FIDO operations available include registration, authentication, and deregistration.

To implement this in the HYPR SDK for iOS, you will need to perform the following steps.

Add a new target; in the HYPR iOS Reference App, we name it the MobileAppUnlock target.

The code examples will allow you to customize, show registered authenticators, register a new user, add an authenticator to a user, authenticate, deregister a user as well as deregister an authenticator.

Add three files and a interface.

Create the following files
- AppDelegate
- ViewController
- AppConfig

Starting with AppDelegate, import HyprCore and then add the following code:

import UIKit
import HyprCore

@UIApplicationMain

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
        
    internal func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        let appConfig = AppConfig(rpServerUrl: "server url",
                                rpAppId: "relying party application id",
                                registrationPolicy: "reg policy name",
                                authenticationPolicy: "auth policy name")
        
        
        HYPRWrapper.initHYPRForMobileAppUnlock(serverUrl: appConfig.rpServerUrl,
                                            relyingPartyAppId: appConfig.rpAppId,
                                            httpHeaderAdapter: httpHeaderAdapter())
        
        if let viewController = window?.rootViewController as? ViewController {
            viewController.hyprWrapper = HYPRWrapper.shared
            viewController.appConfig = appConfig
        }
        
        return true
    }
    
    func httpHeaderAdapter() -> HTTPHeaderAdapter {
        let httpHeaderAdapter = HTTPHeaderAdapter.shared
        httpHeaderAdapter.deviceInfo = DeviceInfo()
        return httpHeaderAdapter
    }
}

An important thing to note is that within the AppConfig you must add the associated details for rpServerUrl, rpAppId,registrationPolicy, and authenticationPolicy. This is a vital step that will allow the FIDO Authentication to work properly.

Next we will take a look at the AppConfig class, which corresponds with the AppDelegate we just created.

import Foundation

class AppConfig {
    
    var rpServerUrl:String
    var rpAppId:String
    var registrationPolicy:String
    var authenticationPolicy:String
    
    init(rpServerUrl: String, rpAppId:String, registrationPolicy:String, authenticationPolicy:String) {
        self.rpServerUrl = rpServerUrl
        self.rpAppId = rpAppId
        self.registrationPolicy = registrationPolicy
        self.authenticationPolicy = authenticationPolicy
    }
}

The other class we need is ViewController; this will ensure you have all the proper functions and operations needed to register and authenticate.

import UIKit
import HyprCore

class ViewController: UIViewController {
    
    var hyprWrapper: HYPRWrapperProtocol!
    var appConfig: AppConfig!
    
    @IBOutlet weak var sdkVersionNumberLabel: UILabel!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        if let version = Bundle(for: HYPRUserAgent.self).infoDictionary?["CFBundleShortVersionString"] as? String {
            sdkVersionNumberLabel.text = "v\(version)"
        }
    }

    // MARK: - HYPR Methods
    
    @IBAction func fidoOperationsTapped(_ sender: UIButton) {
        let fidoOperationOptions = UIAlertController(title: "Select FIDO Operation", message: "", preferredStyle: .actionSheet)
        
        fidoOperationOptions.addAction(UIAlertAction(title: "Register New User", style: .default, handler: { _ in
            self.registerNewUser()
        }))
        
        fidoOperationOptions.addAction(UIAlertAction(title: "Add an Authenticator", style: .default, handler: { _ in
            self.addAuthenticatorToCurrentUser()
        }))
        
        fidoOperationOptions.addAction(UIAlertAction(title: "Authenticate", style: .default, handler: { _ in
            self.authenticate()
        }))
        
        fidoOperationOptions.addAction(UIAlertAction(title: "Deregister", style: .default, handler: { _ in
            self.deregister()
        }))
        
        fidoOperationOptions.addAction(UIAlertAction(title: "Deregister Authenticator", style: .default, handler: { _ in
            self.deregisterAuthenticator()
        }))
    
        fidoOperationOptions.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: nil))
        self.present(fidoOperationOptions, animated: false, completion: nil)
    }
    
    func registerNewUser() {
        hyprWrapper.registerUser(parentViewController: self, policyName: appConfig.registrationPolicy) { error in
            if let error = error as NSError?{
                self.presentAlert(title: "Error", message: "\(error.rootError())")
            }
            else {
                self.presentAlert(title: "Success", message: "Registration Success!")
            }
        }
    }
    
    func addAuthenticatorToCurrentUser() {
        showUsersActionSheet { selectedUserAccount in
            self.hyprWrapper.addAuthenticatorToUser(parentViewController: self, userAccount: selectedUserAccount, policyName: self.appConfig.registrationPolicy) { error in
                if let error = error as NSError? {
                    self.presentAlert(title: "Error", message: "\(error.rootError())")
                }
                else {
                    self.presentAlert(title: "Success", message: "Successfully added authenticator!")
                }
            }
        }
    }
    
    func authenticate() {
        showUsersActionSheet { selectedUserAccount in
            self.hyprWrapper.authenticateUser(parentViewController: self, userAccount: selectedUserAccount, policyName: self.appConfig.authenticationPolicy) { (userInfo, error) in
                if let error = error as NSError? {
                    self.presentAlert(title: "Error", message: "\(error.rootError())")
                }
                else {
                    self.presentAlert(title: "Success", message: "Authentication Success!")
                }
            }
        }
    }
    
    func deregister() {
        showUsersActionSheet { selectedUserAccount in
            self.hyprWrapper.deregister(userAccount: selectedUserAccount) { error in
                if let error = error as NSError? {
                    self.presentAlert(title: "Error", message: "\(error)")
                }
                else {
                    self.presentAlert(title: "Success", message: "Deregistration Success!")
                }
            }
        }
    }
    
    func deregisterAuthenticator() {
        showUsersActionSheet { selectedUserAccount in
            self.showRegisteredAuthenticatorsActionSheet(userAccount: selectedUserAccount) { aaid in
                HYPRWrapper.shared.deregisterAuthenticator(withAAID: aaid, userAccount: selectedUserAccount) { error in
                    if let error = error as NSError? {
                        self.presentAlert(title: "Error", message: "\(error)")
                    }
                    else {
                        self.presentAlert(title: "Success", message: "Deregister Authenticator: \(aaid) Succeeded!")
                    }
                }
            }
        }
    }
    
    func showRegisteredAuthenticatorsActionSheet(userAccount: HYPRUserAgentAccount, onAAIDSelected: @escaping ((String) -> Void)) {
        if let registeredAuthenticators = HYPRWrapper.shared.registeredAuthenticators(forUserAccount: userAccount) {
            let registeredAuthenticatorsActionSheet = UIAlertController(title: "Registered Authenticators", message: "", preferredStyle: .actionSheet)
            for registeredAuthenticator in registeredAuthenticators {
                let aaid = registeredAuthenticator.key
                registeredAuthenticatorsActionSheet.addAction(UIAlertAction(title: aaid, style: .default, handler: { _ in
                    onAAIDSelected(aaid)
                }))
            }
            registeredAuthenticatorsActionSheet.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: nil))
            present(registeredAuthenticatorsActionSheet, animated: false, completion: nil)
        }
        else {
            self.presentAlert(title: "Error", message: "No registered authenticators for \(userAccount)")
        }
    }
    
    @IBAction func helperMethodsTapped(_ sender: UIButton) {
        let helperMethodsActionSheet = UIAlertController(title: "Select Option", message: "", preferredStyle: .actionSheet)
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Change Relying Party Endpoints", style: .default, handler: { _ in
            self.changeRelyingPartyAPIEndpoints()
        }))
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Reset App", style: .default, handler: { _ in
            self.resetApp()
        }))
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Customize Authenticator UI", style: .default, handler: { _ in
            AuthenticatorCustomizer.customizeAuthenticatorUI()
        }))
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Reset Authenticator UI", style: .default, handler: { _ in
            AuthenticatorCustomizer.resetAuthenticatorUI()
        }))
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Registered Authenticators", style: .default, handler: { _ in
            self.showRegisteredAuthenticators()
        }))
        helperMethodsActionSheet.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: nil))
        self.present(helperMethodsActionSheet, animated: true, completion: nil)
    }
    
    func showRegisteredAuthenticators() {
        showUsersActionSheet { selectedUserAccount in
            if let registeredAuthenticators = HYPRWrapper.shared.registeredAuthenticators(forUserAccount: selectedUserAccount), !registeredAuthenticators.isEmpty {
                self.presentAlert(title: "Registered Authenticators",
                                message: "\(registeredAuthenticators)")
            }
            else {
                self.presentAlert(title: "Registered Authenticators", message: "No authenticators registered")
            }
        }
    }
    
    func changeRelyingPartyAPIEndpoints() {
        hyprWrapper.changeRelyingPartyEndpoints()
    }
                        
    func resetApp() {
        hyprWrapper.resetApp { error in
            if let error = error as NSError? {
                self.presentAlert(title: "Error", message: "\(error.rootError())")
            }
            else {
                self.presentAlert(title: "Reset App", message: "Reset App Success!")
            }
        }        
    }
    
    // MARK: - Helper Methods
    private func presentAlert(title : String, message: String) {
        let alert = UIAlertController(title: title, message: message, preferredStyle: UIAlertController.Style.alert)
        alert.addAction(UIAlertAction(title: "OK", style: UIAlertAction.Style.default, handler: nil))
        self.present(alert, animated: true, completion: nil)
    }
    
    func showUsersActionSheet(onUserSelected: @escaping ((HYPRUserAgentAccount) -> Void)) {
        guard !hyprWrapper.allUsersInActiveProfile().isEmpty else {
            self.presentAlert(title: "No users to select", message: "Please register a new user")
            return
        }
        let existingUsersActionSheet = UIAlertController(title: "Select user to authenticate", message: "", preferredStyle: .actionSheet)
        for userAccount in hyprWrapper.allUsersInActiveProfile() {
            existingUsersActionSheet.addAction(UIAlertAction(title: userAccount.fidoUsername, style: .default, handler: { _ in
                onUserSelected(userAccount)
            }))
        }
        existingUsersActionSheet.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: nil))
        present(existingUsersActionSheet, animated: false, completion: nil)
    }
}

For the interface, you can create a storyboard or create another class programmatically. In the ViewController code above we have used a storyboard using IBOutlets that are connected to the storyboard; but this can easily be accomplished however you like.

SDK for Android​

SDK Interface​

Basic Architecture​

Database Setup​

FIDO Registration​

FIDO Authentication​

FIDO Deregistration​

Getting Registered Authenticators​

Add an Additional Authenticator to the Current User​

FIDO Operation Activity Results​

SDK for iOS​