HYPR

The HYPR connector integrates the Maverics Orchestrator with HYPR passwordless authentication — enabling phishing-resistant, device-based authentication for your applications.

Console terminology: In the Maverics Console, this section is called Identity Fabric. The YAML configuration uses the connectors key to define identity provider integrations.

Overview

The HYPR connector enables passwordless authentication using the HYPR platform. It supports device-based authentication and QR code flows — allowing users to authenticate without passwords using their registered mobile device. The Orchestrator uses OIDC internally, but the Console exposes HYPR-specific configuration fields for the HYPR domain, application, and access token.

Use Cases

Passwordless SSO across legacy and modern apps — Replace passwords with HYPR device-based authentication and extend it to applications that lack native HYPR support, unifying passwordless SSO through the Orchestrator
Phishing-resistant MFA for IdP consolidation — Add strong, phishing-resistant multi-factor authentication as part of an IdP rationalization strategy, strengthening security posture while reducing reliance on legacy MFA solutions
QR code authentication for shared workstations — Enable users to scan a QR code with the HYPR mobile app for fast, secure authentication on shared or kiosk devices where passwords are impractical
Zero-trust authentication upgrade — Layer HYPR passwordless authentication into existing identity infrastructure through the Orchestrator, upgrading security without replacing or reconfiguring individual applications

Setup

Console UI
Configuration

To create a HYPR connector in the Maverics Console:

Navigate to Identity Fabric in the Console sidebar.
Click Create and select HYPR.
Enter a Name — this is the friendly name that identifies your provider.
Enter the HYPR Domain — the base domain of your HYPR account (e.g., your-org.hypr.com).
Enter the HYPR App ID — the name of the application as defined in the HYPR Control Center.
Enter the Access Token — an access token configured in the HYPR Control Center. Use the show/hide toggle to verify the value.
Optionally enable QR Authentication to display a QR code that users can scan with the HYPR mobile app. This toggle is off by default.
Optionally set a Status Check URL to monitor the HYPR service status.
Optionally set a Login URL to define a custom endpoint for posting user credentials.
Optionally upload a Custom Login HTML file to customize the login page displayed to users.
Optionally upload a Custom Interstitial HTML file to customize the interstitial page displayed during authentication.
Optionally upload a Custom Error HTML file to customize the error page displayed when authentication fails.
Click Save.

maverics.yaml

connectors:
  - name: hypr
    type: hypr
    hyprDomain: "https://{{ env.HYPR_DOMAIN }}"
    hyprAppID: "{{ env.HYPR_APP_ID }}"
    accessToken: <vault.hypr_access_token>
    qrAuthentication:
      enabled: true
    statusCheckURL: /.hypr-status-check
    loginURL: /.hypr-login
    customLoginHTML: /etc/maverics/html/login.html
    customInterstitialHTML: /etc/maverics/html/interstitial.html
    customErrorHTML: /etc/maverics/html/error.html

Custom HTML files can be loaded from the local filesystem or from the deployment configuration bundle. When using the Maverics Console, upload custom HTML files directly through the connector settings.

Configuration Reference

Key	Type	Required	Description
`name`	string	Yes	Unique connector identifier referenced in app policies
`type`	string	Yes	Must be `hypr`
`hyprDomain`	string	Yes	The base domain of the HYPR account (e.g., `https://your-org.hypr.com`)
`hyprAppID`	string	Yes	The application name as defined in the HYPR Control Center
`accessToken`	string	Yes	Access token from the HYPR Control Center (use secret reference syntax)
`statusCheckURL`	string	No	URL for polling authentication status (default: `/.hypr-status-check`)
`loginURL`	string	No	Custom endpoint for the HYPR login form (default: `/.hypr-login`)
`mfaOnly`	boolean	No	Use HYPR for MFA only (no standalone login handler)
`qrAuthentication.enabled`	boolean	No	Enable QR code authentication flow
`customLoginHTML`	string	No	Path to a custom login page HTML template
`customInterstitialHTML`	string	No	Path to a custom interstitial page HTML template
`customErrorHTML`	string	No	Path to a custom error page HTML template
`tls`	string	No	Named TLS profile for communication with the HYPR domain

For the complete field reference, see Identity Fabric.

Custom HTML Pages

