Secure mode

Overview

This topic explains how to use the secure mode feature to safely evaluate feature flags in a web browser.

Using secure mode

Secure mode ensures that customers' feature flag evaluations are kept private in web browser environments, and that one end user cannot inspect the variations for another end user. On an insecure device, a malicious end user could use a context or user key to identify what flag values another end user receives by analyzing the results of multiple flag evaluations. Secure mode prevents you from doing an evaluation for a context or user key that hasn't been signed on the backend.

Secure mode is available for communication between the following JavaScript-based SDKs and LaunchDarkly:

• Electron
• JavaScript
• Node.js (client-side)
• React Web

Secure mode is not necessary for server-side SDKs.

Understanding how secure mode works

Secure mode works when you configure your JavaScript SDK to include a server-generated HMAC SHA256 hash of your context key or user key. This hash is signed with the SDK key for your environment. Enabling secure mode means that every request coming from a client-side JavaScript SDK requires the secure mode hash to evaluate flag variations. You can pass this to your front-end code with the mechanism of your choice, such as bootstrapping or as a template variable.

To use secure mode, you must complete the following:

1. Enable secure mode for each environment: You can enable secure mode for each of your environments on the Environments tab of your project on the Account settings page. Secure mode is an environment-wide setting. You can enable secure mode for your environment even if you're also using SDKs other than JavaScript. Enabling secure mode does not cause those SDKs to fail.
2. Configure your server-side or edge SDK to generate the secure mode hash: Most LaunchDarkly server-side and edge SDKs include a method to compute the secure mode hash for a key. Alternatively, you can compute the hash yourself. To learn how, read Computing the hash manually. If at any time you reset an environment's SDK key, you will need to regenerate the secure mode hash.
3. Send the computed secure mode hash for the context or user to LaunchDarkly: Include the secure mode hash when requesting flag evaluations. The JavaScript-based SDK will send the context or user key and the hash to LaunchDarkly. If the hash doesn’t match, LaunchDarkly returns an error.

Generating a secure mode hash

Details about generating a secure mode hash are available in the SDK-specific sections below:

• Server-side SDKs
• Edge SDKs

Server-side SDKs

You can use the following server-side SDKs to generate a secure mode hash:

• .NET (server-side)
• Go
• Haskell
• Java
• Node.js (server-side)
• PHP
• Python
• Ruby
• Rust

.NET (server-side)

var hash = client.SecureModeHash(context);
COPY

Go

client.SecureModeHash(context)
COPY

Haskell

secureModeHash client context
COPY

Java

client.secureModeHash(context);
COPY

Node.js (server-side)

client.secureModeHash(context);
COPY

PHP

$hash = $client->secureModeHash($context);
COPY

Python

hash = ldclient.get().secure_mode_hash(context)
COPY

Ruby

client.secure_mode_hash(context)
COPY

Rust

client.secure_mode_hash(&context);
COPY

Edge SDKs

You can use the following edge SDKs to generate a secure mode hash:

• Cloudflare
• Vercel

Cloudflare

const hash = client.secureModeHash(context);
COPY

Vercel

const hash = client.secureModeHash(context);
COPY

Computing the hash manually

To compute the hash manually, locate the server-side SDK key for your environment on the Environments tab of your project on the Account settings page. Then, compute an HMAC SHA256 hash of the UTF-8 encoding of your context key, using the UTF-8 encoding of your SDK key as a secret, and convert the hash to a hexadecimal string.

Here is a .NET (server-side) example:

using System;
using System.Security.Cryptography;
using System.Text;
var encoding = new UTF8Encoding();
var keyBytes = encoding.GetBytes("sdk-key-123abc");
var hmacSha256 = new HMACSHA256(keyBytes);
var hashBytes = hmacSha256.ComputeHash(encoding.GetBytes("context-key-123abc"));
var hashString = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
COPY

Configuring secure mode in JavaScript-based SDKs

To use secure mode, you must generate the hash based on a unique identifier for the context. This unique identifier is called a "canonical key" and is a concatenation of the kind and key attributes, separated by a colon (:). For example, if a user context has a key of "user-key-123abc," this means you must generate the hash using a canonical key of user:user-key-123abc. If the context is a multi-context, the canonical key must include the key and kind attribute for each context kind. For example, if a multi-context contains an organization context kind and a user context kind, and they have the keys "org-key-123abc" and "user-key-123abc", the canonical key is organization:org-key-123abc:user:user-key-123abc.

Secure mode is not compatible with the SDK's ability to automatically generate keys for anonymous contexts because the SDK needs a correctly calculated hash value. To learn more, read Anonymous contexts and users.

In JavaScript-based SDKs, send the computed secure mode hash for your context as the hash attribute in the LDOptions object during client initialization, and as the hash parameter if subsequently identifying new contexts.

Specifying the computed secure mode hash is supported in the following client-side SDKs:

• Electron
• JavaScript
• Node.js (client-side)
• React Web

Electron

// client initialization
const options = {
  hash: 'server-generated-hash-123abc',
};
const client = LDClient.initialize('client-side-id-123abc', user, options);
// identification of new user
client.identify(newUser, hash, function() {
  console.log("New user's flags available");
});
// identification of new user, with a Promise
client.identify(newUser, hash).then(() => {
  console.log("New user's flags available");
});
COPY

JavaScript

// client initialization
const options = {
  hash: 'server-generated-hash-123abc',
};
const client = LDClient.initialize('client-side-id-123abc', context, options);
// identification of new contexts
client.identify(newContext, hash, function() {
  console.log("New context's flags available");
});
COPY

Node.js (client-side)

// client initialization
const options = {
  hash: 'server-generated-hash-123abc',
};
const client = LDClient.initialize('client-side-id-123abc', context, options);
// identification of new contexts
client.identify(newContext, hash, function() {
  console.log("New context's flags available");
});
// identification of new contexts, with a Promise
client.identify(newContext, hash).then(() => {
  console.log("New context's flags available");
});
COPY

React Web

All context-related functionality provided by the JavaScript SDK is also available in the React SDK.