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

How to pair, access and unpair the workstation from your iPhone. Step-by-step guide.

In this document we'll cover how to use HyprCore iOS SDK to add workforce access functionality to your app.

Things to know about the HyprCore SDK

HYPRUserAgent Data Model

As you can see from the data model HYPRUserAgent may have multiple Profiles, each of them may have multiple userAccounts, each of them may have multiple RemoteDevices (Workstations).
In this document we'll focus on the interaction with RemoteDevices (Workstations). If your app will have workstations from more than one server or rp app id, your sdk will include more than one profile and corresponding userAccount. In this case to be able to interact with the workstation you'll have to switch the active profile and (optional) active account to match the workstation user wants to interact with. In most of the cases though each profile will have only one account and switching the profile will be enough.

// Switch profile
HYPRUserAgent.sharedInstance().switchActiveProfile(profile)
// Switch account (optional in most of the cases)
HYPRUserAgent.sharedInstance().switchActiveUserAccount(account)

Little bit more information about profiles could be found below.

Before starting the interaction with workstations

First we need to setup the SDK:

// Enable the authenticators
        HYPRUAFClient.registerAuthenticatorModule(HYPRFingerprintAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRFaceIDAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRFaceAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRPINAsm.self)
               
 // Optional: For sending/receiving HTTP Headers in HYPR SDK calls
        HYPRUserAgent.setCustomHeadersDelegate(self)
        
 // Enable or Disable SSL Pinning
        HYPRUserAgent.setSSLPinningEnabled(false)
        
 // Optional: Enable default AAID Picker UI for UserAgent
        HYPRUserAgent.setAAIDPickerViewEnabled(true)
        
 // Optional: Set AAIDPickerViewController if previous set to true
        let viewController = UIStoryboard(name:"Main", bundle: nil).instantiateViewController(withIdentifier: "PickerViewController")
        HYPRUserAgent.setAAIDPickerViewController(viewController)
        
 // Optional: Set the Face Authenticator Parameters
        HYPRFaceAsm.setTimeout(60000)

To be able to present the HyprCore UI (authenticators and AAIDPicker) we'll need to setup the presenting view controller or parent view controller as we call it in HyprCore. Depending on your app implementation it could be done once and all the HyprCore UI will be present at the same view controller, or you may need it to set each time you go to another place, for example in viewWillAppear: method:

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    HYPRUserAgent.setParentViewController(self)
}

Pairing/Registration

Before pairing the computer to your mobile app, it is required to setup the profile, which corresponds to the RP (Relying Party) Server and RP App Id. There are 2 ways to do it -

  1. License configuration. Uses the qr code or pin and lets the sdk to configure itself. It will include setting up the rp profile and the first workstation pairing.
  2. Manually. Here you'll need to specify rp url, rp app id and pair the workstation explicitly.

Here are both examples:

1) License configuration
Here we pass the nil as a key to trigger the qr code scanner presentation by the SDK. Scan the qr code presented on your workstation client and the process will start.
(as an alternative you can pass the pin to the sdk as a string, for example if user in your app enters it manually)

// Call the licenseConfiguration method with empty key parameter
HYPRUserAgent.sharedInstance().licenseConfiguration(withKey: nil) { (error) in
    // Error handling goes here
}

After the operation finishes successfully, the user will have the first rp profile and first workstation set.

2) Manually.
Create and set the profile. This procedure should be executed once per rp server/rp app id pair. You should execute it more times if user is going to pair workstation from different rp app ids/rp servers. In most of the cases your users will interact with workstations within 1 rp server/1 rp app id, so you could set it in the app delegate:

// If app profile does not exist, create a new one
if HYPRUserAgent.sharedInstance().activeProfile() == nil {
// Create the profile configuration where you specify the following:
        let profileConfig = HYPRUserAgentProfileConfiguration(rpAppId: "RP App ID here: i.e. HYPRDefaultApplication",
                                                        rpServerUrl: "Place the RP URL here: i.e. https://9999-pov.hypr.com",
                                                         deviceType: "WORKSTATION",
                                              rpSSLPinCredentials: nil,// or ssl pin credentials if you have ones and set sslPinning to true in setup
                                                     additionalData: nil)

// Create the profile with the profile configuration
        let profile = HYPRUserAgentProfile(displayName: "<Your profile name goes here>", configuration: profileConfig, persona: nil, userAccounts: nil)
            
        HYPRUserAgent.sharedInstance().registerProfile(profile!)
}

