Customizing URLs
By default, DID Connect sets up its API endpoints under a predictable path structure like /api/did/{action}/auth. However, when deploying behind a reverse proxy, nested application router, or serverless function, you may need to customize these URLs. This guide explains how DID Connect automatically infers the public-facing base URL and how you can manually transform the endpoint paths to fit your environment.
Automatic baseUrl Inference#
The DID Wallet requires an absolute, publicly accessible URL to send responses back to your application. The library intelligently constructs this base URL by inspecting request headers, which is especially useful when your application is behind a reverse proxy like Nginx or a cloud load balancer.
Here is the order of precedence the library uses to determine each part of the URL:
This automatic detection means that in most standard proxy setups, no extra configuration is needed. For example, if your Nginx proxy sets the X-Forwarded-Proto: https and X-Forwarded-Host: myapp.com headers, the library will correctly generate a base URL like https://myapp.com.
Example: Retrieving Base URL from Headers#
Consider an Express app where the host header is localhost:8083, but a proxy exposes it publicly on port 8081. The prepareBaseUrl utility can be used to see how the final URL is constructed.
// This utility is used internally but can be imported for testing
const { prepareBaseUrl } = require('@did-connect/handler/lib/handlers/util');
// Mock request object reflecting a proxy environment
const req = {
protocol: 'http',
headers: {
'host': 'host.com:8083',
'x-real-port': 8082, // This header is set by the proxy
},
get: (key) => req.headers[key.toLowerCase()],
};
// The 'params' object, from the request body or query, can override headers
const params = { 'x-real-port': 8081 };
const url = prepareBaseUrl(req, params);
console.log(url);
// Output: http://host.com:8081/This shows that params['x-real-port'] has the highest priority for determining the port.
Customizing Endpoint Paths with pathTransformer#
While baseUrl handles the server's address, the pathTransformer function lets you modify the URL's path segment (e.g., /api/did/login/auth). This is useful for namespacing your APIs, supporting versioning, or adapting to specific routing frameworks.
You provide the pathTransformer function when you create your WalletHandlers instance.
How it Works#
- Automatic Path Resolution: The library first determines the full request path by inspecting
req.originalUrl. For instance, if a handler for/authis on a router mounted at/api/did/login, it correctly identifies the full path as/api/did/login/auth. - User Transformation: Your
pathTransformerfunction receives this auto-resolved path and returns a new string to be used as the final endpoint path.
Example: Prepending a Version to the Path#
To prefix all DID Connect endpoints with /v2, you can define a pathTransformer function.
const express = require('express');
const { WalletHandlers } = require('@did-connect/handler');
// Other required initializations (authenticator, tokenStorage, etc.)
const app = express();
// 1. Define the path transformer function
const pathTransformer = (pathname) => {
// Prepend /v2 to every connect path
return `/v2${pathname}`;
};
// 2. Instantiate WalletHandlers with the transformer
const handlers = new WalletHandlers({
authenticator, // your authenticator instance
tokenStorage, // your tokenStorage instance
pathTransformer, // Pass the function here
});
// 3. Attach the handlers for a 'login' action
handlers.attach({
app,
action: 'login',
onAuth: async ({ userDid }) => {
console.log(`User ${userDid} authenticated.`);
return { successMessage: 'Login successful!' };
},
});
// When a new session is generated, the URL provided to the wallet
// will be based on the transformed path. For example, the auth URL
// will become: https://your-app.com/v2/api/did/login/authIn this example, every URL generated for the DID Connect flow will include the /v2 prefix, ensuring it matches your application's routing structure.
By leveraging automatic baseUrl inference and the pathTransformer function, you can adapt DID Connect to virtually any deployment environment.
Next, learn how to monitor the authentication lifecycle by exploring Event Handling.