.. Relock Cloud Deployment documentation master file, created by
   sphinx-quickstart on Wed Aug 20 11:05:55 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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: 

.. code-block:: bash

  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/``.

.. rst-class:: break_before

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


.. rst-class:: break_before

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:

.. code-block:: nginx

   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:

.. code-block:: bash

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

Then add to your VirtualHost:

.. code-block:: apache

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


.. rst-class:: break_before

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:

.. code-block:: python

   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``:

.. rst-class:: break_before

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. 

.. code-block:: javascript

   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());
   }