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.

Workforce Access

🚧

THIS GUIDE ASSUMES THAT YOU ALREADY HAVE THE HYPR SDK SETUP. Follow the Quick Start Setup Guide before continuing.

Overview

HYPR Workforce Access provides the means to login to or unlock a paired machine.

🚧

Limited Functionality on MacOS

Currently, it is possible to log into, but it not possible to unlock a MacOS machine using HYPR.

SDK Interface

Workforce Access uses the HYPR API Action Adapter and HYPR DB Adapter SDK interfaces.

πŸ“˜

HYPR Code Objects

The following HYPR Code Objects are used in Workforce Access mode:
HyprAppProfileData - App Profile Corresponds to a HYPR RP Server Application
HyprMachineProfileData - Machine Profile corresponds to a Machine (most likely a workstation or computer)
HyprMachineState - State of a Machine
HyprOfflineData - Object containing Offline State variables of a machine

πŸ“˜

DB IDs

Most HYPR code objects have a DB ID to uniquely identify it. The SDK interfaces often require a DB ID to indicate which object is being operated on at the time.
Workforce Access mode uses the following DB IDs:

  • App Profile DB ID
  • Machine Profile DB ID

Database Setup

From the Quick Start Setup Guide you should have created a CustomHyprDbAdapter which extends the HyprDbAdapter class.
Workforce Access mode requires a couple modifications to that custom class setup.

The additions include setting the RpAppType to WorkstationOnly, setting your RP URL, and setting your RP Application ID.

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

The complete class with 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) {
        // Workstation Access Additions
        appProfile.setHyprRpAppType(context, HyprRpAppType.WorkstationOnly);
        appProfile.setBaseDomainUrl(context, "https://your-company-hypr-rp-address.com");
        appProfile.setRpAppId(context, "your RP Application Id");

    }
}

Pair a Machine

Before a machine can be unlocked, it needs to be paired with a phone. The process can be started either by scanning a QR code, using an OOB PIN Entry, or using a Direct OOB PIN.

πŸ“˜

Initiate Pairing Options

There are three different ways to launch an Activity to initiate the pairing via the HyprApiActionAdapter:
QR Code:
HyprApiActionAdapter.addMachineToAppProfileWithQrScanner()
PIN Entry:
HyprApiActionAdapter.addMachineToAppProfileWithPinEntry()
PIN Direct:
HyprApiActionAdapter.addMachineToAppProfileWithPinDirect()

The results are returned in onActivityResults with the resultCode of:
HYPR_OOB_DEVICE_SETUP_ACT_REQ_CODE

In the example below, first check to make sure that 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. Managing App Profiles page has more information on App Profiles.

Then pass that App Profile DB ID into the addMachineToAppProfileWith* method to start a HYPR SDK activity which will perform the pairing.

The results are returned in the onActivityResult method described in the Workforce Access Activity Results section further below. The result code is HYPR_OOB_DEVICE_SETUP_ACT_REQ_CODE.

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

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

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

Get Paired Machines

To perform an action with a paired machine, its Machine DB ID is required. This method will get the list of Machines.

πŸ“˜

Get Paired Machines Method

The following is used to get the list of HyprMachineProfileDatas:
hyprAppProfileData.getHyprMachineProfileDatas()
This is a direct DB call and does not launch an Activity.

In the example below, first check to make sure that 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. Managing App Profiles page has more information on App Profiles.

From the App Profile you can get the list of Machine Profiles with the getHyprMachineProfileDatas method.

The code sample below shows how to get a full list of paired machines and their DB IDs.

List<HyprMachineProfileData> getPairedMachines(Activity activity) {
    List<HyprMachineProfileData> list = new ArrayList<>();
    if (App.isHyprInitComplete()) {
        try {
            HyprAppProfileData hyprAppProfileData = App.getHyprDbAdapter().getCurHyprAppProfileData(activity);
            list = hyprAppProfileData.getHyprMachineProfileDatas();
        } catch (HyprException exception) {
            exception.printStackTrace();
        }
    }
    return list;
}

Update and Check Machine State

A machine can be in several states. Please see status explanation below.

STATE

DESCRIPTION

INIT

This is the initial state. If a machine is in this state, it is not fully setup yet.

NO_STATUS

This is the state after a machine is fully registered, but before its state is checked.

INVALID_STATUS

There was an error checking the state.

