External Mitigation Service Configuration
This document provides detailed instructions on how to configure and integrate the external mitigation service.
1. Configuration Parameters
The following parameters are required in Server.yml to enable and configure this feature.
| Parameter | Type | Description |
|---|---|---|
enabled | Boolean | true or false. Enables or disables this feature. |
redirect_url | String | Specifies the URL of the external verification service to which users will be redirected. |
secret_key | String | The secret key used to generate and verify HMAC signatures. Ensure this key is sufficiently complex and secure. |
session_timeout | Integer | Specifies the session timeout duration in seconds. After this period, the user must be re-validated by the external verification service. |
2. Redirecting to the External Service
When Server Torii redirects a user to the external service, the URL will include the following query parameters. You must store these parameters to correctly redirect the user back after they are successfully verified by the external service.
Query Parameters
| Parameter | Description |
|---|---|
domain | The domain of the original request. |
session_id | The session ID generated by Server Torii. |
original_uri | The URI the user originally attempted to access. |
hmac | The HMAC signature used to verify the authenticity of the request. |
Redirect URL Example
https://example.com/your-verification-page?domain=your-website.com&session_id=somesessionid&original_uri=%2Fprotected%2Fresource&hmac=abc123xyz456
HMAC Signature Calculation
The HMAC signature is used to ensure the integrity and security of the request. It must be strictly validated on the external verification service's side to prevent security vulnerabilities, such as arbitrary redirects.
Calculation Method: Create an HMAC object (using the SHA512 algorithm) with the secret_key. Then, generate the signature by creating a string that concatenates domain, timestampStr, and original_uri, separated by colons (:).
Example:
hmac = HMAC-SHA512(secretKey, domain + ":" + timestampStr + ":" + originalUri)
3. Redirecting the User Back to Server Torii
After your external service has successfully verified the user, you must redirect the user back to Server Torii's fixed callback endpoint: /torii/external_migration.
Callback Parameters
When performing the callback, you must provide the following parameters in the URL query:
| Parameter | Description |
|---|---|
original_uri | The original URI that the user initially requested. |
timestamp | The current timestamp. |
hmac | A new HMAC signature generated based on the callback parameters. |
HMAC Signature Calculation (Callback)
Calculation Method: Create an HMAC object (using the SHA512 algorithm) with the secret_key. Then, generate the signature by creating a string that directly concatenates sessionID, timestamp, and original_uri.
Example:
hmac = HMAC-SHA512(secretKey, sessionID + timestamp + original_uri)
Warning
To ensure security and proper functionality, you must redirect the user back to the Server Torii callback endpoint immediately after calculating the HMAC.