HYPRUserAgent Data Model

The data model for HYPR SDK for iOS, HYPRUserAgent, operates with the following main instances:

• UserAgent

• Profile

• UserAccount

• RemoteDevice

These objects represent the website in the web flow and Windows/iOS workstations in the employee flow. Details can be found in the following sections.

• UserAgent contains the list of each Profile

• Each Profile contains the list of UserAccounts; currently HYPR SDK for iOS supports one UserAccount per Profile; manually adding more than one UserAccount to the Profile can cause unpredicted behavior

• Each UserAccount contains the list of RemoteDevices; there is always one RemoteDevice per UserAccount for the web flow and any number of RemoteDevices for the employee flow

UserAgent

UserAgent is a singleton object instance of the HYPRUserAgent class. It is the main point of interaction with HYPR SDK for iOS.

[HYPRUserAgent sharedInstance];

The full interface is described in Getting Started. This object provides you all methods needed to setup and use the HYPR SDK for iOS. It includes but is not limited to licensing flow, registration, creation, modifying, removing, deregistering of profiles, accounts and remote devices. More details are provided in following section.

Profiles

UserAgent contains the list of each Profile – instances of HYPRUserAgentProfile class.
Profile represents the Relying Party server. It includes the server settings and configuration associated with the userAccount.

/**
 Profiles which have been registered.

 @return List of currently registered profiles. May be empty if no profiles have been registered.
 */
-(NSArray<HYPRUserAgentProfile*>* _Nullable)profiles;
/**
 Provides the currently active profile.

 @return Profile object with app configuration parameters. `nil` if no profiles are registered or have been selected.
 */
-(HYPRUserAgentProfile* _Nullable)activeProfile;

Here is the HYPRUserAgentProfile interface:

@interface HYPRUserAgentProfile : NSObject <NSCopying, NSCoding>

/**
 * User-facing description for this Profile. May be modified by the user.
 */
@property (nonatomic, readonly, copy) NSString *displayName;
/**
 * Configuration information for this profile
 */
@property (nonatomic, readonly, copy) HYPRUserAgentProfileConfiguration *configuration;
/**
 * Persona is a unique identifier to separate users across Profiles. This must be shared with the ASM.
 */
@property (nonatomic, readonly, copy) HYPRUserAgentPersona *persona;
/**
 * List of registered User Accounts in this Profile.
 */
@property (nonatomic, readonly, copy) NSArray<HYPRUserAgentAccount*> *userAccounts;

+ (instancetype)new NS_UNAVAILABLE;

- (instancetype)init NS_UNAVAILABLE;

- (instancetype)initWithDisplayName:(NSString *)displayName configuration:(HYPRUserAgentProfileConfiguration *)configuration persona:(HYPRUserAgentPersona *)persona userAccounts:(NSArray<HYPRUserAgentAccount*> *)userAccounts;

@end

Configuration includes server-related information, as described below:

Property	Type	Description
rpAppId	NSString	The Relying Party Application ID for this configuration.
rpServerUrl	NSString	The HYPR Relying Party Server URL.
deviceType	NSString	Remote device type.
rpSSLPinCredentials	NSArray	Relying Party Server SSL Pinning Credentials. Provide at least two credentials to enable SSL Pinning (current key and backup).
additionalData	NSDictionary	Additional data.

Example

@interface HYPRUserAgentProfileConfiguration : NSObject <NSCopying, NSCoding>

/**
 * The Relying Party App ID for this configuration
 */
@property (nonatomic, readonly, copy) NSString *rpAppId;
/**
 * The HYPR Relying Party Server URL
 */
@property (nonatomic, readonly, copy) NSString *rpServerUrl;
/**
 * Profile type. Corresponds to remote devices type of this profile. Can be "WEB", "WORKSTATION"
 */
@property (nonatomic, readonly, copy) NSString *deviceType;
/**
 * Relying Party Server SSL Pinning Credentials. Provide at least two credentials to enable SSL Pinning (current key and backup).
 */
@property (nonatomic, readonly, copy) NSArray<HYPRSSLPinCredential*> *rpSSLPinCredentials;
/**
 * Contents of the rest of the configuration TBD
 */
