> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HYPR

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

> [!NOTE]
>
> **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**

To create a HYPR connector in the Maverics Console:

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

**Configuration**

```yaml maverics.yaml theme={null}
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
```

> [!NOTE]
>
> 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](/reference/orchestrator/identity-fabric#configuration-reference).

## 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`](https://pkg.go.dev/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.
>
> ```html login.html theme={null}
> <!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.
>
> ```html interstitial.html theme={null}
> <!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.
>
> ```html error.html theme={null}
> <!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

## Related Pages

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Generic OIDC](/reference/orchestrator/identity-fabric/custom-oidc)**
>
> Generic OpenID Connect connector

> **[Okta](/reference/orchestrator/identity-fabric/okta)**
>
> OIDC connector for Okta

> **[Microsoft Entra ID](/reference/orchestrator/identity-fabric/azure-ad)**
>
> OIDC connector for Microsoft Entra ID