Client Authentication

All Gremlin clients authenticate to the Gremlin Control Plane using a public-key certificate and private key. We call this signature-based authentication. This page shows how to download and create these credentials, and answers some FAQs about them.

To read about User authentication via the Gremlin Web App, see User Management and Authentication..

You must be a superuser of your Gremlin account to manage certificates.

Downloading the Certificate

To download your certificate, navigate to the Gremlin Web App Company Settings.

Then click the Team whose client credentials you want to download. (Each team has its own client credentials.)

Company Settings

Each Team page has everything your Gremlin clients need to authenticate to the Control Plane: the Team ID and Certificate.

Click Download to get your Team Certificate.

Team page

The downloaded file (e.g., Kent contains both a public-key certificate and a matching private key. Unzip the file, and configure all Gremlin clients with the certificate, the private key, and the Team ID.

Creating a New Certificate

All certificates expire one year after creation. Before the expiration date, you must create a new certificate, reconfigure all clients with it, and delete the old certificate. As the expiration date draws near, the Gremlin Web App will display a warning about it.

To create a new certificate, simply click the Create New button next to your existing certificate (see the previous screenshot). Now that you have two certificates, you cannot download the older certificate (though all clients still configured with it may still use it to authenticate), and you cannot create a third certificate.

Two Certificates

If you didn’t mean to create the newer certificate yet, just destroy it. Otherwise, move all clients to the newer certificate, then destroy the old one.

Client states

All Gremlin clients (infrastructure and application) authenticated to the Gremlin Control Plane appear under the infrastructure clients and application clients. You can only run attacks on “active” clients. A client goes into an “idle” state if there is no activity for the past 5 minutes. You will not be able to run/schedule attacks on idle clients. If Gremlin doesn’t hear from these idle clients for the period of 24 hours, these clients will disappear from the clients list. However, if a client starts communicating with Gremlin again while in the idle window, the client is reactivated.


Can I create one certificate for my whole Company?

No. Every Team within the Company must use its own certificate.

Can I create one certificate per Gremlin client?

No. Every Gremlin client within a Team uses the same shared certificate. When that certificate is about to expire, you must create a new certificate. For a brief time, you may have some clients configured with the older certificate and some with the newer one. But before the older certificate expires, you must move all clients to the newer certificate.

Is it OK for some clients to use secret-based auth while others use signature-based auth?

Yes, but if you are still using secret-based auth, you should move all clients to signature-based auth as soon as possible.

What does signature-based authentication have to do with SSL?

Nothing. Signature-based auth is independent of the SSL layer, but both are important. The purpose of SSL is to 1) encrypt the client-to-server connection, and 2) let the client authenticate the server (i.e. the Gremlin Control Plane). Signature-based auth lets the Gremlin Control Plane authenticate the client.

Before the client connects to the backend, it signs the payload using $GREMLIN_TEAM_PRIVATE_KEY_OR_FILE. Then it initiates an SSL handshake with the backend, verifying the backend’s SSL certificate in the process. After the SSL tunnel has been established the backend verifies that the payload was signed by a Gremlin-issued key.

What cryptographic standard does signature-based authentication use?

It uses 256-bit ECDSA (prime256v1) for keys, with SHA 256-bit ECDSA for signatures. The recommended lifespan for anything secured by these standards is two years, but we’re more conservative, opting for one-year expiration.