@property (nonatomic, readonly, copy) NSDictionary *additionalData;
/**
 * Set UI Configuration for each of the Authenticator Screens
 * The dictionary maps an NSNumber key to a HYPRAuthenticatorViewConfiguration
 * The key will come from the HYPRAuthenticatorViewConfiguration's key property
 */
@property (nonatomic, readonly, copy) NSArray<HYPRAuthenticatorViewConfiguration*> *authenticatorViewConfigurations;

- (instancetype)initWithRpAppId:(NSString *)rpAppId rpServerUrl:(NSString *)rpServerUrl deviceType:(NSString *)deviceType rpSSLPinCredentials:(NSArray<HYPRSSLPinCredential*> *)rpSSLPinCredentials additionalData:(NSDictionary *)additionalData authenticatorViewConfigurations:(NSArray<HYPRAuthenticatorViewConfiguration*> *)authenticatorViewConfigurations;

+ (instancetype)new NS_UNAVAILABLE;

- (instancetype)init NS_UNAVAILABLE;
@end

Persona includes personaId to uniquely identify Profile, among others.

UserAccount

To retrieve the UserAccount of the activeProfile call:

/**
 Get the active user account

 @return the active user account
 */
-(HYPRUserAgentAccount*)activeUserAccount;

HYPRUserAgent Method

UserAccount represents the single user record in HYPR. It's also linked to the FIDO username. All FIDO operations (registration, authentication, and deregistration) are handled inside HYPRUserAgent.

@interface HYPRUserAgentAccount : NSObject <NSCopying, NSCoding>

/**
 * User-facing description of the user account. May be modified by the user.
 */
@property (nonatomic, readonly, copy) NSString *displayName;
/**
 * FIDO-specific username. Should be unique.
 */
@property (nonatomic, readonly, copy) NSString *fidoUsername;
/**
 * List of Remote Devices associated with this user account.
 */
@property (nonatomic, readonly, copy) NSArray<HYPRUserAgentRemoteDevice*> *remoteDevices;
/**
 * Set API Version of Relying Party
 * This value may change later as part of version negotiation 
 * Version 1 supports device registration, unlock, and de-registeration.
 * Version 2 and above supports device registration, unlock/login , and de-registeration.
 */
@property (nonatomic, readonly, copy) NSNumber *currentAPIVersion;

+ (instancetype)new NS_UNAVAILABLE;

- (instancetype)init NS_UNAVAILABLE;

- (instancetype)initWithDisplayName:(NSString *)displayName fidoUsername:(NSString *)fidoUsername remoteDevices:(NSArray<HYPRUserAgentRemoteDevice*> *)remoteDevices currentAPIVersion:(NSNumber *)currentAPIVersion;

@end

remoteDevice

The list of remote devices associated to the activeUserAccount can be retrieved by calling remoteDevice, which represents a single workstation or "website instance" in HYPR SDK for iOS.

/**
 Get the list of currently registered Remote Devices for the active User Account.

 These objects may be passed to the other Remote Device methods to perform operations (eg. unlock, unregister) for them.

 @return list of Remote Devices registered to the active user account.
 */
-(NSArray<HYPRUserAgentRemoteDevice*>* _Nullable)registeredRemoteDevices;

HYPRUserAgent Method

Here is the HYPRUserAgentRemoteDevice interface:

typedef NS_ENUM(NSUInteger, HYPRWorkstationStatus) {
    HYPRWorkstationStatusUnlocked,     /// workstation is unlocked.
    HYPRWorkstationStatusLocked,       /// workstation is logged in and locked.
    HYPRWorkstationStatusUnreachable,  /// workstation is unreachable by the rp.
    HYPRWorkstationStatusAsleep,       /// workstation is in hibernation.
    HYPRWorkstationStatusUnregistered, /// workstation is unregister, but this should never happen.
    HYPRWorkstationStatusUnknown,      /// an unknown status message has been return.
};

@interface HYPRUserAgentRemoteDevice : NSObject <NSCopying, NSCoding>

