Configuring authentication

Follow the steps to configure authentication.

Standard authentication

Standard authentication, with username (email address) and password, is the default authentication method for Instana.

To mitigate the risk of identity theft, use multi-factor authentication (MFA) for all users, especially for privileged accounts. If your organization is relying on an Identity Provider (IdP), configure it for Instana use according to your existing policy because IdP addresses authentication, MFA enforcement, password complexity, and password rotation requirements. In case IdP is not used, enable two-factor authentication (2FA) as soon as possible upon creating your Instana account to mitigate the risk of identity theft.

Two-factor authentication (2FA)

The 2FA option offered by Instana provides enhanced security in comparison to standard authentication.

2FA

When 2FA is activated, a QR code is displayed. You can scan this QR code with an authentication app, like Authy, Duo, or Google Authenticator, to create an account in the app. This account shows the rotating 2FA code. rotating 2FA code. After 2FA is activated for an account, you must use the 2FA code for every login.

Scratch codes serve as a backup in case you ever lose access to your authentication device. Five 8-digit codes are shown to you immediately after activating 2FA, and each of them can be used only once. Without authentication device and scratch codes, access to Instana is not possible.

Codes

SAML authentication and authorization

Verified IdPs

The Instana SAML implementation is fully standard compliant and needs to work with all compliant IdPs. The following IdPs are verified to work out of the box.

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

Quick start guides

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 can access Instana after the newly created app are assigned to them.

Users who are created through SAML are assigned the "default" role upon creation.

NOTE: Once SAML is activated for a tenant, there is no other way to log in to Instana.

Two ways of configuring Instana and your IdP to enable SAML are supported:

  • 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 that your IdP can send tokens with a lifetime in the range 1 - 200 days. This value is chosen since it covers all the currently known default settings for SaaS and OnPrem-IdPs.   

SAML

Automatic configuration of IdP and Instana

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

Follow these steps to get going:

  1. From the link that is provided in the configuration dialog, download Service Provider Metadata.
  2. Upload the file to create the required SAML settings.
  3. Download the IdP-metadata from your IdP.
  4. Using upload in the configuration UI, and provide the IdP-metadata to Instana.
  5. Start using Instana.

Manual configuration of the IdP

For manual configuration, you must type in a few values. It's recommended to copy and paste those values from the configuration UI to avoid confusion.

The following steps guide you through the process:

  1. Create SAML-app in your IdP by using the values provided in the setup UI.
  2. Download the IdP-metadata from your IdP.
  3. Click upload in the configuration UI, and provide the IdP-metadata to Instana.
  4. You can start to Instana.

The following paragraphs are only here for completeness sake. Copy and paste the generated values directly from the UI.

Service Provider (SP) entity ID

The SP entity ID that Instana uses when it talks to your IdP is your tenant name.

Name ID format

The SAML Name ID Format must be set to EMAIL.

Assertion consumer service and 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\<Tenant Name>

For example, if your tenant is called instana, then the resulting URL would look as follows:

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

Logout URL

Central, IdP-initiated Logout is supported.

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

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

Username

The username is generated from SAML attributes that are provided by the IdP during login.

The general recommendation of X500-style attributes and their well-known aliases are followed.

The following logic is applied to extract a username from the provided attributes:

  • Check whether a display name was provided as one of the following attribute names: name/displayname/cn/urn:oid:2.5.4.3.
  • Check whether a first name was provided as one of the following attribute names: firstname/givenname/gn/userfirstname/urn:oid:2.5.4.42.
  • Check whether a last name was provided as one of the following attribute names: lastname/sn/userlastname/surname/urn:oid:2.5.4.4.

The display name takes precedence over all other options. If the display name is not found, but only a first name, a last name or both of them are found, then found names are used. If nothing is found, the string before the @-sign from NameID (which is the user-eMail) is used to generate a name.

Name changes are reflected after a user are logged out since it requires an exchange with the IdP.

OpenId Connect authentication and authorization

The Instana OIDC integration is standard compliant and is therefore supported by all current OIDC ready IdP's.

Configuration

The configuration form can be found next to all other auth procedures in the settings section under Authentication > Identity Providers > OpenID Connect.

OIDC

To configure Instana as a service provider for your IdP side application. You need the following values of your IdP.

  • ClientID: This is the identifier that is assigned to your application by the identity provider.

  • Client Secret: This is a token that is used by Instana to verify the authenticity of the response from the identity provider. This value is a secret ke and is kept secure.

  • Discovery URL or IdP Metadata: The IdP configuration can either be stored dynamically as discovery url or it can be uploaded with a valid static metadata file.

  • Admin/Owner account: An email address of an OIDC account must be entered here. The owner rights are initially granted to this account after the switch to the OIDC flow, all other will be assigned the default rights.

Furthermore, the following values are important for Idp-side configuration.

  • Redirect URL: The redirect URI that you set in the IdP determines where it sends responses to Instana.
  • End Session URL / Sign out URL: For IdP-initiated logout.

NOTE: Once OIDC is activated for a tenant, there is no other way to log in to Instana.

Google Single Sign-On (SSO)

Alternatively, you can enable Instana's preconfigured Google Single Sign-On for your organization.

To enable this authentication method, go to Settings > Authentication > Google SSO, and specify the domain filter.

Instana users who are created through Google SSO are added to the built-in user group that are named "default".

Enter a domain filter that matches your organization's email addresses. For example, the filter @instana.com is used. Multiple filters can be provided, and separated by a comma.

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