The HYPR connector serves three pages during the authentication flow: a login page where users enter their username, an interstitial page displayed while the user responds to the HYPR prompt on their device, and an error page displayed when authentication fails. You can customize each page by providing your own HTML templates. Custom HTML templates are Go html/template files. The Orchestrator injects template values at render time that you can reference using {{ "{{" }} .FieldName {{ "}}" }} syntax.

Template Values

The following template values are available in custom HTML pages:

Value	Available In	Description
`{{ "{{" }} .LoginURL {{ "}}" }}`	Login, Error	The URL for the login form action and retry links
`{{ "{{" }} .RedirectURL {{ "}}" }}`	Login, Interstitial	The originally requested URL — include as a hidden form field so the user is redirected after login
`{{ "{{" }} .StatusCheckURL {{ "}}" }}`	Interstitial	The URL the page should poll to check if the user has completed authentication on their device. Returns plain text: `COMPLETED` when successful, `CANCELED` when the user declines
`{{ "{{" }} .QRCodeImg {{ "}}" }}`	Interstitial	Base64-encoded QR code image for scanning with the HYPR mobile app (only populated when `qrAuthentication.enabled` is `true`)
`{{ "{{" }} .QRDynamicLink {{ "}}" }}`	Interstitial	A dynamic link that opens the HYPR mobile app directly — serves as a fallback when scanning the QR code fails (only populated when `qrAuthentication.enabled` is `true`)
`{{ "{{" }} .QRFallbackCode {{ "}}" }}`	Interstitial	A fallback code for HYPR authentication when QR scanning is not available (only populated when `qrAuthentication.enabled` is `true`)
`{{ "{{" }} .Error {{ "}}" }}`	Error	The error message describing why authentication failed

Examples

Custom login page with username form