/**
 * Unique device identifier provided during Device Setup.
 */
@property (nonatomic, readonly, copy) NSString *deviceIdentifier;
/**
 * User-friendly, display name for this device. may be customized by the user.
 */
@property (nonatomic, readonly, copy) NSString *displayName;
/**
 * The machine name associated with this Remote Device
 */
@property (nonatomic, readonly, copy) NSString *deviceName;
/**
 * TBD. Currently 2 values supported:"WEB", "WORKSTATION"
 */
@property (nonatomic, readonly, copy) NSString *deviceType;
/**
 * The username associated with this Remote Device
 */
@property (nonatomic, readonly, copy) NSString *deviceUsername;
/**
 * Optional, actionIds for operations. Typically contains keys for default registration and authentication.
 */
@property (nonatomic, readonly, copy) NSDictionary<NSString*,NSString*> *actionIds;
/**
 * Status message of the workstation, received from StatusRequest. Can have following values: 'LOCKED', 'UNLOCKED', 'UNREACHABLE', 'UNREGISTERED', 'ASLEEP'
 */
@property (nonatomic, readonly, copy) NSString *statusMessage;

@property (readonly) HYPRWorkstationStatus status;

/**
 * API version 
 */
@property (nonatomic, readonly, copy) NSNumber *apiVersion;

+ (instancetype)new NS_UNAVAILABLE;

- (instancetype)init NS_UNAVAILABLE;

- (instancetype)initWithDeviceIdentifier:(NSString *)deviceIdentifier displayName:(NSString *)displayName deviceName:(NSString *)deviceName deviceType:(NSString *)deviceType deviceUsername:(NSString *)deviceUsername actionIds:(NSDictionary<NSString*,NSString*> *)actionIds statusMessage:(NSString *)statusMessage apiVersion:(NSNumber *)apiVersion;

@end

Status and statusMessage are applicable to the remoteDevice type WORKSTATION only.

Profile Operations

Additionally you can register a profile created on your own, switch active profile, deregister, or rename a profile using HYPRUserAgent methods:

/**
 Register a configured profile for use with HYPRCore.

 This method is primarily intended for applications which directly configure Profiles rather than dynamically configure them via the HYPR Licensing server.

 @param newProfile The configured profile with Relying Party URL, App ID, SSL Pinning credentials and additional configuration.
 */
-(void)registerProfile:(HYPRUserAgentProfile*)newProfile;

/**
 Switch the active profile to the specified value.

 @warn The provided profile *must* already be registered with the User Agent.

 Switching profiles will also invalidate the active user account.
 After switching, you may read the profile's configuration to re-configure the host application as needed.

 @param profile The profile the User Agent should make active.
 @return YES if the profile is valid and the User Agent could switch to it. NO if the profile is not registered.
 */
-(BOOL)switchActiveProfile:(HYPRUserAgentProfile*)profile;

/**
 Remove the specified profile from the User Agent
 
 @warn this will deregister any user accounts associated with the profile and workstations/web assosisated with accounts.
 
 @param profile The profile to unregister.
 @param completion Callback with the result of the operation.
 */
-(void)deregisterProfile:(HYPRUserAgentProfile*)profile completion:(HYPRUserAgentGenericResult _Nullable)completion;

/**
 Rename the provided profile.

 @note If this method returns an updated profile, then the profile list has been updated and should be re-loaded to retrieve the current values.

 @param profile The profile to update
 @param displayName A new display name for this profile.
 @return Updated profile. `nil` if the profile was not found in this User Agent.
 */
-(HYPRUserAgentProfile* _Nullable)renameProfile:(HYPRUserAgentProfile*)profile withDisplayName:(NSString*)displayName;

You should switch active profiles each time before performing any operation on its account or remoteDevices.

Deregistering the profile will de facto deregister all associated workstations, accounts, and FIDO registrations.

Account Operations

Register a new user with a name, reregister userAccount, deregister userAccount, and authenticate userAccount using HYPRUserAgent methods. All operations will be performed on the active profile. If the active profile doesn't include this userAccount, operations will fail.

