Register, Authenticate, and Deregister

This page explains how to register, authenticate, and deregister a user with the HYPR API. It also shows how to deregister a specific authenticator, for example to re-add with a new PIN.

Before You Start

This document assumes that you've set up the HYPR SDK in your iOS project by following the steps on the Quick Start page.

To define which authenticators are available for use during registration, authentication, and deregistration you first need to create a policy. See HYPR SDK for IOS Policy Matching for details.

SDK for Android

Registering a User

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.

info

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.

1. 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.
2. Pass that App Profile DB ID into the registerAuthenticatorsForAppProfile method to start a HYPR SDK activity which will perform the registration.
3. 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.

register user

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

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.

info

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.

1. 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.
2. Pass that App Profile DB ID into the authenticateAppProfile method to start a HYPR SDK activity which will perform the authentication.
3. 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.

Autentication

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

Deregistration

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.

info

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

1. 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.
2. Pass that App Profile DB ID into the deregisterAuthenticatorsForAppProfile method to start a HYPR SDK activity which will perform the deregistration.
3. 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.

Deregistration

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

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

Add an Additional Authenticator

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.

FIDO Operation Activity Results

@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

Registering a User

1. Set the viewController on which the HYPR SDK for IOS UI will be presented.

2. Register the user by calling the registerUser() method. If you pass nil for the name parameter, the SDK will generate a unique name for you. The action parameter should be the exact policy name you set in the Control Center.

register user function

import HyprCore
  
class ViewController: UIViewController {
func register() {
  HYPRUserAgent.setParentViewController(self)
  HYPRUserAgent.sharedInstance().registerUser(withName: nil, action: "<policy name goes here>") { error in
    if let error = error {
      // Handle the error
    }
    else {
      // Registration is successful
    }
  }
}
}

Authenticating a User

1. Set the viewController on which the HYPR SDK UI will be presented.

2. Authenticate by calling the authenticateUser() method. If you pass nil for the name parameter, the HYPR SDK will authenticate the current user. The action parameter should be the exact policy name you set in the Control Center.

authenticate user function

import HyprCore
  
class ViewController: UIViewController {
func authenticate() {
  HYPRUserAgent.setParentViewController(self)
  HYPRUserAgent.sharedInstance().authenticateUser(nil, action: "<policy name goes here>") { error in
    if let error = error {
      // Handle the error
    }
    else {
      // Authentication is successful
    }
  }
}
}

Deregistering a User

Deregister the user by calling the deregisterUser() method. If you pass nil for the user parameter, the HYPR SDK will deregister the current user.

deregister user function

import HyprCore
  
class ViewController: UIViewController {
func deregister() {
  HYPRUserAgent.sharedInstance().deregisterUser(nil) { error in
    if let error = error {
      // Handle the error
    }
    else {
      // Deregistration is successful
    }
  }
}
}

Getting Registered Authenticators

To get a list of registered authenticators, pass the userAccount to the registeredAuthenticators() method. If you provide nil for the userAccount, the HYPR SDK will use the current active account.

The return value is a dictionary containing the authenticator attestation IDs (AAIDs) as keys and a list of every KeyId for that AAID.

HYPRUserAgent.sharedInstance().registeredAuthenticators(forUser: <userAccount>, facetId: HYPRUAFClient.facetId())

Deregistering an Authenticator

Deregister a specific authenticator by calling the deregisterAuthenticator() method. You'll need to specify the AAID you want to deregister, along with the userAccount. If you provide nil for the userAccount, the HYPR SDK will use the current active account.

HYPRUserAgent.sharedInstance().deregisterAuthenticator(withAAID: "AAID goes here", forUser: <userAccount>, facetId: HYPRUAFClient.facetId()) { error in
            if let error = error {
                // Error
            }
            else {
                // Success! Authenticator has been removed
            }
        }