SameSite Integration

This integration makes the Relock spinner/loader appear under your own domain, while keeping the same logic as the simple redirect option. Cryptographic keys are stored within your domain and are bound to the browser’s origin, ensuring they cannot be shared across unrelated sites.

The major difference in this deployment model is the ability to provide the Relock authentication gateway with information about user sign-in and sign-out events. If a user ID is passed to the gateway, subsequent verifications will include that ID in the response. This simplifies the authentication experience by eliminating the need to prompt the user for their login again.

Relock gateway will be accessible at:

https://example.com/relock/gateway/<RANDOM_UUID>

To conceal the forwarding to Relock behind your own domain, you need to configure rules in your reverse proxy or load balancer. This setup ensures that users always see your company’s domain in the browser, even when verification is handled by the Relock cloud service.

The main benefits of this approach are:

First-party cookies: Because the request appears to originate from your domain,Relock can set cookies that are treated as first-party by the browser. This makes session management more secure and reliable compared to third-party cookies.

Consistent user experience: The verification flow feels seamless to users since they never leave your domain, even though the authentication process is being proxied to Relock in the background.

Simplified integration: You don’t need to modify your application logic. Instead, your reverse proxy or load balancer forwards requests to Relock whenever the path begins with /relock/.

Gateway Wildcard Header

When deploying Relock under your own domain, you must provide a UUID identifier for the gateway in each request header. This UUID serves as a unique key that binds requests from your domain to the correct gateway configuration in Relock Cloud.

You can find the dedicated UUID for your gateway in the Gateway Keys tab of the Relock Admin Panel. The UUID must be attached to every proxied request to Relock.

To simplify this, we recommend automating the process by adding a header rule to your reverse proxy configuration (e.g., X-Key-Wildcard: <gateway-uuid>). This ensures that all traffic routed through /relock/ will consistently include the required gateway identifier without any changes to your application code.

Redirect Routes Note

In this integration option, the redirect routes must be configured exactly the same as in the simple integration. The Relock gateway enforces strict origin verification during its internal checks. If the redirect routes do not match the expected origin of the requests, the device will always be treated as new (or “fresh”), even if it is actually trusted.

Therefore, you must provide a complete URL including the domain name when configuring return routes in the Relock Admin Panel.

Configure the return routes (URLs) in the Relock Admin Panel as follows:

Known/Trusted device → https://example.com/require_password_only

New/Fresh device → https://example.com/make_idv_authentication

Reverse-proxy configuration

Below you can find example configurations for Nginx and Apache that redirect all requests where path starting with /relock/ to the Relock gateway on third-party server at relock.host

Nginx Example:

location /relock/ {
    proxy_pass https://relock.host;
    proxy_set_header Host relock.host;
    proxy_set_header X-Key-Wildcard "your-unique-uuid";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Apache Example:

Make sure mod_proxy and mod_headers are enabled:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod headers
sudo systemctl restart apache2

Then add to your VirtualHost:

<VirtualHost *:443>
    ServerName example.com

    SSLProxyEngine On
    ProxyRequests Off

    <Location /relock/>
        ProxyPass https://relock.host/relock/
        ProxyPassReverse https://relock.host/relock/
        RequestHeader set X-Key-Wildcard "your-unique-uuid"
    </Location>
</VirtualHost>

SameSite Login Hook

When integrating a Single-Page Application (SPA) where the frontend stores sensitive user data, you can log the user directly into the Relock gateway with a simple fetch request. This approach allows the SPA to establish the device owner within the gateway without requiring any redirects or additional friction.

For non-SPA web applications, you must additionally provide an HTTP_ONLY session cookie with is included to your backend request by a browser. Locate the X-Key-Session cookie value and include it as a JSON attribute in the request. In SPA applications that call the gateway directly from the frontend, this cookie is automatically included.

Python Flask example:

request.cookies.get('X-Key-Session', str())

In this integration mode, an explicit logout call is not required. The session is automatically terminated once the user closes the browser tab, ensuring that no sensitive data persists beyond the active browsing session.

Below you can find the javascript example of API call for gateway user login and device token and signature verification. The /relock/login request verifies the user device signature and validates the token’s authenticity and assigns the device owner. This serves as an additional safeguard to confirm the legitimacy of the gateway response, separate from the server-side Ed25519 signature validation that your application should always perform. Once user is assigned to the device the gateway will include information about the device owner into the response.

Javascript example API call for /relock/login:

The required token and signature are provided in the gateway’s response after spinner loader (behind) verification. Each gateway POST response includes X-Key-Token and X-Key-Signature in the response body.

async function login(user = String('<some_user_id_or_hash>'),
                     email = String('<user_email>'),
                     token = String('<device_token>'),
                     signature = String('<device_signature>'),
                     xsid = String('<HTTP_ONLY_cookie_value>')) {

    return await fetch("/relock/login", {
        method: "POST",
        credentials: 'include',
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify({
            "X-Key-Token": token,
            "X-Key-Signature": signature,
            "X-Key-Session": xsid,
            "user": user,
            "email": email
        })
    }).then((res) => res.json());
}