Workforce Access
HYPR SDK for Android
Do This First
This article assumes you have already completed the HYPR SDK for Android Quick Start before continuing.
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 HyprDbAdapter SDK interfaces.
HYPR Code Objects
The following HYPR code objects are used in Workforce Access mode:
HyprAppProfileData
- Profile corresponding to a HYPR RP ApplicationHyprMachineProfileData
- Profile corresponding to a machine (most likely a workstation or computer)HyprMachineState
- State of a machineHyprOfflineData
- Object containing the 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
Workforce Access
This implementation involves using HYPR SDK for Android to authenticate into a workstation. This is a full HYPR implementation for direct communication with a HYPR RP Server / HYPR FIDO Server.
Interface | HyprInit HyprApiActionAdapter HyprDbAdapter |
Related Components | UIAdapter User Agent FIDO Client ASMs Authenticators |
Functionality | OOB Registration Website Authentication FIDO Operations |
Learn More
To learn more about OOB Consumer Access and how to integrate it into your app, go to the Web Authentication page.
Database Setup
During the Quick Start you created a CustomHyprDbAdapter
which extends the HyprDbAdapter
class. Workforce Access mode requires the following modifications to that custom class setup:
- Set the
HyprRpAppType
to WorkstationOnly - Set your RP URL (
BaseDomainUrl
) - Set your RP Application ID (
RpAppId
)
// 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 must be paired with a smart phone using one of the following methods:
- Scan a QR code
- Use an out-of-base PIN entry
- Use a direct out-of-base PIN
Initiate Pairing Options
Three methods exist for launching an Activity to initiate pairing via the
HyprApiActionAdapter
:
- QR Code:
HyprApiActionAdapter.addMachineToAppProfileWithQrScanner()
- PIN Entry:
HyprApiActionAdapter.addMachineToAppProfileWithPinEntry()
- PIN Direct:
HyprApiActionAdapter.addMachineToAppProfileWithPinDirect()
The results are returned in
onActivityResults
with theresultCode
ofHYPR_OOB_DEVICE_SETUP_ACT_REQ_CODE
.
-
Using the example below, verify the HYPR Initialization is complete. If only using one App Profile, get the current Application Profile and the App Profile DB ID. See App Profiles for more details.
-
Pass that App Profile DB ID into the
addMachineToAppProfileWith
method to start a HYPR SDK Activity which will perform the pairing. -
Results are returned in the
onActivityResult
method described in the Workforce Access Activity Results section below. The result code isHYPR_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 return the list of Machines.
Get Paired Machines Method
hyprAppProfileData.getHyprMachineProfileDatas()
is used to get the list ofHyprMachineProfileDatas
.This is a direct DB call and does not launch an Activity.
-
Using the example below, verify the HYPR Initialization is complete. If only using one App Profile, get the current Application Profile and the App Profile DB ID. App Profiles has more details.
-
From the App Profile, return 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. An explanation of the possible statuses follows.
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 makes no sense to unlock it.
Update Machine States Method
HyprApiActionAdapter.refreshWorkstationStatus()
is used to launch an Activity to update the Machine States in the HYPR DB via theHyprApiActionAdapter
:The results are returned in
onActivityResult
with theresultCode
of
HYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE
.
-
Using the example below, verify the HYPR Initialization is complete. If only using one App Profile, get the current App Profile and the App Profile DB ID. App Profiles has more details.
-
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 statuses automatically in the HYPR DB. -
The success/fail results are returned in the
onActivityResult
method described in the Workforce Access Activity Results section. The result code isHYPR_UPDATE_WORKSTATION_STATUS_ACT_REQ_CODE
. -
After this operation is complete and the results from
onActivityResult
are checked, obtain the current Machine State from the HYPR DB using thegetPairedMachines
method from the earlier section to get a list of Machine Profiles. Each Machine Profile will then contain the updated Machine State.
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 passed into methods to tell the SDK which Machine Profile to use.
Unlock a Machine Method
HyprApiActionAdapter.unlockWorkstation()
is used to launch an Activity to initiate a Machine Unlock via theHyprApiActionAdapter
:The results are returned in
onActivityResults
with theresultCode
of
HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE
.
-
In the example below, 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.
-
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. The result code isHYPR_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 smartphone 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 (required because an authentication payload is needed to start an offline unlock)
- There are unused offline PINs available
Offline Unlock is on a Machine Profile basis. Each Machine Profile has a DB ID that is passed to methods to tell the SDK which Machine Profile to use.
Offline Unlock
HyprApiActionAdapter.offlineUnlockWorkstation()
is used to launch an Activity to initiate a Machine Offline Unlock via theHyprApiActionAdapter
.The results are returned in
onActivityResults
with theresultCode
of
HYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE
.
-
Using the example below, verify the HYPR Initialization is complete. Machine DB ID is passed to the method. Keep track of Machine Profile DB IDs for your UI elements that correlate with Machines.
-
Check if the Offline Mode Unlock is available for use via the
HyprOfflineData
object. The Offline Data object can be retrieved from the Machine withgetHyprOfflineData
. From the Offline Data object, check to see thatOfflineMode
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 are satisfied, 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 isHYPR_LOGIN_ACT_UNLOCK_MACHINE_REQ_CODE
.
The PIN is contained in the onActivityResult
intent data, in the HyprStatusResult
object, the getSuccessPayload()
method. PIN Retrieval from the data object is described in the Workforce Access Activity Results section.
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 Machine
Unpairing a Machine is done on a Machine Profile basis. Each Machine Profile has a DB ID that is passed to methods to tell the SDK which Machine Profile to use.
Unpair a Computer Method
HyprApiActionAdapter.deleteWorkstation()
is used to launch an Activity to initiate a Machine Unpair via theHyprApiActionAdapter
.The results are returned in
onActivityResults
with theresultCode
ofHYPR_DELETE_WORKSTATION_ACT_REQ_CODE
.
-
Using the example below, check to make sure that the HYPR Initialization is complete. Passed into the method is the Machine DB ID. Keep track of Machine Profile DB IDs for your UI elements that correlate with Machines.
-
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 isHYPR_DELETE_WORKSTATION_ACT_REQ_CODE
.
void unpairMachine(Activity activity,
String machineDbId) {
if (App.isHyprInitComplete()) {
HyprApiActionAdapter.deleteWorkstation(activity, machineDbId);
}
}
Workforce Access Activity Results
Results from all HyprApiActionAdapter
operations are returned in the onActivityResults
method. The standard result code returned for a successful HYPR SDK for Android 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 4 months ago