After the profile is set you can pair your first workstation via qr code scanner:

HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .qRCodeScan , actionId: "<Your policy name goes here>") { (error) in
    if(error != nil) {
        // Error handling goes here
    } 
}

In both cases user will be prompted to authenticate via matched authenticators, according to the specified policy. Policies are set on the control center per rp app id.

πŸ“˜

Make sure to create a policy that will include the desired configuration of available authenticators

In order to dictate what authenticators to use during registration, authentication, and deregistration, you'll need to create a policy. Details are provided here: iOS Policy Matching

πŸ“˜

Both types of registration can be cancelled via corresponding HYPRUserAgent method calls

HYPRUserAgent.sharedInstance().cancelLicenseConfiguration { (error) in 
        // Error handling goes here
}

HYPRUserAgent.sharedInstance().cancelRegisterRemoteDevice { (error) in 
        // Error handling goes here
}

Operations

Here are the operations which can be performed on the paired device.

1) Unlock.
It includes unlock and login (if supported and control settings has corresponding settings turned ON). From the HyprCore SDK perspective it's the same operation:

HYPRUserAgent.sharedInstance().unlock(workstation) { (error) in 
        // Error handling goes here
}

During this operation user will be prompted to authenticate according to the registered authenticators and received policy from the server

πŸ“˜

Unlock can be cancelled via corresponding HYPRUserAgent method call

HYPRUserAgent.sharedInstance().cancelUnlock(workstation, completion: { (error) in
        // Error handling goes here
})

2) Update status.
After calling this method all workstations, which belong to the active user account will have their statuses updated. You may want to call this method before trying to unlock the workstation. For example it can be already unlocked so you can notify user accordingly. Check HYPRUserAgentRemoteDevice.h class in the HyprCore framework for reference.

HYPRUserAgent.sharedInstance().updateRegisteredRemoteDevicesStatuses { (error) in
        // Error handling goes here
}

3) Local operations rename and set as default.
These changes don't affect any server-side, workstation-side settings

// Rename the workstation
let updatedWokstation = HYPRUserAgent.sharedInstance().renameRemoteDevice(workstation, withDisplayName: name)
// Set the workstation as a defaulf for active account
updatedWorksation = HYPRUserAgent.sharedInstance().setRemoteDevice(workstation, default: true)

// Also you can get the active user's default workstation:
let defaultWorkstation = HYPRUserAgent.sharedInstance().defaultRemoteDevice()?

4) Offline access
If you have the HyprCore SDK version with offline access support and it is set properly in the Control Center - your users are able to access(unlock) their workstations without the internet connection, using the offline tokens. To be able to use this functionality - they have to pair their workstation with iPhone and perform online unlock/login at least once before going offline.
There are 2 methods available:
Please also reference to HYPROfflineAccessInfo.h class in HyprCore SDK.

// Getting the offline access info
let workstationOfflineAccessInfo = try? HYPRUserAgent.sharedInstance().offlineAccessInfo(for: workstation) {
    // Present UI with obtained info if needed                    
} 

// Getting the offline access token to make user enter it on workstation instead of a password
HYPRUserAgent.sharedInstance().consumeOfflineToken(for: workstations, completion: { (token, info, error) in
        // Error handling, token presentation on UI goes here
}

During the consumeOfflineToken operation user will be prompted to authenticate according to the registered authenticators and cached policy from the server.

Deregister/Unpair

And the last thing to do is to unpair the existing workstation from the iPhone. This method takes array of the workstation as a parameter

HYPRUserAgent.sharedInstance().deregister([workstation], completion: { (error) in
        // Error handling goes here            
})

Also you may want to deregister the entire profile. In this case you'll have to create and add it next time user wants to pair the workstation. Manually or it will be created automatically via the licenseConfiguration call, as described in the beginning of the article.

HYPRUserAgent.sharedInstance().deregisterProfile(activeProfile) { (error) in
        // Error handling goes here
}

Limit the number of workstations

If you want to limit the number of the workstation user can pair, you can do it with the following method:

HYPRUserAgent.sharedInstance().setWorkstationsLimit(NSNumber(integerLiteral: 9))

Updated about a year ago

Workforce Access


How to pair, access and unpair the workstation from your iPhone. Step-by-step guide.

Suggested Edits are limited on API Reference Pages

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