/**
 Register a new user with the FIDO Server.

 @param userName (Optional) user name which will be used for this user with the FIDO Server. Should be unique. Pass `nil` to allow the User Agent to generate a username.
 @param actionId (Optional) action which should be used for this registration. Must be one of the defined values in the current Profile Configuration (TBD). Pass `nil` to perform the default action.
 @param completion Callback with the result of the operation.
 */
-(void)registerUserWithName:(NSString * _Nullable)userName action:(NSString * _Nullable)actionId completion:(HYPRUserAgentGenericResult)completion;

/**
 Re-register an existing User Account with the FIDO Server

 This may be used to add additional authenticator registrations and/or biometric enrollments for an existing user account.

 @param userAccount The user account which should be registered. Pass `nil` to use the activeUserAccount.
 @param actionId (Optional) action which should be used for this registration. Must be one of the defined values in the current Profile Configuration (TBD). Pass `nil` to perform the default action.
 @param completion Callback with the result of the operation.
 */
-(void)registerUser:(HYPRUserAgentAccount * _Nullable)userAccount action:(NSString * _Nullable)actionId completion:(HYPRUserAgentGenericResult)completion;

/**
 Deregister the specified user from the FIDO Server

 @warn This is a destructive action; credentials registered to this user will be deleted.

 @param userAccount The user account which should be deregistered. This user account will be removed from the current Policy.
 @param completion Callback with the result of the operation.
 */
-(void)deregisterUser:(HYPRUserAgentAccount* _Nullable)userAccount completion:(HYPRUserAgentGenericResult)completion;

/**
 Authenticate a user with the Relying Party configured by the current Profile.

 @param userAccount The user account which should be used for authentication. Pass `nil` to use the activeUserAccount
 @param actionId (Optional) action which should be authenticated. Must be one of the defined values in the current Profile Configuration (TBD). Pass `nil` to perform the default action.
 @param completion Callback with the result of the operation.
 */
-(void)authenticateUser:(HYPRUserAgentAccount* _Nullable)userAccount action:(NSString * _Nullable)actionId completion:(HYPRUserAgentGenericResult)completion;

Deregistering the userAccount will also deregister all associated workstations and FIDO registrations.

Remote Device Operations

Using HYPRUserAgent methods:

• register remoteDevice

• check remoteDevice status

• unlock/cancel unlock for remoteDevice

• rename remoteDevice- set remoteDevice as default

• deregister remoteDevice

All operations will be performed with activeProfile. You have to switchActive profile before performing any operations. If the remoteDevice cannot be found within activeUserAccount's remoteDevice, the operation will fail.

Check status, unlock, and cancel unlock are applicable for remoteDevice of type "WORKSTATION" only.

/**
 Register a new Remote Device

 @param userAccount the User Account to associate with this Remote Device. Pass `nil` to create a new User Account during device setup.
 @param pin the PIN received from the remote device. Pass `nil` to be prompted for the pin through an alert.
 @param actionId Must be one of the defined values in the current Profile Configuration (TBD). Pass `nil` to perform the default action.
 @param completion handler called upon completion of the device setup operation.
 */
-(void)registerRemoteDeviceForUser:(HYPRUserAgentAccount* _Nullable)userAccount pin:(NSString* _Nullable)pin actionId:(NSString* _Nullable)actionId completion:(HYPRUserAgentGenericResult)completion;

/**
 Update statuses for registered remote devices of current active user account
 
 @note call registeredRemoteDevices method on success to get the updated instances of remote devices
 @param completion handler called upon completion of the device setup operation.
 */
-(void)updateRegisteredRemoteDevicesStatusesForCurrentUserAccountWithCompletion:(HYPRUserAgentGenericResult)completion

/**
 Unlock the specified Remote Device
 
 @note This device must be owned by the active User Account.
 
 @param remoteDevice the Remote Device which should be unlocked.
 @param completion handler called upon completion of the device unlock operation.
 */
-(void)unlockRemoteDevice:(HYPRUserAgentRemoteDevice*)remoteDevice completion:(HYPRUserAgentGenericResult)completion;