UNLOCKED

The machine is unlocked.

UNREACHABLE

The machine is not reachable, usually because it is not connected to the internet.

LOCKED

The machine is locked.

Depending on the state of the machine, it might not make sense to start certain actions. For example, if a computer is in the UNLOCKED state, then it might not make sense to try to unlock it.

πŸ“˜

Update Machine States Method

The following is used to launch an Activity to update the Machine States in the HYPR DB via the HyprApiActionAdapter:
HyprApiActionAdapter.refreshWorkstationStatus()
The results are returned in onActivityResult with the resultCode of:
HYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE

In the example below, first check to make sure that 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. Managing App Profiles page has more information on App Profiles.

Then pass that App Profile DB ID into the refreshWorkstationStatus method to start a HYPR SDK activity which will perform the call to the HYPR Server to get the Machine States and update those statues automatically in the HYPR DB.

The success/fail results are returned in the onActivityResult method described in the Workforce Access Activity Results section further below. The result code is HYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE.

After this operation is complete and the results from onActivityResult are checked, then you can get the current Machine State from the HYPR DB. You can use the getPairedMachines method from the earlier section to get a list of Machine Profiles. Each Machine Profile will then contain the updated Machine Status.

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

void checkMachineStates(Activity activity) {
    if (App.isHyprInitComplete()) {
        List<HyprMachineProfileData> list = getPairedMachines(activity);
        for (HyprMachineProfileData machineProfileData : list) {
            String machineDbId = machineProfileData.getDbId();
            HyprMachineState machineState = machineProfileData.getMachineState();
            // update UI dependent on Machine State
        }
    }
}

Unlock a Machine

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

πŸ“˜

Unlock a Machine Method

The following is used to launch an Activity to initiate a Machine Unlock via the HyprApiActionAdapter:
HyprApiActionAdapter.unlockWorkstation()
The results are returned in onActivityResults with the resultCode of:
HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE

In the example below, first check to make sure that the HYPR Initialization is complete. Passed into the method is the Machine DB ID. You should be keeping track of Machine Profile DB IDs for your UI elements that correlate with Machines.

Then pass that Machine Profile DB ID into the unlockWorkstation method to start a HYPR SDK activity which will perform the unlock.

The results are returned in the onActivityResult method described in the Workforce Access Activity Results section further below. The result code is HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE.

void unlockMachine(Activity activity,
                   String machineDbId) {
    if (App.isHyprInitComplete()) {
        HyprApiActionAdapter.unlockWorkstation(activity, machineDbId);
    }
}

Offline Unlock

If Offline Unlock is enabled in the HYPR Control Center, a user can complete an Offline Unlock to receive a PIN that can be used to unlock their computer. This can be done regardless of whether or not the phone and/or the computer have an internet connection. The code sample below shows how to initiate an Offline Unlock and how to retrieve the offline PIN on a successful authentication.

πŸ“˜

Prerequisites

To initiate an Offline Unlock, the following must be true:

  • Offline Unlock is enabled (a check is done with the HYPR Control Center each time a standard online unlock is successfully completed)
  • At least one successful online unlock was completed (this is required because an authentication payload is needed to start an offline unlock)
  • There are unused offline pins available

Offline Unlock a Machine is done on a Machine Profile basis. Each Machine Profile has a DB ID that typically is used to pass into methods to tell the SDK which Machine Profile to use.

πŸ“˜

Offline Unlock

The following is used to launch an Activity to initiate a Machine Offline Unlock via the HyprApiActionAdapter:
HyprApiActionAdapter.offlineUnlockWorkstation()
The results are returned in onActivityResults with the resultCode of:
HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE

In the example below, first check to make sure that the HYPR Initialization is complete. Passed into the method is the Machine DB ID. You should be keeping track of Machine Profile DB IDs for your UI elements that correlate with Machines.

You should check to see if the Offline Mode Unlock is available for use via the HyprOfflineData object. The Offline Data object can be retrieved from the Machine with getHyprOfflineData. From the Offline Data object, check to see that OfflineMode is enabled, that the Machine has performed a successful online unlock already, and that there are still Offline Tokens available for use.

If those conditions pass, then pass that Machine Profile DB ID into the offlineUnlockWorkstation method to start a HYPR SDK activity which will perform the Offline Unlock PIN Retrieval.

