> ## 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.
</Note>

## 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

<Tabs>
  <Tab title="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**.
  </Tab>

  <Tab title="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.
    </Note>

    ## 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).
  </Tab>
</Tabs>

## 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

<AccordionGroup>
  <Accordion title="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>
    ```
  </Accordion>

  <Accordion title="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>
    ```
  </Accordion>

  <Accordion title="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>
    ```
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Generic OIDC" icon="key" href="/reference/orchestrator/identity-fabric/custom-oidc">
    Generic OpenID Connect connector
  </Card>

  <Card title="Okta" icon="shield-halved" href="/reference/orchestrator/identity-fabric/okta">
    OIDC connector for Okta
  </Card>

  <Card title="Microsoft Entra ID" icon="microsoft" href="/reference/orchestrator/identity-fabric/azure-ad">
    OIDC connector for Microsoft Entra ID
  </Card>
</CardGroup>