/**
 Unlock the specified Remote Device with API specific handlers

 @note This device must be owned by the active User Account.

 @param remoteDevice the Remote Device which should be unlocked.
 @param eventBlock called upon completion of the device unlock operation and the device unlock complete operation.
 @note  Possible event values include:
        HYPRAPIEventResultFailure
        HYPRAPIEventResultAuthenticate
        HYPRAPIEventResultUnlock
        HYPRAPIEventResultComplete
 */
-(void)unlockRemoteDevice:(HYPRUserAgentRemoteDevice*)remoteDevice eventBlock:(HYPRUserAgentEventResult)eventBlock;

/**
 Update the display name for the provided Remote Device

 @note This device must be owned by the active User Account
 @note If an updated remote device is returned, then the current Profile has been updated and should be reloaded to display the current version.

 @param remoteDevice the Remote Device which should be renamed
 @param displayName the desired display name for the Remote Device
 @return an update instance of the Remote Device. `nil` if the Remote Device was not found in the active User Account.
 */
-(HYPRUserAgentRemoteDevice * _Nullable)renameRemoteDevice:(HYPRUserAgentRemoteDevice*)remoteDevice withDisplayName:(NSString*)displayName;

/**
 Set the chosen Remote Device as the Default Remote Device
 
 @note This device must be owned by the active User Account
 @note If an updated remote device is returned, then the current Profile has been updated and should be reloaded to display the current version.
 
 @param remoteDevice the Remote Device which should be renamed
 @param isDefault Setting this value to YES will lead to setting this value to YES to current remote device and to NO for all other remove devices
 @return same instance of the Remote Device. `nil` if the Remote Device was not found in the active User Account.
 */
-(HYPRUserAgentRemoteDevice * _Nullable)setRemoteDevice:(HYPRUserAgentRemoteDevice * _Nonnull)remoteDevice default:(BOOL)isDefault;

/**
 Return the current default remote device
 
 @note This device must be owned by the active User Account
 
 @return a remote device, which was set to defaulf for the current user. nil if there is no default device for the current user
 */
- (HYPRUserAgentRemoteDevice * _Nullable)defaultRemoteDevice;


/**
  Cancel the unlock request previously completed for a remote device.
 
  @note This device must be owned by the active User Account.
 
 @param remoteDevice the Remote Device which should be unlocked.
 @param completion handler called upon completion of the device unlock operation.
 */
-(void)cancelUnlock:(HYPRUserAgentRemoteDevice*)remoteDevice completion:(HYPRUserAgentGenericResult)completion;

/**
 Unregister the specified Remote Devices locally and remotely

 @note The Remote Devices must be owned by the active user account and belong to the current active profile.

 @param remoteDevices the Remote Devices which should be removed indicated by the deviceIdentifier field.
 @param completion handler called upon completion of the deregister operation.
 */
-(void)deregisterRemoteDevices:(NSArray<HYPRUserAgentRemoteDevice*>*)remoteDevices completion:(HYPRUserAgentGenericResult)completion;

Limiting Relying Party Profiles and Workstations

Set a limit to the number of RP profiles by calling the following UserAgent method:

/**
 Limit the number of profiles of specific type allowed. By default no limit is set.
 @param limit limits the maximum number of profiles of the specified type. Set nil to remove the limit.
 @param profileType of HYPRUserAgentProfileType enum.
 */
-(void)setLimit:(NSNumber* _Nullable)limit forProfilesOfType:(HYPRUserAgentProfileType)profileType;

With one of the two values:

typedef NS_ENUM(NSUInteger, HYPRUserAgentProfileType) {
    HYPRUserAgentProfileTypeWeb,            //Registered web profiles
    HYPRUserAgentProfileTypeWorkstation     //Registered workstation profiles
};

To limit the number of workstations (not related to the web profile remote devices):

/**
 Limit the number of workstations of specific type allowed. By default no limit is set.
 @param limit limits the maximum number of workstations across all workstation profiles.  Set nil to remove the limit.
 */
-(void)setWorkstationsLimit:(NSNumber* _Nullable)limit;