Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML

This page provides instructions on configuring Microsoft Entra ID (previously Azure Active Directory) to enable SAML-based authentication. Before following this guide, first follow instructions 1–3 in Authenticating users with SAML. You’ll need the Gremlin Service Provider (SP) metadata fields and claims. This page will show you how to configure Microsoft Entra ID with your metadata and claims.

Enabling SAML-based authentication with Microsoft Entra ID

  1. Log into your Azure account and navigate to the Microsoft Entra ID admin center.
  2. Select Enterprise applications, then click New application.
  1. Select Create your own application.
  1. Enter a name for your application (e.g. “GremlinSSO”) and click Create.
  1. After saving, select the new application from the list of available Enterprise Applications.
  1. From its properties page, click Set up single sign-on.
  1. Select SAML for the SSO method.
  1. Under Basic SAML Configuration, click the Edit button.
  1. Enter the values of Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL).  These values are provided in the Gremlin documentation here. As of May 24, 2024, the current values are:
    1. Identifier (Entity ID): http://api.gremlin.com/saml
    2. Reply URL (Assertion Consumer Service URL): https://api.gremlin.com/v1/users/auth/saml/acs
  2. Enter your Relay State value. This is specific to your Gremlin company, so copy it from the SAML Setup section of the Gremlin UI or API.
  1. After entering the required information, click Save to return to the previous screen.
  1. From the Enterprise Application SAML configuration screen, note the following three values, for use in the Gremlin SAML configuration screen within the Gremlin app.  Fetch the Certificate (Base64), the Login URL, and the Azure AD Identifier.
  1. In a separate window, open https://app.gremlin.com/settings/security and add the values from the previous step into the appropriate fields:some text
    1. Azure AD Identifier / Microsoft Entra Identifier goes into the Identity Provider Entity ID field.
    2. Login URL goes into the Identity Provider SSO URL field
    3. The contents of the Certificate (Base64) file go into the Identity Provider Certificate field. Note that if you are on Windows, you’ll want to open this file using Wordpad or Notepad. Otherwise, the value may not be formatted correctly.

At this point we’ve completed the basic SAML configuration.  You can choose to configure your SAML claims in Microsoft Entra ID, but that process is beyond the scope of this document.

Troubleshooting SAMLResponse

If you're getting an unexpected SAMLResponse from your IdP, try the following steps. These steps are based on the AWS Identity and Access Management user guide to viewing a SAML response in your browser.

First, open your browser's Developer Tools. In Chrome, you can do this from the View->Developer->Developer Tools Menu item.  Select the ‘Network’ tab and reset the capture log with the Clear button:

Proceed with your login attempt. After the login attempt, look for the POST request to https://api.gremlin.com/v1/users/auth/saml/acs. Here, you can inspect the payload and grab the base64-encoded SAML response from the IdP.  You can right-click the payload field to copy the value to the pasteboard.

If you're using MacOS, you can read the base64-encoded value by opening Terminal and running the following command:


xmllint --format <(pbpaste | base64 --decode)>

On Linux, you can use base64 to decode the value:


echo [enter your base64 value here] | base64 --decode
No items found.
This is some text inside of a div block.
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Health Checks
Command Line Interface
Updating Gremlin
Reliability Management (RM) Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Container security
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Configuring Role Based Access Control (RBAC)
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Managing Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users
Integration Agent for Linux
Test Suites
Restricting Testing Times
Process Exhaustion Experiment
Enabling DNS collection
Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML
AWS Quick Start Guide