Powering Email Unsubscribe Links Using Signed URLs In ColdFusion

component
	output = false
	hint = "I provide the application settings and event handlers."
	{

	this.name = "UnsubscribeDemo";
	this.applicationTimeout = createTimeSpan( 1, 0, 0, 0 );
	this.sessionManagement = false;
	this.setClientCookies = false;

	// Mailhog test server.
	this.mailServers = [{
		host: "127.0.0.1",
		port: 1025
	}];

	// ---
	// LIFE-CYCLE METHODS.
	// ---

	/**
	* I initialize the ColdFusion application.
	*/
	public void function onApplicationStart() {

		// This ColdFusion component helps generate message authentication codes (HMAC).
		application.urlSigner = new UrlSigner(
			secretKey = binaryDecode( fileRead( "./secret.key" ), "base64" )
		);

		// Uses an ORDERED STRUCT to hold fake user data so that we can look users up by
		// ID as well as iterate over them in order.
		application.users = [
			"1": { id: 1, name: "Molly",  email: "molly@example.com",  subscribed: true },
			"2": { id: 2, name: "Arnold", email: "arnold@example.com", subscribed: true },
			"3": { id: 3, name: "Kim",    email: "kim@example.com",    subscribed: true }
		];

	}

}

<cfscript>

	// DEMO ONLY: For making it easier to read the inbox subject-lines.
	sendID = createUniqueId( "counter" );

	// Send an email to each of the users.
	loop
		key = "userID"
		value = "user"
		struct = application.users
		{

		// If the user is not subscribed to emails, continue onto next user.
		if ( ! user.subscribed ) {

			continue;

		}

		// We're about to embed a user-specific link within an email that allows the
		// user to change their state without having to authenticate with credentials.
		// As such, we need to make sure that the URL cannot be tampered with; otherwise,
		// we'd expose a way in which a malicious actor could change the state of any
		// user.
		signature = application.urlSigner.generateSignature({
			userID: user.id,
			feature: "unsubscribe-#user.id#"
		});

		// Prepare data structure to be consumed in email template.
		partial = {
			user: user,
			unsubscribeUrl: (
				"http://#cgi.http_host#" &
				"/signed-url/unsubscribe.cfm" &
				"?userID=#encodeForUrl( user.id )#" &
				"&signature=#encodeForUrl( signature )#" // Include signature!
			)
		};

		mail
			to = partial.user.email
			from = "no-reply@example.com"
			subject = "Great new offers! (#sendID#)"
			type = "html"
			async = false
			{

			include "./email-content.cfm";
		}

	}

</cfscript>

<a href="./send-email.cfm">Send again!</a>

<cfoutput>
	<h1>
		Hello #encodeForHtml( partial.user.name )#
	</h1>
	<p>
		Check out all our new offers!
	</p>
	<p>
		<a href="#partial.unsubscribeUrl#">Unsubscribe</a>
	</p>
</cfoutput>

<cfscript>

	// Ensure request parameters.
	param name="url.userID" type="numeric";
	param name="url.signature" type="string";
	param name="form.action" type="string" default="";

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	// Ideally, we want to test the URL signature before we do anything else so that in
	// addition to protecting the user we can also protect other upstream services (such
	// as the database). If the signature doesn't match, an error is thrown.
	application.urlSigner.testSignature(
		{
			userID: url.userID,
			feature: "unsubscribe-#url.userID#"
		},
		url.signature
	);

	// ASSERTION: At this point, we know that the URL was not tampered with (regarding the
	// user ID). As such, we can trust that the current user (at least) has access to the
	// target user's email account. To that end, we can render this page as if the user
	// has been properly authenticated (noting that this trust does NOT extend to any
	// other page within the current application).

	// Get the user record (for demo simplicity, I'm not validating this).
	user = application.users[ url.userID ];

	// Process form submission.
	switch ( form.action ) {
		case "subscribe":
			user.subscribed = true;
		break;
		case "unsubscribe":
			user.subscribed = false;
		break;
	}

</cfscript>
<cfoutput>

	<!-- To get name to show in the browser tab. -->
	<title>
		#encodeForHtml( user.name )#
	</title>

	<h1>
		Hello #encodeForHtml( user.name )#
	</h1>

	<form
		method="post"
		action="#cgi.script_name#?userID=#encodeForUrl( user.id )#&signature=#encodeForUrl( url.signature )#">

		<cfif user.subscribed>

			<p>
				You are currently <strong>subscribed</strong> to all emails.
			</p>
			<p>
				<button type="submit" name="action" value="unsubscribe">
					Unsubscribe Now!
				</button>
			</p>

		<cfelse>

			<p>
				You are currently <em>unsubscribed</em> to all emails.
			</p>
			<p>
				<button type="submit" name="action" value="subscribe">
					Subscribe Again
				</button>
			</p>

		</cfif>

	</form>

</cfoutput>