Product: HYPR Control Center, PingFederate
Applicable Version(s): HYPR v1 or 2, On-premises

This user guide applies to version 7.9.3 of HYPRTM Integration Kit for PingFederate®.

Trademarks

The following table contains a list of trademarks that are registered with the U.S. Patent and Trademark Office in Washington, D.C. Trademarks are protected pursuant to the Lanham Trademark Act of 1946. Unauthorized use may result in penalties for trademark infringement.

Vendor Software Name Registration Definition

Ping Identity

Ping Identity, PingFederate

Ping Identity® and PingFederate® are trademarks of Ping Identity Corporation in the United States.

HYPR Corporation

HYPR

HYPR™ is a trademark of HYPR Corporation in the United States and other countries.

Apache Software Foundation

Apache Velocity

Velocity™ is a trademark of the Apache Software Foundation.

Disclaimer

The information provided in this document is provided "as is" without warranty of any kind. HYPR disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall HYPR or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits, or special damages, even if HYPR or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages, so the foregoing limitation may not apply.

Table of Contents

INTRODUCTION

    Intended Audience

    System Requirements

    Zip Manifest

    Reference Documents and Suggested Reading

AUTHENTICATION OVERVIEW

REGISTRATION CONSIDERATIONS

INSTALLATION AND SETUP

    Installing the HYPR Integration Kit

    Upgrading the HYPR Integration Kit

    Logging Configuration

    Configuring the HYPR IdP Authentication Adapter

    Configuring the HYPR Registration Adapter

    Configuring the HYPR Custom Data Store

    Configuring HYPR Password Credential Validator

CUSTOMIZING USER FACING SCREENS

NOTARY AUTHENTICATION USE CASES


INTRODUCTION

The HYPR Integration Kit utilizes PingFederate as an Identity Provider (IdP). HYPR provides an IdP Adapter which enables users to authenticate using OOB Authentication to the HYPR Mobile App via FIDO UAF or via direct FIDO2 Authentication and Password Credential Validator (PCV). The HYPR IdP Adapter should be used whenever possible, but PCV can be used in situations where using the Adapter is not possible; for example: WS-Trust, OAuth ROPC.

Intended Audience

This documentation is directed to readers who may use it in different ways:

Audience Document Use
System Administrators This document is intended for system administrators with experience in the configuration and maintenance of a PingFederate server. Knowledge of networking, user management, and HYPR software for HYPR administration is assumed.
System Architects This document provides an overview of the system interactions and architecture, which is intended for system architects with experience in the Ping Identity product ecosystem.

System Requirements

This HYPR Integration Kit is designed and supported for HYPR Control Center and compliant with the PingFederate SSO IdP Server. The HYPR Integration Kit is compliant with PingFederate v10.x and v11.x General Audience (GA) releases and PingFederate v10.x and v11.x GA releases. Refer to PingFederate documentation for the specific system requirements for the specific version of PingFederate being integrated as the target hosting platform for the HYPR Integration Kit.

Zip Manifest

The distribution .zip file for the HYPR Integration Kit contains the following items:

  • /legal – Contains legal documents
  • Legal.pdf – Copyright and license information
  • License_Agreement.pdf – Click-through agreement
  • /docs – Contains the documentation needed to setup and use the HYPR IdP Adapter
  • README – Release notes
  • HYPR-Integration-Kit-UserGuide.pdf – This document you are reading right now
  • /dist – Contains the libraries needed to implement the HYPR IdP Adapter
  • pf.adapters.hypr-7.9.3.jar – HYPR IdP Adapter plug-in for PingFederate
  • ApplessAssistant_war.war – HYPR Appless Assistant: .war file designed to help with Appless Flow (Authentication and Registration)
  • /dist/conf/language-packs – Contains the language support packs for user interfaces
  • HYPR-messages.properties – English translation for out-of-the-box user templates
  • /dist/conf/template – Contains the velocity templates needed for user interfaces
  • hypr.form.login.template.html – Login template
  • hypr.field.presence.required.template.html – Presence validation template
  • hypr.form.customTransaction.template.html – Custom transaction sample template
  • hypr.qr.code.template.html – Display QR Code template
  • hypr.form.notary.auth.html – Designed for Notary (Managed Enrollment) flow
  • hypr.appless.template.html – Displays QR code and link for Appless Flow
  • /dist/conf/template/assets/css – Contains the HYPR style sheet for velocity templates
  • hypr.css – HYPR style sheet for velocity templates
  • desktopsso.css – HYPR style sheet for velocity templates for Desktop SSO (HYPR Speed) Flow
  • /dist/conf/template/assets/scripts – Contains scripts required for FIDO2/WebAuthn
    • browserCheck.js
    • cookie.js
    • desktopSSOAuth.js
    • fetch.umd.min.js
    • hyprfido2sdk.js
    • hyprfido2sdk-compatible.js
    • polyfill.min.js
    • qrcodeutils.js
    • utils.js
    • utils-compatible.js
  • /dist/lib/
    • Jjwt-api-0.11.2.jar
    • Jjwt-impl-0.11.2.jar
    • Jjwt-jackson-0.11.2.jar

