HYPR – Maverics Identity Orchestration Platform

HYPR

The HYPR Connector manages authentication requests to the HYPR platform. These requests could be “passwordless” with no other IDP providing primary identity information, or they can be used as a second factor in conjunction with another Identity Provider.

This connector manages the user’s authentication experience in the browser with three different pages:

an interface for the user to provide their username if HYPR is used as a passwordless first factor
an interstitial page displayed while waiting for the user’s response to the HYPR platform
an error page for exceptional conditions

Each of these have a default implementation, but you can provide customized pages or completely change the user’s interactions via Service Extension.

Configuration options

The following values are used to configure the HYPR connector via the Orchestrator configuration file.

Name

name is used to reference this connector elsewhere in config.

HYPR Domain

hyprDomain is the base domain of the HYPR account.

HYPR App ID

hyprAppID is the name of the application as defined in the HYPR Control Center.

MFA Only (optional)

mfaOnly is used when HYPR is used in conjuction with another identity provider as a second factor, and not as a passwordless primary IDP.

Access Token

accessToken is the access token configured in the HYPR Control Center. This is sensitive information which should be retrieved from a secret provider in production environments.

Status Check URL (optional)

statusCheckURL is used by the interstitial page to poll for status while waiting for the user to complete the authentication on their device. This endpoint is hosted by the Orchestrator, so the domain specified should resolve to a domain the Orchestrator hosts. It can also be set as a relative path. In either case, it must not conflict with any paths to protected applications. If unset, the value /.hypr-status-check will be used.

ℹ️

When specifying a statusCheckURL, use absolute (full) URL including scheme, hostname, and path to ensure status requests are routed correctly. Always specify custom statusCheckURL value if the routePattern includes a hostname.

For example, if the routePattern is defined as follows:

routePatterns:
  - api.example.com

then the statusCheckURL value might be:

statusCheckURL: https://api.example.com/.hypr-status-check

Login URL (optional)

loginURL is used to post the username to be authenticated. This endpoint is hosted by the Orchestrator, so the domain specified should resolve to a domain the Orchestrator hosts. It can also be set to a relative path. In either case, it must not conflict with any paths to protected applications. If unset, the value /.hypr-login will be used.

ℹ️

When specifying a loginURL, use absolute (full) URL including scheme, hostname, and path to ensure status requests are routed correctly. Always specify custom loginURL value if the routePattern includes a hostname.

For example, if the routePattern is defined as follows:

routePatterns:
  - api.example.com

then the loginURL value might be:

loginURL: https://api.example.com/login

Custom Intersitial HTML (optional)

customInterstitialHTML The page displayed while waiting for the user to respond to the HYPR prompt. It should contain the file system location of an HTML page. If the value is unset a default interstitial page will be used.

Custom Login HTML (optional)

customLoginHTML is the page displayed to prompt the user for their HYPR username. It should contain the file system location of an HTML page. If the value is unset a default login page will be used.

Custom Error HTML (optional)

customErrorHTML is the page displayed for error conditions. It should contain the file system location of an HTML page. If the value is unset a default error page will be used.

Examples

Using HYPR as an IDP

tls:
  sonar-app:
    caFile: certs/rootCA.pem
  maverics:
    certFile: certs/maverics.sonarsystems.co.crt
    keyFile: certs/maverics.sonarsystems.co.key

http:
  address: :443
  tls: maverics

session:
  cookie:
    domain: maverics.sonarsystems.com

connectors:
  - name: hypr
    type: hypr
    hyprDomain: "https://example.hypr.com"
    hyprAppID: "strata"
    accessToken: <HYPR_SECRET>

appgateways:
  - name: Sonar
    basePath: /
    upstream: https://app.sonarsystems.com:8443
    tls: sonar-app

    headers:
      SM_USER: hypr.username

    policies:
    - location: /sonar
      authorization:
          allowAll: true
      authentication:
          idps:
            - hypr

ℹ️

Set mfaOnly: true in the connector configuration when using HYPR as MFA.

HYPR as MFA Provider

Claim Mapping in Authentication Policy

Using the HYPR connector as an MFA provider in authentication policy requires a mapping between the HYPR username to a corresponding claim provided by the IDP connector. This matches user’s identity in the first factor (IDP) with their HYPR identity. For example:

authentication:
  idps:
    - azure
  mfa:
    - hypr:
        mapping:
          - username: azure.name

tls:
  sonar-app:
    caFile: /etc/maverics/certs/rootCA.pem
  maverics:
    certFile: /etc/maverics/certs/maverics.sonarsystems.co.crt
    keyFile: /etc/maverics/certs/maverics.sonarsystems.co.key

http:
  address: :443
  tls: maverics

session:
  cookie:
    domain: example.com

appgateways:
  - name: Sonar
    basePath: /
    upstream: https://app.sonarsystems.com:8443
    tls: sonar-app
    unauthorizedPage: https://example.com/sonar/accessdenied

    idps:
      - name: azure
      - name: hypr

    headers:
      SM_USER: azure.name
      firstname: azure.name
      lastname: azure.surname

    policies:
      - location: /sonar/accessdenied
        allowUnauthenticated: true
      - location: /sonar
        unauthorizedPage: https://app.sonarsystems.com:8443/sonar/accessdenied
        authentication:
          idps:
            - azure
          mfa:
            - hypr:
                mapping:
                  - username: azure.name

connectors:
  - name: azure
    type: azure
    authType: saml
    samlConsumerServiceURL: https://example.com/saml
    samlLogoutCallbackURL: https://example.com/logout
    samlMetadataURL: https://login.microsoftonline.com/<ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>
    samlEntityID: https://example.com

  - name: hypr
    type: hypr
    hyprDomain: "https://example.hypr.com"
    hyprAppID: "example"
    accessToken: <CLIENT_SECRET>

Customizing the Login Experience

There are three customization points for the HYPR connector’s user interactions. Each of these can deliver a custom HTML page stored in a location reachable by the Orchestrator, as shown above. The Orchestrator uses Go Templates to provide relevant arguments to be rendered.

Custom login page

This page will need to POST the username content to the login URL, which will be delivered in the LoginURL template value. The originally requested page can be found in the RedirectURL template value, and should be posted to the login URL along with the username.

<html>
  <body>
    <form method="POST" action="{{.LoginURL}}">
      <input type="hidden" name="redirectURL" value="{{.RedirectURL}}">
      <input type="text" name="username">
      <input type="submit">
    </form>
  </body>
</html>

Custom interstitial page

This is a holding page for the user’s browser session while they respond to the prompt on the HYPR app. It will need to poll the StatusCheckURL template value to determine when the request has completed. The originally requested URL is available in the RedirectURL template value.

<html>
  <script type="text/javascript">
    function checkHYPRStatus() {
      var xmlhttp = new XMLHttpRequest();
      xmlhttp.onreadystatechange = function() {
        if (xmlhttp.readyState == XMLHttpRequest.DONE) {
          if (xmlhttp.responseText == "COMPLETED") {
            window.location.replace("{{.RedirectURL}}");
            return;
          }
        }
      }
    };
    xmlhttp.open("GET", "{{.StatusCheckURL}}", true);
    xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
    xmlhttp.send();
   checkHYPRStatus();
  </script>
  <body>
    We're sending you a notification to confirm it's really you...
  </body>
</html>

Custom error page

This page is used to render error messages, which are available in the Error template value.

<html>
  <body>
    An error has occurred: {{.Error}}
  </body>
</html>

Auth0 LDAP