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.

Access Token

accessToken is the API token configured in the HYPR Control Center. This is sensitive information which should be retrieved from a secret provider in production environments. At the bare minimum, it should have application authentication permissions.

QR Authentication

By default the Hypr connector will use push based authentication for prompting the user to authenticate. However, you can enable QR authentication which will display a QR code to the user which should be scanned by the Hypr Mobile App.

Enabled

Set to true to use QR Authentication. It is false by default.

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

Push Based Authentication

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

apps:
  - name: ExampleApp
    type: proxy
    routePatterns:
      - /
    upstream: https://app.exmaple.com

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

QR Code Authentication

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

apps:
  - name: ExampleApp
    type: proxy
    routePatterns:
      - /
    upstream: https://app.example.com

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

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.

If QR Authentication is enabled, the QR code image will be available in the QRCodeImg template value.

<html>
<head>
    <script type="text/javascript">
        function checkHYPRStatus() {
            var xmlhttp = new XMLHttpRequest();
            xmlhttp.onreadystatechange = function () {
                if (xmlhttp.readyState == XMLHttpRequest.DONE) {
                    if (xmlhttp.status == 200) {
                        if (xmlhttp.responseText == "COMPLETED") {
                            window.location.replace("{{.RedirectURL}}");
                            return;
                        }
                        setTimeout(checkHYPRStatus, 2000)
                    }
                }
            }
            xmlhttp.open("GET", "{{.StatusCheckURL}}", true);
            xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
            xmlhttp.send();
        };
        window.onload = function () {
            checkHYPRStatus();
        };
    </script>
</head>
<body>
<div>
    {{ if not .QRCodeImg }}
    <div style="font-weight: 400;font-size: 14px;white-space: pre-line;">
        We're sending you a notification to confirm it's really you...
    </div>
    {{- else }}
    <div style="font-weight: 400;font-size: 14px;white-space: pre-line;">
        open your Hypr app and scan the QR code below.
    </div>
    <div id="qr-code">
        <img src="data:image/png;base64,{{.QRCodeImg}}" alt="QR Code">
    </div>
    {{- end }}
</div>
</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>

Continuity Connector LDAP and Active Directory