Reference Documents and Suggested Reading

The PingFederate Administrator Manual provides additional topical information.

AUTHENTICATION OVERVIEW

Five authentication options are available:

  • Push/Tap to Login
  • QR Code
  • FIDO2 (WebAuthn)
  • HYPR Speed Login
  • Appless Login

The diagrams below show high-level steps for each flow.

HYPR Push / Tap to Login Authentication Flow
HYPR_Push_Tap_to_Login.png

HYPR QR Code Login Authentication Flow
HYPR_QR_To_Login.png

 

HYPR FIDO2 (WebAuthn) Login Flow
HYPR_FIDO2_Login.png

HYPRspeed Login Flow
HYPR_Speed_to_login.png

 

Appless FlowPingFederate_Authentication_and_Registration_Flows_-_Appless.png

REGISTRATION CONSIDERATIONS

User registration can be set up through the HYPR Device Manager. For FIDO2 to work properly, HYPR Device Manager must be hosted on the same domain or host as PingFederate. For instance:

This can be achieved by using a proxy such as PingAccess to be in front of Device Manager, or in front of both Device Manager and PingFederate.

An alternative to using HYPR Device Manager is using HYPR Registration Adapter or build a custom Device Manager. HYPR Registration Adapter offers the same style of HTML template as other adapters so the UI can be easily customized with appropriate branding.

INSTALLATION AND SETUP

Integrating the HYPR IdP Adapter into a PingFederate server involves the following steps:

  • Installing the HYPR IdP Adapter libraries, language packs, and templates onto a PingFederate server
  • Configuring the HYPR IdP Adapter based on a specific use case

Installing the HYPR Integration Kit