This template provides a branded login page where users enter their username to initiate HYPR passwordless authentication. The form posts to {{ .LoginURL }} and passes {{ .RedirectURL }} as a hidden field so the user returns to their original destination after login.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Login</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 100vh;
            background-color: #f5f5f5;
        }
        .login-container {
            background: white;
            padding: 2rem;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            width: 100%;
            max-width: 400px;
        }
        h1 { font-size: 1.5rem; margin-bottom: 1.5rem; text-align: center; }
        label { display: block; margin-bottom: 0.5rem; font-weight: 500; }
        input[type="text"] {
            width: 100%;
            padding: 0.75rem;
            border: 1px solid #ddd;
            border-radius: 4px;
            font-size: 1rem;
            margin-bottom: 1rem;
        }
        button {
            width: 100%;
            padding: 0.75rem;
            background-color: #4a90d9;
            color: white;
            border: none;
            border-radius: 4px;
            font-size: 1rem;
            cursor: pointer;
        }
        button:hover { background-color: #357abd; }
        .qr-fallback {
            text-align: center;
            margin-top: 1rem;
            font-size: 0.875rem;
        }
        .qr-fallback a { color: #4a90d9; text-decoration: none; }
    </style>
</head>
<body>
    <div class="login-container">
        <h1>Sign In</h1>
        <form method="POST" action="{{ "{{" }} .LoginURL {{ "}}" }}">
            <input type="hidden" name="redirectURL" value="{{ "{{" }} .RedirectURL {{ "}}" }}">
            <label for="username">Username</label>
            <input type="text" id="username" name="username" placeholder="Enter your username" required>
            <button type="submit">Continue with HYPR</button>
        </form>
    </div>
</body>
</html>

Custom interstitial page with device authentication polling

This template displays a waiting screen while the user authenticates on their HYPR mobile device. It uses JavaScript to poll the status check URL and automatically redirects the user once authentication completes. A dynamic link fallback is provided for users who cannot scan the QR code.

interstitial.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Authenticating</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 100vh;
            background-color: #f5f5f5;
        }
        .interstitial-container {
            background: white;
            padding: 2rem;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            width: 100%;
            max-width: 400px;
            text-align: center;
        }
        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
        p { color: #666; margin-bottom: 1.5rem; }
        .spinner {
            border: 4px solid #f3f3f3;
            border-top: 4px solid #4a90d9;
            border-radius: 50%;
            width: 40px;
            height: 40px;
            animation: spin 1s linear infinite;
            margin: 0 auto 1.5rem;
        }
        @keyframes spin {
            0% { transform: rotate(0deg); }
            100% { transform: rotate(360deg); }
        }
        .fallback-link {
            font-size: 0.875rem;
            margin-top: 1rem;
        }
        .fallback-link a { color: #4a90d9; text-decoration: none; }
    </style>
</head>
<body>
    <div class="interstitial-container">
        <div class="spinner"></div>
        <h1>Waiting for Authentication</h1>
        <p>Please approve the login request on your HYPR mobile app.</p>
        {{ "{{" }} if .QRDynamicLink {{ "}}" }}
        <div class="fallback-link">
            <p>Can't scan the QR code? <a href="{{ "{{" }} .QRDynamicLink {{ "}}" }}">Open HYPR app directly</a></p>
        </div>
        {{ "{{" }} end {{ "}}" }}
    </div>
    <script>
        (function () {
            var statusURL = "{{ "{{" }} .StatusCheckURL {{ "}}" }}";
            var redirectURL = "{{ "{{" }} .RedirectURL {{ "}}" }}";
            if (!statusURL) return;
            var interval = setInterval(function () {
                fetch(statusURL)
                    .then(function (resp) { return resp.text(); })
                    .then(function (state) {
                        if (state === "COMPLETED") {
                            clearInterval(interval);
                            window.location.replace(redirectURL);
                        } else if (state === "CANCELED") {
                            clearInterval(interval);
                            document.querySelector("h1").textContent = "Authentication Canceled";
                            document.querySelector("p").textContent = "The login request was declined. Please try again.";
                            document.querySelector(".spinner").style.display = "none";
                        }
                    })
                    .catch(function () {});
            }, 2000);
        })();
    </script>
</body>
</html>

Custom error page for authentication failures

This template displays a user-friendly error message when HYPR authentication fails. It renders the error message provided by the Orchestrator and gives the user an option to retry.

error.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Authentication Error</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 100vh;
            background-color: #f5f5f5;
        }
        .error-container {
            background: white;
            padding: 2rem;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            width: 100%;
            max-width: 400px;
            text-align: center;
        }
        .error-icon {
            font-size: 3rem;
            margin-bottom: 1rem;
            color: #e74c3c;
        }
        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
        .error-message {
            color: #666;
            margin-bottom: 1.5rem;
            padding: 1rem;
            background-color: #fef2f2;
            border-radius: 4px;
            border: 1px solid #fecaca;
        }
        a.retry-button {
            display: inline-block;
            padding: 0.75rem 1.5rem;
            background-color: #4a90d9;
            color: white;
            text-decoration: none;
            border-radius: 4px;
            font-size: 1rem;
        }
        a.retry-button:hover { background-color: #357abd; }
    </style>
</head>
<body>
    <div class="error-container">
        <div class="error-icon">&#9888;</div>
        <h1>Authentication Failed</h1>
        <div class="error-message">
            <p>{{ "{{" }} .Error {{ "}}" }}</p>
        </div>
        <a href="{{ "{{" }} .LoginURL {{ "}}" }}" class="retry-button">Try Again</a>
    </div>
</body>
</html>

Troubleshooting

Verify the HYPR domain is accessible from the Orchestrator host — ensure the domain is correct and reachable
Ensure the App ID matches exactly what is configured in the HYPR Control Center — mismatched app IDs cause authentication failures
Check that the access token is valid — expired or revoked tokens will prevent the connector from communicating with HYPR
QR code not displaying — confirm that the QR Authentication toggle is enabled in the Console or that the equivalent setting is configured in YAML

Identity Fabric

Overview of all identity providers

Generic OIDC

Generic OpenID Connect connector

Okta

OIDC connector for Okta

Microsoft Entra ID

OIDC connector for Microsoft Entra ID

Console Administration

Orchestration

Overview

Use Cases

Setup

Configuration Reference

Custom HTML Pages

Template Values

Examples

Troubleshooting

Identity Fabric

Generic OIDC

Okta

Microsoft Entra ID

Console Administration

Orchestration

​Overview

​Use Cases

​Setup

​Configuration Reference

​Custom HTML Pages

​Template Values

​Examples

​Troubleshooting

​Related Pages

Identity Fabric

Generic OIDC

Okta

Microsoft Entra ID

Overview

Use Cases

Setup

Configuration Reference

Custom HTML Pages

Template Values

Examples

Troubleshooting

Related Pages