The results are returned in the onActivityResult method. The result code is HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE.
The PIN is contained in the onActivityResult Intent data, in the HyprStatusResult object, getSuccessPayload() method. PIN Retrieval from the data object is described in the Workforce Access Activity Results section further below.

void offlineUnlock(Activity activity,
                   String machineDbId) {
    if (App.isHyprInitComplete()) {
        if (isOfflineModeAvailableAndReadyToUse(activity, machineDbId)) {
            HyprApiActionAdapter.offlineUnlockWorkstation(activity, machineDbId);
        }
    }
}

boolean isOfflineModeAvailableAndReadyToUse(Activity activity,
                                            String machineDbId) {
    try {
        HyprOfflineData offlineData = App.getHyprDbAdapter().getMachineProfileByDbId(activity, machineDbId).getHyprOfflineData();

        boolean isOfflineEnabled = offlineData.isOfflineEnabledAndSetup();
        boolean hasPerformedOnlineUnlockWithOfflineEnabled = offlineData.hasPerformedOnlineUnlockWithOfflineEnabled();
        boolean isTokensRemaining = offlineData.getTokenCountRemaining() > 0;

        return isOfflineEnabled && hasPerformedOnlineUnlockWithOfflineEnabled && isTokensRemaining;

    } catch (HyprException exception) {
        exception.printStackTrace();
        return false;
    }
}

Unpair a Computer

Unpair a Machine is done on a Machine Profile basis. Each Machine Profile has a DB ID that typically is used to pass into methods to tell the SDK which Machine Profile to use.

πŸ“˜

Unpair a Computer Method

The following is used to launch an Activity to initiate a Machine Unpair via the HyprApiActionAdapter:
HyprApiActionAdapter.deleteWorkstation()
The results are returned in onActivityResults with the resultCode of:
HYPR_DELETE_WORKSTATION_ACT_REQ_CODE

In the example below, first check to make sure that the HYPR Initialization is complete. Passed into the method is the Machine DB ID. You should be keeping track of Machine Profile DB IDs for your UI elements that correlate with Machines.

Then pass that Machine Profile DB ID into the deleteWorkstation method to start a HYPR SDK activity which will perform the unpair.

The results are returned in the onActivityResult method described in the Workforce Access Activity Results section further below. The result code is HYPR_DELETE_WORKSTATION_ACT_REQ_CODE.

void unpairMachine(Activity activity,
                   String machineDbId) {
    if (App.isHyprInitComplete()) {
        HyprApiActionAdapter.deleteWorkstation(activity, machineDbId);
    }
}

Workforce Access 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_OOB_DEVICE_SETUP_ACT_REQ_CODE:
            Toast.makeText(this, "Pairing Successful", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE:
            Toast.makeText(this, "Update Status Successful", Toast.LENGTH_SHORT).show();
            break;
            
        case HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE:
            String pinText = "";
            if (data != null && data.hasExtra(INTENT_KEY_HYPR_STATUS_RESULT)) {
                HyprStatusResult hyprStatusResult = (HyprStatusResult) data.getSerializableExtra(INTENT_KEY_HYPR_STATUS_RESULT);
                if (hyprStatusResult != null) {
                    pinText = hyprStatusResult.getSuccessPayload();
                }
            }

            if (!TextUtils.isEmpty(pinText)) {
                // Offline login was performed. Offline PIN retrieved and can be displayed by the UI.
                Toast.makeText(this, "Offline Unlock PIN Retrieval Successful", Toast.LENGTH_SHORT).show();
            } else {
                // Standard login was performed. Handle standard login success here.
                Toast.makeText(this, "Unlock Machine Successful", Toast.LENGTH_SHORT).show();
            }
            break;

        case HYPR_DELETE_WORKSTATION_ACT_REQ_CODE:
            Toast.makeText(this, "Delete Machine Successful", Toast.LENGTH_SHORT).show();
            break;

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

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

        case HYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE:
            Toast.makeText(this, "Update Status Failed", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE:
            Toast.makeText(this, "Unlock Machine Failed", Toast.LENGTH_SHORT).show();
            break;

        case HYPR_DELETE_WORKSTATION_ACT_REQ_CODE:
            Toast.makeText(this, "Delete Machine Failed", Toast.LENGTH_SHORT).show();
            break;

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

Updated 7 months ago

Workforce Access


Suggested Edits are limited on API Reference Pages

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