Perform the following steps to install the HYPR IdP Adapter:

  1. Login as an administrator to the PingFederate server.
  2. Stop the PingFederate server if it is running.
  3. Change directory to the /config/WEB-INF directory and modify application.properties.
  4. (Steps 4, 5, 6 are needed only for Appless and can be skipped if Appless flow will not be used)
    Change directory to the /config directory.
  5. Make appropriate changes to the configuration file  application.properties
  6. run the following:
    zip -r -u ../dist/ApplessAssistant_war.war
  7. From the integration kit /dist directory, copy the .jar and .war files into the specified PingFederate directory.
    <PF-install>/server/default/deploy/pf.adapters.hypr-7.9.3.jar
    <PF-install>/server/default/deploy/ApplessAssistant_war.war
  8. From the Integration Kit /dist directory, copy the configuration files for language packs and templates into the specified PingFederate directory. These files do not replace existing PingFederate configuration files; rather, they are used in addition to existing configuration files.<PF-install>/server/default/conf/*
  9. Start the PingFederate server.

 

Upgrading the HYPR Integration Kit

For upgrades, first remove the previous version of HYPR Integration Kit.

  1. Remove any previous .jars into deployed:
    rm <PF-install>/server/default/deploy/pf.adapters.hypr*
  2. Copy the file from /conf/*, making sure that whatever customizations that were added are not overwritten.
  3. Diff all files that were customized from the previous adapter with the current adapter located in the /dist/conf folder.
  4. Incorporate required changes: Follow Steps 4,5,6 from Installing HYPR Integration Kit for Appless Assistant reconfiguration.  
Note:
If upgrading from 7.0.0 or earlier:
  • Back up the current PingFederate Configuration.
  • Run the following commands (or just build from scratch):
      cd pingfederate/server/default/data/config-store
    grep -rl 'com.ping.hypr.Adapter' ./ | xargs sed -i '' -e 's/com.ping.hypr.Adapter/com.ping.hypr.AuthenticationAdapter/g'
    grep -rl 'com.ping.hypr.hyprRegistrationAdapter' ./ | xargs sed -i '' -e 's/com.ping.hypr.hyprRegistrationAdapter/com.ping.hypr.RegistrationAdapter/g'
    grep -rl 'com.ping.hypr.hyprCredentialValidator' ./ | xargs sed -i '' -e 's/com.ping.hypr.hyprCredentialValidator/com.ping.hypr.CredentialValidator/g'
  • Restart PingFederate Console.
  • Manually verify that all existing configurations are visible.

Logging Configuration

Add the following lines to Log4j2.xml in the <PF-ROOT>/server/default/conf directory:

  <Logger name="com.ping.hypr" level="DEBUG" /> (For HYPR Plugin )
<Logger name="com.hypr.ping.appless.assistant" level="DEBUG" />  (For Appless Assistant)

Configuring the HYPR IdP Authentication Adapter

Perform the following steps to configure PingFederate with the HYPR IdP Authentication Adapter:

  1. Open a web browser and login to the PingFederate Administration Console.
  2. In the main menu under IdP Configuration, within the console, select Adapters.
    For more information about IdP Adapters, see the PingFederate Administrator's Manual.
  3. On the Manage IdP Adapter Instances screen, click Create New Instance.
  4. On the Type screen, enter the following values:
    • Instance Name: Choose a name for identifying the adapter instance
    • Instance ID: Internal PingFederate ID that cannot contain spaces or non-alphanumeric characters
    • Type: HYPR Authentication Adapter 7.9.3
  5. At the bottom of the Type screen, click Next.
  6. On the IdP Adapter screen, provide entries for the fields shown here:
    Field Name Description
    PINGFEDERATE BASE URL Ping Federate base URL. The trailing "/" will be ignored.
    HYPR BASE URL The base URL for the HYPR API. The trailing "/" will be ignored.
    APPLICATION ID The ID used to identify this application to the HYPR API.
    ACCESS TOKEN Access Token; configured in HYPR Control Center.
    TEST USER ID User ID for testing on the Actions Tab (optional).
    SUPPORT DESKTOP SSO (HYPRSPEED) Support Desktop SSO (HYPRspeed).
    SUPPORT DESKTOP SSO RP URL Support Desktop SSO RP URL, Leave Bank if same as HYPR base URL.
    USERNAME COOKIE DURATION The number of days the username cookie will remain active. A negative value indicates that the cookie will persist until the browser is shutdown.
    OBFUSCATE USERNAME COOKIE ENCRYPTION KEY If you want to obfuscate the username in the cookie, provide an encryption key. This will result in two values stored in a cookie: an encrypted value and an obfuscated value. Leave empty for no obfuscation.
    REGEX FOR OBFUSCATION Regex used for obfuscation. Suggested / default regex is "(?!^|.$)[^@\s]".
    OBFUSCATE USERNAME COMING FROM PRECEDING ADAPTER Obfuscate username coming from preceding adapter.
    USER ID FIELD NAME The field name for the user ID that is returned from the preceding IdP adapter in a Composite Adapter that is used for user authentication. Examples include username from an HTML Form Adapter and subject from an OpenToken Adapter or Identifer First Adapter username of Notary for Notary Authentication.
    APPLESS SUPPORT QR Appless Support QR code.
    APPLESS SUPPORT Link Appless Assistant support link.
    APPLESS ASSISTANT URL Appless Assistant URL, usually PingFederate base URL plus /ApplessAssistant_war.
    HYPR APPLESS TEMPLATE HYPR Appless template.
    IP 2 LOCATION API KEY IP two-location API Key. Used to identify location-based on IP address for Appless Authentication/Registration:
    https://www.ip2location.com/.
    USERNAME FOR SUBJECT IN THE NOTARY AUTHENTICATION FLOW The field name for the subject username during the Notary Authentication flow.
    AUTO FAIL IF DEVICES NOT REGISTERED If no devices are registered, exit the Adapter with an error.
    CHAINED ATTRIBUTE VARIABLE NAME FOR PREFERRED AUTHENTICATION METHOD Chained Attribute Variable Name for preferred authentication method; this value will be passed into the login template to invoke automatic authentication.
    AUTO FAIL IF DEVICES NOT REGISERED If no devices are registered and username edits are not allowed, cancel automatically (returns error or success based on the "Return Success on Cancel" setting).
    AUTO SUBMIT Auto Submit.
    ALLOW USERNAME EDITS Allow Username Edits.
    ALLOW USERNAME EDITS WHEN NO USERNAME AVAILABLE Allow Username Edits when no username available.
    HYPR LOGIN TEMPLATE The HTML template (in <PF-install>/server/default/conf/template) to render for a login.
    EXPOSE FIDO2 REGISTRATION STATUS Expose FIDO2 registration status.
    EXPOSE MOBILE REGISTRATION STATUS Expose mobile registration status.
    FRONT CHANNEL POLLING INTERVAL IN SECONDS Front Channel Polling Interval in seconds; Default: 3 seconds.
    OOB PUSH POLLING INTERVAL OOB Push Polling Interval in seconds; Default: 2 seconds.
    COLLECT LOCATION DATA Collect location data from mobile device whenever available. HYPR Server 7.2 and Mobile SDK 7.2 are required.
    ADAPTER INTEGRATION ERROR TEMPLATE The HTML template (in <PF-install>/server/default/conf/template) to render when an integration error occurs within the adapter. The default value of general.error.page.template.html is the PingFederate error template.
    PRESENCE REQUIRED FLAG Presence Required Flag; if checked, the user will have to go through additional checks to validate presence and avoid push fatigue attacks.
    HYPR PRESENCE REQUIRED TEMPLATE User presence confirmation template.
    NUMBER OF STRINGS Number of strings to show user to ensure presence.
    PRESENCE CONFIRMATION INSTRUCTION Presence confirmation instruction text to be sent to the user as part of the authentication (transaction).
    DEFAULT TRANSACTION TEXT Default user prompt, if empty will present either data from the template or HYPR application name. Requires that the authentication policy matches the FIDO UAF policy name. Read the comments in html.form.login.template.html to customize the transaction message.
    FIDO UAF POLICY NAME Policy Name for transaction confirmation. If empty it will result in the actionId from the form template to be used.
    Default value should be defaultAuthAction.
    The other common value is completeMediumTransaction.
    FAKE USER AUTHENTICATION Check to fake user authentication to ensure registered and unregistered user experience is the same to defend against credential harvesting.
    SUPPORT MOBILE PUSH Support mobile push. (Requires HYPR 6.13+)
    SUPPORT QR CODE Support QR code. (Requires HYPR 6.13+)
    SUPPORT LINK Support redirect link. (Requires HYPR 6.13+)
    SUPPORT FIDO2 Support FIDO2.
    ALLOW EXTERNAL AUTHENTICATORS Allow external authenticators.
    DISPLAY CANCEL OPTION Display the option to cancel.
    HYPR QR CODE TEMPLATE  
    SHOW ADVANCED FIELDS  
     
    OGNL EXPRESSION OGNL expression; for instance, #this.get("username")
    LDAPusername is the other available field.
    RETURN SUCCESS ON CANCEL Return Success on Cancel. Speak with HYPR Support about the correct value. transactionType, transactionText, and actionID will be set to either CANCEL or NOT REGISTERED or NETWORK ERROR.
    USER VERIFICATION REQUIREMENT User Verification Requirement (for WebAuthn, in beta Discouraged is not currently supported).
    ALLOW RESIDENT KEY Allow Resident Key:
    WARNING: Username provided by the key maybe different from the username provided by previous adapter or the Form.
       
    LDAP Data Store Configuration
     
    LDAP Data Source The LDAP data source used for retrieving HYPR unique user identifier and userAccountControl attributes.
    Query Directory Query Directory; if unchecked, this directory will not be searched.
    Base DN Base DN for the search.
    Filter Filter string.
    LDAP Search Scope OBJECT_SCOPE: Limits the search to the base object.
    ONE_LEVEL_SCOPE: Searches the immediate children of a base object but excludes the base object itself.
    SUBTREE_SCOPE (Default): Searches all child objects as well as the base object.
    HYPR Identifier Attribute Name HYPR unique identifier attribute in LDAP; case-sensitive (sAMAccountName).
    userAccountControl The LDAP attribute that controls user status.
  7. At the bottom of the IdP Adapter screen, click Next.
  8. (Optional) click Validate Configuration. Read the results, then click Reset
  9. (Optional) click Authenticate. Read the results, then click Reset, click Next.
  10. On the Extended Contract screen, add any desired contract extensions, then click Next.
  11. On the Adapter Attributes screen, select username as the Pseudonym, then click Next.

Six (6) attributes are available as a result of successful HYPR Authentication:

  • Username: Username as provided by the user-facing screens
  • TransactionType: Type of transaction that occurred; the value can be customized and passed as part of the template, or take on the following values:
    • "Passwordless Authentication"
    • "Presence Confirmation"
    • "Mobile Push"
    • “Mobile QR”
    • “FIDO2”
    • “CANCEL”
    • “NOT REGISTERED”
    • “NETWORK ERROR”
    • "UNEXPECTED FLOW"
    • “APPLESS”
  • TransactionText: Value can be passed in from the login template or set up as part of the adapter configuration; it can also take a value of N/A for Auth only
  • ActionId: Can be either one of the UAF Policies set up in Control Center or FIDO2 authentication flags UV/UP values flags
  • userAccountControl: if LDAP lookup was made a value indicating user status in LDAP
  • hyprUserName: username as it appears in HYPR Control Center
  1. On the Adapter Contract Mapping screen, configure desired adapter contracts, then click Next.
  2. On the Summary screen, verify the information is correct, then click Done.
  3. On the Manage IdP Adapter Instances screen, click Save to complete the adapter configuration.

Configuring the HYPR Registration Adapter

There are four ways to register to HYPR:

  • HYPR Mobile App
  • FIDO2 Platform Authenticator (Windows Hello, Touch ID, Face ID, etc.)
  • FIDO2 External Authenticator (Yubikey, Feitian, etc.)
  • Appless (Scan a QR code from mobile device)

Perform the following steps to configure PingFederate with the HYPR Registration Adapter:

  1. Open a web browser and login to the PingFederate Administration Console.
  2. In the main menu under IdP Configuration, within the console, select Adapters.
    For more information about IdP Adapters, see the PingFederate Administrator Manual.
  3. On the Manage IdP Adapter Instances screen, click Create New Instance.
  4. On the Type screen, enter the following values:
    • Instance Name: Choose a name for identifying the adapter instance
    • Instance ID: Internal PingFederate ID that cannot contain spaces or non-alphanumeric characters
    • Type: HYPR Registration Adapter 7.9.3
  5. At the bottom of the Type screen, click Next.
  6. On the IdP Adapter screen, provide entries for the fields shown here:
    Field Name Description
    PINGFEDERATE BASE URL Ping Federate base URL, no trailing "/".
    HYPR BASE URL The base URL for the HYPR API.
    APPLICATION ID The ID used to identify this application to the HYPR API.
    ACCESS TOKEN Access Token; configured in HYPR Control Center.
    TEST USER ID User ID for testing on the Actions tab (optional).
    USER ID FIELD NAME The field name for the userID returned from the preceding IdP adapter in a Composite Adapter used for user authentication. Examples include username from an HTML Form Adapter or subject from an OpenToken Adapter.
    APPLESS SUPPORT QR Appless Support QR code.
    APPLESS SUPPORT Link Appless Assistant support link.
    APPLESS ASSISTANT URL Appless Assistant URL; usually the PingFederate base URL plus /ApplessAssistant_war.
    HYPR APPLESS TEMPLATE HYPR Appless template.
    IP 2 LOCATION API KEY The HTML template (in <PF-install>/server/default/conf/template) to render for a login.
    ADAPTER INTEGRATION ERROR TEMPLATE The HTML template (in <PF-install>/server/default/conf/template) to render when an integration error occurs within the adapter.
    The default value of general.error.page.template.html is the PingFederate error template.
    SUPPORT MOBILE PUSH Support mobile push.
    SUPPORT FIDO2 Support FIDO2.
    ALLOW EXTERNAL AUTHENTICATORS Allow external authenticators.
    DISPLAY CANCEL OPTION Display the option to cancel.
    SHOW ADVANCED FIELDS  
     
    OGNL EXPRESSION OGNL Expression; for instance: #this.get("username").
    LDAPusername is the other available field.
    USER VERIFICATION REQUIREMENT User Verification Requirement (for WebAuthn, in beta Discouraged is not currently supported).
    ALLOW RESIDENT KEY Allow Resident Key:
    WARNING: Username provided by the key may be different from the username provided by the previous adapter or the form.
       
    LDAP Data Store Configuration
     
    LDAP Data Source The LDAP data source used for retrieving HYPR unique user identifier and userAccountControl attributes.
    Query Directory If unchecked, this directory will not be searched.
    Base DN Base DN for the search.
    Filter Filter string.
    LDAP Search Scope OBJECT_SCOPE: Limits the search to the base object.
    ONE_LEVEL_SCOPE: Searches the immediate children of a base object, but excludes the base object itself.
    SUBTREE_SCOPE (Default): Searches all child objects as well as the base object.
    HYPR Identifier Attribute Name HYPR unique identifier attribute in LDAP; case-sensitive (sAMAccountName).
    userAccountControl The LDAP attribute that controls user status.
  7. At the bottom of the IdP Adapter screen, click Next.
  8. (Optional) click Validate Configuration. Read the results, click Reset.
  9. (Optional) click Authenticate. Read the results, click Reset, click Next.
  10. On the Extended Contract screen, add any desired contract extensions, then click Next.
  11. On the Adapter Attributes screen, select username as the Pseudonym, then click Next.
  12. On the Adapter Contract Mapping screen, configure any desired adapter contracts, then click Next.
  13. On the Summary screen, verify the information is correct, then click Done.
  14. On the Manage IdP Adapter Instances screen, click Save to complete the adapter configuration.

Configuring the HYPR Custom Data Store

Perform the following steps to configure PingFederate with the HYPR Custom Data Store:

  1. Open a web browser and login to the PingFederate Administration Console.
  2. On the main menu under System, within the console, select Data Stores.
    For more information about Data Stores, see the PingFederate Administrator Manual.
  3. On the Data Stores screen, click Add New Data Store.
  4. On the Type screen, enter the following values:
    • Name: Choose a name for identifying the Data Store
    • Type: HYPR Custom Passwordless Data Source 7.9.3
  5. At the bottom of the Type screen, click Next.
  6. On the IdP Adapter screen, provide entries for each of the fields shown here:
Field Name Description
PINGFEDERATE BASE URL Ping Federate base URL; no trailing "/".
HYPR BASE URL The base URL for the HYPR API.
APPLICATION ID The ID used to identify this application to the HYPR API.
ACCESS TOKEN Access Token; configured in HYPR Control Center.
   
LDAP Data Store Configuration
 
LDAP Data Source The LDAP data source used for retrieving HYPR unique user identifier and userAccountControl attributes.
Query Directory Query Directory; if unchecked, this directory will not be searched.
Base DN Base DN for the search.
Filter Filter string.
LDAP Search Scope OBJECT_SCOPE: Limits the search to the base object.
ONE_LEVEL_SCOPE: Searches the immediate children of a base object, but excludes the base object itself.
SUBTREE_SCOPE (Default): Searches all child objects as well as the base object.
HYPR Identifier Attribute Name HYPR unique identifier attribute in LDAP; case-sensitive (sAMAccountName).
userAccountControl The LDAP attribute that controls user status.
  1. At the bottom of the Data Store screen, click Next.
  2. At the bottom of the Summary screen click Save.

Whenever using custom HYPR data source, use the filter string in the following format: ${subject}.

Configuring HYPR Password Credential Validator

Considerations:
HYPR Credential Validator does not actually validate a password, but rather it ensures through push notification that the user wants to authenticate. Credential Validator is useful for back channel flows such as ROPC or WS-Trust, or to easily plug into existing policies with minimum changes.
User’s username will be used to send a push notification to a HYPR app. The user will then authenticate to HYPR using FIDO UAF, and it will return success or failure to the PCV. The PCV will then proceed with the policy.

Perform the following steps to configure PingFederate with the HYPR Custom Data Store:

  1. Open a web browser and login to the PingFederate Administration Console.
  2. In the main menu under System, within the console, select Password Credential Validator.
    For more information about Password Credential Validators, see the PingFederate Administrator Manual.
  3. On the Password Credential Validator screen, click Add New Instance.
  4. On the Type screen, enter the following values:
    • Instance Name: Choose a name for identifying the Password Credential Validator
    • Instance ID: Choose an ID for identifying the Password Credential Validator
    • Type: HYPR Password Credential Validator 7.9.3
  5. At the bottom of the Type screen, click Next.
  6. On the IdP Adapter screen, provide entries for the fields shown here:
Field Name Description
HYPR BASE URL The base URL for the HYPR API.
APPLICATION ID The ID used to identify this application to the HYPR API.
ACCESS TOKEN Access Token; configured in HYPR Control Center.
DEFAULT TRANSACTION TEXT Default user prompt. If empty, it will present either data from the template or HYPR application name; requires that Authentication Policy matches the FIDO UAF Policy.
FIDO UAF POLICY NAME Policy Name for transaction confirmation. If empty, it will result in the actionId from the form template to be used.
Default value is defaultAuthAction.
The other common value is completeMediumTransaction.
   
LDAP Data store Configuration
 
LDAP Data source The LDAP data source used for retrieving hypr unique user identifier and userAccountControl attributes.
Query Directory Query Directory; if unchecked, this directory will not be searched.
Base DN Base DN for the search.
Filter Filter string.
LDAP Search Scope OBJECT_SCOPE: Limits the search to the base object.
ONE_LEVEL_SCOPE: Searches the immediate children of a base object but excludes the base object itself.
SUBTREE_SCOPE (Default): Searches all child objects as well as the base object.
HYPR identifier attribute name HYPR unique identifier attribute in LDAP; case-sensitive (sAMAccountName).
userAccountControl The LDAP attribute that controls user status.
  1. At the bottom of the Password Credential Validator screen, click Next.
  2. At the bottom of the Summary screen click Save.

CUSTOMIZING USER-FACING SCREENS

All user facing screens are customizable using velocity templates. All templates’ variables are documented in the velocity templates, including creating custom transaction text used as start for push notification, transaction type and Action Id (UAF Policy Name). There are also a number of functions that can be envoked while customizing existing java script or from your own. 

Here are some examples:

  • postBack() – Takes user to the original screen no auto submit
  • postBackandFIDO2() – Restart and autosubmit FIDO2
  • postBackandMobilePush() – Restart and autosubmit mobile push
  • postBackandMobileQR() – Restart and autosubmit mobile QR
  • postCancel() – Exits adapter with “CANCEL”
  • postDenied() – Exits adapter with “DENIED”

NOTARY AUTHENTICATION USE CASES

Notary Authentication is an authorizing another user to authenticate, one example of that is a managed enrollment flow. In a managed enrollment flow a user (notary subject) is requesting another user (notary) to authenticate for them, in order to complete a transaction such as registration. Notary will need to have appropriate access and or permissions to authenticate on the user’s behalf. This flow can be extended to require multiple notaries to provide additional security.

In the flow below there are two personas:

  • Notary subject: User trying to register for HYPR passwordless authentication
  • Notary User approving the authentication

Managed Enrollment Authentication Flow Diagram

Managed_Enrollment_Flow.png

Managed Enrollment Authentication Flow Steps:

Setting Up Managed Enrollment

  1. Setup the Identifier First Adapter. This will request the user to submit their username.
    • Choose a different template (identifier.first.template.html) to customize the look and feel (optional)
    • Extend the contract with notarySubjectUsername
    • Under Adapter Contract Mapping, choose the following expression for notarySubjectUsername: #this.get("subject")
  2. Setup the second Identifier First Adapter: notaryIdentifier. This will request the user to submit approver’s username.
    • Choose a different template (notary.subject.template.html) to customize the look and feel (optional)
    • Extend the contract with notaryUsername
    • Under Adapter Contract Mapping, choose the following expression for notaryUsername: #this.get("subject")
  3. Setup a composite adapter subject and notaryIdentifier:
    • Put Identifer First as the first adapter (required)
    • Put notaryIdentifer as the second (required)
    • Extend the contract with
      • notarySubjectUsername
      • notaryUsername
    • Customize Issuance Criteria according to custom rules (who is allowed to approve whom)
  4. Create the HYPR Authentication Adapter overriding the following fields from other Authentication Adapter you might have already set up:
    • Support Desktop SSO: “”
    • Obfuscate username Cookie Encryption Key: “”
    • Obfuscate username Cookie From Preceding Adapter: “”
    • UserId Field Name: notaryUsername
    • Username For Subject in the Notary Authentication Flow: notarySubjectUsername
    • Chained Attribute Variable Name for Preferred Authentication Method
    • Auto Submit: “”
    • Hypr Login Template: hypr.form.notary.auth.template.html (You can customize this template to provide an appropriate look and feel)
    • Presence Required Flag: “check”
    • Presence Confirmation Instruction: Authenticate ${NOTARY_SUBJECT_USERNAME}
    • Support QR: “”
    • Supprt Link: “”
    • Support Fido2: “”
  5. Create an authentication policy or a composite Adapter where the composite Adapter is followed by the HYPR Authentication Adapter created in the previous section.

This video provides an overview of the HYPR and PingFederate integration.

Was this article helpful?
7 out of 8 found this helpful