Configuring authentication

To secure access to Instana, you can configure various authentication methods. Follow these steps to set up authentication for your Instana environment.

Standard authentication

Instana uses standard authentication with a username (email address) and password by default. To enhance the security, use multi-factor authentication (MFA) for all users, especially privileged accounts. If your organization uses an Identity Provider (IdP), configure it for Instana according to your existing policy. IdP addresses authentication, MFA enforcement, password complexity, and password rotation requirements. If your organization does not use an IdP, enable two-factor authentication (2FA) upon creating your Instana account to mitigate the risk of identity theft.

SAML authentication and authorization

Instana's SAML implementation works with all compliant IdPs. The following IdPs are verified to work out of the box:

This list is not complete and is updated as other options are validated:

Quick start guides

For IdPs without a quickstart guide, see the following sections.

Getting started

To activate SAML, you must create a SAML application for Instana in your IdP and assign it to individual users. Users that are created through SAML are automatically assigned the default role.

Self-hosted setups that previously missed creating the service provider key must create the service provider key and configure the service provider. For more information on how to configure a service provider, see Configuring a Service Provider.

After you activate SAML for a tenant, you can log in to Instana only by using SAML. To make changes to an active SAML configuration, you must delete the current configuration and create a new one. You can delete the SAML configuration either through the through API by using a token with sufficient permissions or by using the Delete button in the SAML Configuration dialog in the Instana UI.

Instana supports two methods for configuring SAML with your IdP:

  • Automated configuration by exchanging metadata files
  • Manual configuration by entering the required values into your IdP

You can configure both of these methods in the "Configure authentication - SAML" dialog in Instana.

The accepted token lifetime for SAML authentication is between 1 and 200 days. This range covers the default settings for most SaaS and OnPrem IdPs.

SAML settings
Figure 1. SAML settings

Automatic configuration

Some identity providers (IdPs) support automatic SAML configuration through metadata file exchange. To configure SAML authentication automatically:

  1. From the navigation menu in the Instana UI, go to Settings > Security & access > Identity providers > SAML.
  2. Enter the email ID and service provider(SP) entity ID in the Configure authentication - SAML dialog.
  3. Select **Automatic if your IdP allows uploading Instana metadata.
  4. Click Download Instana metadata.
  5. Upload the downloaded Instana metadata to your identity provider.
  6. Download the IdP metadata from your IdP.
  7. Click Choose file for uploading to Instana and upload your IdP metadata to Instana.
  8. Open a new incognito tab or a different browser and attempt to log in to Instana using your IdP credentials to verify the configuration.

Manual configuration

You can use manual configuration if your identity provider does not allow you to upload Instana metadata. For manual configuration, you must enter the metadata values for the SAML app. To avoid errors, copy and paste the required values from the Configure authentication - SAML dialog in Instana UI.

To configure SAML authentication manually:

  1. From the navigation menu in the Instana UI, go to Settings > Security & access > Identity providers > SAML.
  2. Enter the email ID and service provider(SP) entity ID in the Configure authentication - SAML dialog.
  3. Select Manual.
  4. In your IdP, create a SAML app by using the values that are provided in the Instana UI. For more information about the values, see Instana metadata values,
  5. Download the IdP metadata from your IdP.
  6. Click Choose file for uploading to Instana and upload the IdP metadata.
  7. Open a new incognito tab or a different browser and attempt to log in to Instana using your IdP credentials to verify the configuration.

Instana metadata values

The following Instana metadata values are required to connect your identity provider to Instana:

  • Service Provider (SP) entity ID

    The Service Provider (SP) entity ID that Instana uses to communicate with your identity provider (IdP) is your tenant name.

  • Name ID format The SAML Name ID Format must be set to EMAIL by using the format identifier: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

  • Assertion consumer service (Single Sign-On) URL

    The Assertion Consumer Service (ACS) URL, also known as the Single Sign-On URL, is a combination of a fixed part from Instana and your tenant name.

    The URL format is as follows:

    https://instana.io/auth/signIn/saml/callback?client_name=SAML2Client\<Tenant Name>
    

    For example, if your tenant is instana, then the resulting URL would be:

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

    Central, IdP-initiated Logout is supported.

    The logout URL is fixed and does not require any variable parts. You can use the following URL 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.

Configuring SAML in the core.secret

To display the SAML item in the navigation pane, configure core.secret as follows:

  1. Enter mykeypass as the keyPassword.

     # SAML configuration
     serviceProviderConfig:
     # Password for the key/cert file
     keyPassword: mykeypass
    
  2. Create the key by running the following command:

    openssl genrsa -aes128 -out key.pem 2048
    
  3. Create the certificate by running the following command:

    openssl req -new -x509 -key key.pem -out cert.pem -days 365
    
  4. Combine the key and certificate into a single file by running the following command:

    cat key.pem cert.pem > sp.pem
    

OpenId Connect authentication and authorization

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

Configuration

To locate the configuration form, from the navigation menu in the Instana UI, click Settings > Security & Access > Identity Providers.

Configure authentication - OIDC
Figure 2. Configure authentication - 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: Use a discovery URL of your OIDC configuration, and Instana fetches it automatically.

  • 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.

After OIDC is activated for a tenant, you have no other way to log in to Instana. The OIDC configuration can be deleted through API by using a token with enough permissions.

Google single sign-on (SSO)

You can enable Instana's preconfigured Google single sign-on for your organization. Single sign-on is a tenant setting. When you enable SSO, it is applied to all the tenant units in your organization. The Instana users who are created through Google SSO are added to the built-in user group "default".

To enable Google SSO, complete the following steps:

  1. From the navigation menu in the Instana UI, click Settings > Security & Access > Identity Providers.
  2. Select Preconfigured Google SSO.
  3. In the Allowed domains field, enter the domains that match your organization's email address. For example, @instana.com. Use commas to separate multiple domains.

Enter domains that your organization owns. Do not use domains that are external to your organization, such as "@gmail.com," as it grants access to everyone with an email address at that domain.{: note} 4. Click Save.

The users with email address at the domains that are listed in the Allowed domains field are allowed to sign in as new users on Instana.

The users who received access to Instana through Google SSO can access Instana even if you change or remove the allowed domains later. To revoke access for a user, remove the user from Instana.

Setting session timeout

You can set session timeout for Instana. The session timeout is applied at the tenant level.

  • Idle session timeout: The maximum duration for which a tab in the browser with Instana GUI can remain hidden. If you access the Instana UI and switch to another tab in the browser, the session expires after the set duration. You need to log in to the Instana UI again. The default value is 8 hours.
  • User session timeout: The maximum duration that a user can remain logged in after the user logs in to the Instana GUI. The session expires after the set duration. The user needs to log in to the Instana UI again. The default value is 7 days. Idle session timeout takes precedence over user session timeout.

To set session timeout, complete the following steps:

  1. From the navigation menu in the Instana UI, click Settings > Security & Access > Session timeouts.
  2. Set the timeout duration.
  3. Click Save.