Authentication

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.

2FA

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” -> “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 @instana.com is what we use. Multiple filters can be provided, separated by a comma.

Single Sign-On

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 @gmail.com as this would grant access to everyone with a gmail account.

Configuring Single Sign-On for on premise

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

  1. Login to your Google (company) account to create the needed OAuth credentials Single Sign-On On premise

  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 premise

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

  5. In your /etc/instana/settings.yaml, type in the new credentials

o_auth:
    google:
      client_id:
      client_secret:
  1. Execute instana-configure

  2. 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-prem only)

On-prem 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 obtain owner access the stated user.email from /etc/instana/settings.yaml should match a valid LDAP user’s email.

To use LDAP as the authentication method, you need to configure the corresponding config values in your settings.yaml - located in the root directory of your Instana installation.

Once this has been configured and activated, the users matching the group query will be added to Instana with the default role “default.” You can set the roles by user as described in Access Control.

#LDAP configuration
ldap:
  url: // LDAP Server URL (ldap://host:389 or ldaps://host:636)
  base: // a base for every query (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_dn_mapping: // (optional) the field (e.g. distinguishedName) which contains the users dn
  user_field: // (optional) the field the users are referenced within the group by the value of this attribute (if not DN is used)
  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)
  ro_user: // user for initial LDAP bind. It needs to have sufficient rights to list groups through group_query
  ro_password: // password for initial LDAP bind

TLS

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

Configuration

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

Example Configurations

Microsoft Active Directory - Example 1

For most situation the sAMAccountName is used as the loginname (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.

config:
  #LDAP configuration for Microsoft Active Directory
  ldap:
    url: ldap://your-server.net:389
    base: DC=mycompany,DC=net
    group_query: (CN=instana_users_test)
    group_member_field: member
    user_dn_mapping: distinguishedName
    user_field:
    user_query_template: (sAMAccountName=%s)
    email_field: mail
    ro_user: instana-admin-ro
    ro_password: xyzxyzxyz

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.

config:
  #LDAP configuration for Microsoft Active Directory
  ldap:
    url: ldap://your-server.net:389
    base: DC=mycompany,DC=net
    group_query: (|(cn=Application_Monitor__adm)(CN=Operations_team_adm))
    group_member_field: member
    user_dn_mapping:
    user_field:
    user_query_template: (CN=%s)
    email_field: mail
    ro_user: instana-admin-ro
    ro_password: xyzxyzxyz

OpenLDAP - Example

In generic LDAP servers the fields are named differently than in Active Directory setups. This example config is actually working as the forumsys.com 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.

  #LDAP configuration for OpenLDAP server
  #This is a working configuration with an example LDAP server; please adjust the settings according to your LDAP server. For tests you can use "euler" or "gauss" as login-names with the same password as it set for the ro_user.
  ldap:
    url: ldap://ldap.forumsys.com:389
    base: DC=example,DC=com
    group_query: (ou=mathematicians)
    group_member_field: uniqueMember
    user_dn_mapping:
    user_field:
    user_query_template: (uid=%s)
    email_field: mail
    ro_user: cn=read-only-admin,dc=example,dc=com    
    ro_password: password

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:

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.

SAML

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:

https://instana.io/auth/signIn/saml/callback?client_name=SAML2Client\

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

https://instana.io/auth/signIn/saml/callback?client_name=SAML2ClientInstana

Logout URL

We support central, IdP-initiated Logout.

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

https://instana.io/auth/signOut/saml/callback