Authentication Troubleshooting

TABLE OF CONTENTS

• Client authentication methods
  • Secret-based authentication
  • Signature-based authentication
• Rotating expiring certificates
• Verifying Gremlin Agent authentication
• Releasing client certificates
• FAQ

GETTING STARTED

The Gremlin Daemon (gremlind) connects to the Gremlin Control Plane and waits for attack orders from you. When it receives attack orders, it uses the Gremlin Agent (gremlin) to run the attack.

To connect the Gremlin Daemon to the Control Plane, you need your client credentials, provided either via secret-based authentication using TEAM ID and SECRET, or via signature-based authentication using PEM certificates. These credentials are not the same as the email and password credentials you use to access the Gremlin web app. To read about user authentication through the Gremlin web app, see User Authentication.

Client authentication methods

There are two methods for authenticating clients with Gremlin:

• Secret authentication involves a secret string value that Gremlin clients use to prove their identity. Secrets are created from the Gremlin UI, and are like passwords. They can never be retrieved from Gremlin after creation; they can only be reset.
• Signature authentication requires supplying a public and private ECDSA certificate-key pair to Gremlin clients. This certificate pair is created from the Gremlin web app, and can be downloaded again at any time, but expires 1 year from the date of creation.

Both authentication methods can be configured with the Gremlin configuration file or environment variables. See Advanced configuration to learn more about how to configure Gremlin.

Secret-based authentication

Create a secret

To use secret-based authentication as a new user, sign in to the Gremlin web app. Go to Team Settings, and click your Team. From the Team Settings page, on the secret line, click Create to create a new secret.

Configure clients with secret

To configure Gremlin clients for secret authentication, follow one of the [advanced configuration] (/docs/getting-started/advanced-configuration/) methods:

set team_id and team_secret in your config.yaml

YAML

team_id: 11111111-1111-1111-1111-111111111111
team_secret: 11111111-1111-1111-1111-111111111111

# export these to the gremlind process or save them to /etc/default/gremlind (used by Systemd and SysV)
GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111
GREMLIN_TEAM_SECRET=11111111-1111-1111-1111-111111111111

gremlin init --tag service=my-api --tag service-version=1.0.0 --tag service-type=http

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.

The downloaded zip file contains both a public-key certificate and a matching private key. Unzip the file, and register Gremlin clients to the Control Plane with the included certificate, private key, and your Team ID.

Configure clients with certificate pair

To configure Gremlin clients for signature authentication, follow one of the advanced configuration methods:

set team_id, team_certificate, and team_private_key in your config.yaml

• YAML

  #/etc/gremlin/config.yaml
  team_id: 11111111-1111-1111-1111-111111111111
  team_certificate: file:///var/lib/gremlin/cert.pem
  team_private_key: file:///var/lib/gremlin/key.pem

  or pass environment variables GREMLIN_TEAM_ID, GREMLIN_TEAM_CERTIFICATE_OR_FILE, and GREMLIN_TEAM_PRIVATE_KEY_OR_FILE directly to the gremlind process

• SHELL

  # export these to the gremlind process or save them to /etc/default/gremlind (used by Systemd and SysV)
  GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111
  GREMLIN_TEAM_CERTIFICATE_OR_FILE=file:///var/lib/gremlin/cert.pem
  GREMLIN_TEAM_PRIVATE_KEY_OR_FILE=file:///var/lib/gremlin/key.pem

• Rotating expiring certificates

  You must be a Team or Company Manager of your Gremlin account to manage certificates.

  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.

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

Verifying Gremlin Agent authentication

To verify that your Gremlin Agents are connected to the Gremlin Control Plane, first make sure that the Gremlin Daemon is running.

For hosts running System V (RHEL 6, CentOS 6, Amazon Linux 1, etc.), use the service command:

sudo service gremlind status

sudo systemctl status gremlind

gremlin check auth

auth
====================================================
Auth Input Type                      : Certificate
API Response                         : OK

auth
====================================================
Auth Input Type                      : No valid auth found
========= Identification ============:
Team ID Source                       : Team ID not found
Gremlin Identifier                   : [Host identifier]
Gremlin Identifier Source            : Not supplied explicitly, using the default
========= Secret/Token Info =========:
Team Secret Source                   : Team Secret not found
.credentials valid                   : /var/lib/gremlin/.credentials file not found
========= Certificate Info ==========:
Team Certificate Source              : Team Certificate not found
========= Private Key Info ==========:
Team Private Key Source              : Team Private Key not found