• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""
    EXPAND ALL

    EDIT ON GITHUB

    Secure mode

    Read time: 3 minutes
    Last edited: Mar 16, 2023

    Overview

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

    Newer versions of LaunchDarkly SDKs replace users with contexts

    A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more, read Contexts and segments.

    Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.

    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 only available for communication between client-side SDKs and LaunchDarkly. It is not necessary for server-side SDKs.

    Understanding how secure mode works

    Secure mode works by having you configure your JavaScript SDK to include a server-generated HMAC SHA256 hash of your context or user key. This hash is signed with the SDK key for your environment.

    To use secure mode, you must complete the following:

    • 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 mobile SDKs that don't support it. Enabling secure mode does not cause those SDKs to fail.

    • Compute the secure mode hash. 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.

      Each of our server-side SDKs includes a method to compute the secure mode hash for a key. To learn how, read Generating a secure mode hash. Alternatively, you can compute the hash yourself. To learn how, read Computing the hash manually.

    • Send the computed secure mode hash for the context or user. You need to include this when requesting flag evaluations. To learn how, read Configuring secure mode in the JavaScript client-side SDK.

    Enable secure mode during initial setup

    You can enable secure mode at any time when you use LaunchDarkly SDKs. As a best practice, we recommend that you enable secure mode during initial SDK configuration, because late-stage changes to your SDK configuration may have negative interactions with other settings.

    Generating a secure mode hash

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

    .NET (server-side)

    Expand .NET (server-side) code sample

    The SecureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    var hash = client.SecureModeHash(context);

    Go

    Expand Go code sample

    The SecureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    client.SecureModeHash(context)

    Haskell

    Expand Haskell code sample

    The secureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    secureModeHash client context

    Java

    Expand Java code sample

    The secureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    client.secureModeHash(context);

    Node.js (server-side)

    Expand Node.js (server-side) code sample

    The secureModeHash method computes an HMAC signature of a user signed with the client's SDK key.

    Here is the method:

    client.secureModeHash(context);

    PHP

    Expand PHP code sample

    The secureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

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

    Python

    Expand Python code sample

    The SecureModeHash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

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

    Ruby

    Expand Ruby code sample

    The secure_mode_hash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    client.secure_mode_hash(context)

    Rust

    Expand Rust code sample

    The secure_mode_hash method computes an HMAC signature of a context signed with the client's SDK key.

    Here is the method:

    client.secure_mode_hash(&context);

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

    Configuring secure mode in the JavaScript client-side SDK

    You should send the computed secure mode hash for your user as the hash attribute in the LDOptions object during client initialization and as the hash parameter if subsequently identifying new contexts:

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

    To use secure mode, context objects must contain a predefined key attribute. 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.