Standard Authentication

Standard authentication with username (email address) and password is the default method securely provided by Instana.

Two-Factor Authentication (2FA)

Instana also offers 2FA to provide increased security. With 2FA activated, a QR code will be shown that should be scanned with an app like Authy, Duo, or Google Authenticator.


NOTE: Once 2FA is activated for an account, the user will have to use the second factor for every login. Please make sure to store scratch codes securely for when there is no device access. Without device and scratch codes, access to Instana is not possible.

Single Sign-On (SSO)

Instead of standard authentication, single sign-on can also be enabled for your organization. We currently support Google as our SSO provider.

In order to activate this authentication method for your organization, a domain filter must be specified under “Management Portal” -> “Tenant Authentication”.

Users created through SSO will be assigned the “default” role upon creation.

Enter a domain filter that matches your organization’s email address(es). For example, the filter is what we use. Multiple filters can be provided, separated by a comma.

Single Sign-On

To change the SSO settings, you first need to deactivate SSO and then reenable it with the desired changes.

NOTE: Single sign-on is a tenant setting, meaning that once enabled it is active for all of your organization’s tenant units. Please make sure to not use a generic filter such as as this would grant access to everyone with a gmail account.

Configuring Single Sign-On for On-Premises Installation

If you want to use Single-Sign On in On-Premises Installation, you first need valid Google credentials. The easiest way is to simply following the Google description.

  1. Login to your Google (company) account and navigate to the API Credentials section to create the needed OAuth credentials. Single Sign-On On-Premises

  2. Choose type “Web application”.

  3. As the authorization redirect url, please use https://YOUR_INSTANA_BACKEND/auth/signIn/sso/oAuth Single Sign-On On-Premises .

  4. Click on “Create” and save your new Google Client ID & secret.

  5. In your settings.yaml file (package-based install) or settings.hcl file (container-based install), enter the new credentials.

  6. Run instana-configure (package-based install) or instana update (container-based install).

  7. Now you should see the Single-Sign On button in your Instana login form. Don’t forget to create a filter as described above to give new users the ability to login to Instana.

LDAP Authentication (On-Premises only)

On-Premises users have the option of provisioning authentication through OpenLDAP and Active Directory. Users authenticate against these third party providers, after which Instana fetches the roles and subsequent permissions for the now authenticated user. Once LDAP authentication is activated users cannot log in with their previous username & password combination, only the corresponding LDAP credentials are verified.

Users created through LDAP will be assigned the “default” role upon creation.

To use LDAP as the authentication method, you need to configure the corresponding config values in the Manangment Portal under Tenant Authentication. The configuration form is under the LDAP tab.

To persist the LDAP configuration you need to enter a username and password at the end of the form, this user will be added as owner you can change that after the initial setup. Once this has been configured and activated, other users matching the group query will be added to Instana with the default role. You can set the roles by user as described in Access Control.



Configuring LDAP can be quite challenging. Our guide on how to use ldapsearch to find the correct settings for LDAP should help.


LDAP Server URL (ldap://host:389 or ldaps://host:636)


The LDAP read only user. It needs to have sufficient rights to list groups through group_query or if you allow anonymous access for it


Password for read only user


The base for queries (dc=instana,dc=com)

Group Query:

The query to list a group or a set of groups with members having access to Instana (ou=Instana)

Group Member Field:

Name of the field containing DNs of users listed through group_query (uniqueMember)

User Query Template:

Template to query the user, for instance (uid=%s)

Email Field:

The name of the field where to find the email address (mail)


User Dn Mapping(optional):

The field (e.g. distinguishedName) which contains the users dn


The field the users are referenced within the group by the value of this attribute (if not DN is used)

Owner Username:

The user to be related in instana as owner user. A login is tried as a test before the settings are saved.

Login Password:

The passwort of the instana onwer user.


Connecting through LDAPS can be as easy as providing ldaps://url:636. In case the server only accepts an encryption stronger than what is provided by your Java 8 installation, cryptography extension need to be used. It can be downloaded from Oracle and configured as described on the JCE documentation page.

Currently Supported Authentication Provider

  • OpenLDAP
  • Active Directory

Example Configurations

Microsoft Active Directory - Example 1

For most situation the sAMAccountName is used as the login name (the name the user types in when authenticating). The internal representation of a user in Active Directory is the DN (distinguishedName) which does not always contain the sAMAccountName. In this case it needs to be mapped to the distinguishedName which is retrieved through the Group Query. The mapping is happening through the field User Dn Mapping.


Microsoft Active Directory - Example 2

In other cases we get the distinguishedName directly with the DN. In this case the mapping settings can be left empty.


OpenLDAP - Example

In generic LDAP servers the fields are named differently than in Active Directory setups. This example config is actually working as the LDAP server is open to the public as a test server. Usually all it takes to setup OpenLDAP with Instana is the Group Query, where you can omit the base part of the query. For instance the complete group name is ou=mathematicians,dc=example,dc=com, but we set the base to dc=example,dc=com, hence we can shorten the Group Query, as the base is added automatically.


SAML authentication and authorization

Currently Verified IdPs

The Instana SAML implementation is fully standard compliant and should work with all compliant IdPs. The following IdPs have been verified by our team to work out of the box.

This list is by no means complete and will grow over time as we validate other options:

Quick start guides

Please follow the next few paragraphs for IdPs without a quickstart guide.

Getting started

Activating SAML requires the creation of a SAML-app for Instana in your IdP. Individual users will be able to access Instana after assigning the newly created app to them.

Users created through SAML will be assigned the “default” role upon creation.

NOTE: Once SAML is activated for a tenant there will be no other way to log into Instana.

We support two ways of configuring Instana and your IdP to enable SAML.

  • Mostly automated by exchanging metadata
  • Manually by entering the required values into your IdP

Both use the same configuration dialog in Instana as the only step required in Instana is to upload the IdP-metadata.

Note The accepted token lifetime for SAML-authentication is 200 days. That means your IdP can send tokens with a lifetime anywhere between 1 and 200 days. This value has been chosen since it covers all the currently known default settings for SaaS and OnPrem-IdPs.


Option 1: Automatic configuration of IdP and Instana

Some IdPs provide the capability to activate SAML via a simple exchange of metadata files.

Simply follow these steps to get going:

  1. Download Service Provider Metadata from the link provided in the configuration dialog.
  2. Upload the file from step 1 into your IdP to create the required SAML settings.
  3. Download the IdP-metadata from your IdP
  4. Provide the IdP-metadata to Instana using the upload button in the configuration UI
  5. Start using Instana

Manual configuration of the the IdP

For manual configuration you will have to type in a few values. We highly recommend to copy’n’paste those values from our configuration UI (see above) to avoid confusion.

The following steps will guide you through the process:

  1. Create SAML-app in your IdP using the values provided in the setup UI
  2. Download the IdP-metadata from your IdP
  3. Provide the IdP-metadata to Instana using the upload button in the configuration UI
  4. Start using Instana

The following paragraphs are only here for completeness sake. Please copy’n’paste the generated values directly from our UI.

Service Provider (SP) Entity ID

The SP entity ID Instana uses when talking to your IdP is your tenant name.

Name ID Format

The SAML Name ID Format must be set to EMAIL

Assertion Consumer Service / Single SignOn URL

The Assertion Consumer Service (ACS) URL (also called Single SignOn URL in some cases) is a combination of a fixed part from Instana and your tenant name:\

e.g. if your tenant is called instana then the resulting URL would look like this:

Logout URL

We support central, IdP-initiated Logout.

The logout URL has no variable part and can be used directly: