Configuring Active Directory

Edit online

Classic Active Directory requires more configuration to get running with SAML than its Azure sibling. Follow the regular SAML-documentation for that one.

The following guidance is for a classic Active Directory installation, not for Azure Active Directory.

Get the service provider metadata

Edit online

To make the configuration easier, a Service Provider metadata XML file is provided. It can be downloaded from the SAML settings dialog:

To make the configuration easier, a Service Provider metadata XML file is provided. You can download this file from Instana, go to Settings > Security & Access > Identity Providers.

To save the file for later use, click METADATA DOWNLOAD.

Creating the Relying Trust Partner

Edit online

  1. From the tools list, open AD FS Management.

    ADFS Management

  2. Select Add Relying Party Trust.

    Add Relying Party Trust

    Then, you are presented with a wizard for creating a Relying Party Trust, also known as SAML.

    Add Relying Party Trust 1

    The Select Data Source step of this dialog allows you to upload the service provider metadata that you downloaded from Instana. Upload the file and wait until Active Directory is done processing.

    Add Relying Party Trust upload

    Finish the remaining steps to create the new trust.

    You are then prompted with the AD FS Management default view, which now contains the newly created Relying Party Trust.

Add necessary attribute mappings

Edit online

Instana needs to receive the email address of an authenticated user. Therefore, you need to add a mapping to get the email address of each individual user that is mapped into the SAML-interaction.

Active Directory has some issues with doing this mapping correctly, so you need to help with a rule combination.

To add the rule, select the newly created Relying Party Trust, and click Edit Claim Issuance Policy ....

Edit Claim Issuance Policy

There might be no rules in there since it is just created.

Edit Claim Issuance Policy empty

Select Add Rule....

The next dialog guides you through the creation of the mapping rule.

Select Send LDAP Attributes as Claims from the list.

Edit Claim Issuance Policy LDAP Attribute as Claim

Give a name to the rule and select to map E-Mail-Address to E-Mail-Address.

Note: The menu also contains a field that is named NameID. However, you cannot use this field, the conversion is broken. The resulting configuration produces invalid SAML-messages.

Edit Claim Issuance Policy LDAP Attribute as Claim 2

Select Add Rule... to add Transform an Incoming Claim. This rule takes care of converting the email address into the NameID required by the SAML-standard.

Edit Claim Issuance Policy Transform incoming Claim

Select E-Mail Address as the incoming claim type, and Name ID as the outgoing claim type. Outgoing name ID format needs to be set to email for the actual conversion to take place.

Edit Claim Issuance Policy Transform incoming Claim 2

Then, you can see the following list of rules.

Edit Claim Issuance Policy overview

The order of these rules is important so double check that everything is where it is supposed to be.

That's it for the Active Directory side of things.

Finish configuration in Instana

Edit online

Connect Instana with AD. You already uploaded the Service Provider metadata from Instana to AD.

You must provide the IdP-Metadata from AD to Instana.

Complete the following steps:

First, you need to download the metadata file. Use a browser and navigate to https://<AD_HOST_NAME>/FederationMetadata/2007-06/FederationMetadata.xml, and make sure to replace <AD_HOST_NAME> with the name of the machine where the AD is running.

Store the downloaded file locally and open the Instana-saml_configuration dialog.

Select Click here to select IDP-Metadata-File for uploading and then click ACTIVATE.

Instana can be accessible by using SAML.

Logging on to Instana for the first time after SAML activation

Edit online

When you configure SAML authentication for Instana, you must enter an email address in the **"Enter an email to be automatically assigned to the owner group"** field. This email address is critical for maintaining administrative access to Instana after SAML is activated.

Assigning owner rights with email address

Edit online

The email address that you enter during SAML configuration serves as a bootstrap mechanism. It ensures that at least one user from your Identity Provider (IdP) can access Instana with administrative privileges immediately after SAML is activated.

This email configuration is essential because of the following reasons:

  • After SAML is activated, you can log in to Instana only by using SAML authentication.
  • The user whose email matches this field is granted owner rights.
  • This access is available even before you configure group mappings or assign roles to other users.
  • All other users who log in through SAML are assigned the default role, see Managing user access.

Logging on to Instana as the initial administrator

Edit online

To log in as the initial administrator after you activate SAML authentication, complete the following steps:

  1. Go to your Instana URL (for example, `https://your-tenant.instana.io`). You are automatically redirected to your Active Directory Federation Services (ADFS) login page.
  2. Log in with the credentials of the user whose email address **exactly matches** the email that you entered in the "owner group" field during SAML configuration. After successful authentication by your IdP, you are redirected back to Instana with full administrative access.

The initial administrator can then complete the following tasks:

  • Configure group mappings to assign roles to other users
  • Manage user access and permissions
  • Modify SAML settings if needed (by deleting and re-creating the configuration)

Important considerations

Edit online

  • Email address must match exactly: The email address in your Active Directory user profile must exactly match the email that you entered during SAML configuration.
  • Case sensitivity: Ensure that the email address matches in terms of case and formatting.
  • Account must be active: The user account must be active and accessible in Active Directory.
  • SAML is the only login method: After SAML activation, standard authentication with username and password is no longer available. Ensure that the owner group email is correct before you activate SAML.
  • Test in a separate browser: Before closing your current session, open an incognito window or different browser to test the SAML login and verify that the initial administrator can access Instana.
Troubleshooting initial login issues
Edit online

If you cannot log in after activating SAML, try the following troubleshooting steps:

  • Verify email address match: Confirm that the email in your ADFS user profile exactly matches the email entered during SAML configuration.
  • Check user account status: Make sure that the user account is active in Active Directory.
  • Verify SAML metadata exchange: Confirm that the IdP metadata was correctly uploaded to Instana and that the Instana metadata was correctly configured in ADFS.
  • Review ADFS logs: Check ADFS logs for authentication errors or SAML assertion issues.
  • API access for recovery: If you are locked out, you can delete the SAML configuration through the Instana REST API by using a token with sufficient permissions.
Mapping Active Directory Groups to Instana roles
Edit online

After SAML authentication is configured, you can map Active Directory groups to Instana roles to automatically assign users the appropriate permissions based on their AD group membership. This mapping enables centralized user management through your Active Directory.

Note: Instana does not directly link Active Directory groups to Instana roles. Instead, the mapping works through SAML assertion attributes in the following way.
  • ADFS sends group information: You configure ADFS to include AD group membership as attributes in the SAML assertion.
  • User logs in via SAML: When a user authenticates, ADFS sends a SAML assertion containing the user's group membership.
  • Instana receives the assertion: Instana extracts the group attributes from the SAML assertion.
  • Mapping rules apply: Instana's mapping rules match the SAML attribute values to Instana roles.
  • User is provisioned: The user is automatically assigned to the corresponding Instana roles.

This attribute-based approach follows the SAML standard and provides flexibility, but it requires configuration on ADFS (to send group information) and Instana (to map the attributes).

Prerequisites

Before configuring role mapping, verify the following prerequisites:

  • Complete the basic SAML configuration as described in the previous sections.

    Create the Instana roles you want to map to. For more information, see Managing user access.

  • Identify which Active Directory groups should map to which Instana roles.
  • Ensure that users are members of the appropriate AD groups.

You must configure ADFS to include Active Directory group membership as claims in the SAML assertion. This is done by adding claim rules to your Relying Party Trust in ADFS.

ADFS configuration includes the following steps:

  • Add claim rules to send group membership information.
  • Configure how group information is represented in the SAML assertion.
  • Specify which AD groups to send or send all group memberships.
  • Ensure that the claim values are consistent and easy to map.

For detailed instructions on configuring ADFS to send group claims, see the following references in Microsoft official documentation:

Consider the following key points for ADFS configuration:

  • Use a consistent attribute name for group claims (for example, "Group", "Role", or a custom name)
  • Use simple, lowercase values for group identifiers (for example, "instana-admins" instead of "CN=Instana-Admins,OU=Groups,DC=example,DC=com")
  • Test with a few groups first before sending all group memberships
  • Be aware that sending many groups can result in large SAML assertions

Before configuring Instana, verify that ADFS is sending group information in the SAML assertion by completing the following steps:

  1. Log in to Instana using SAML authentication.
  2. Use your browser's developer tools (F12) to inspect network traffic.
  3. Look for the SAML response (usually a POST to a callback URL).
  4. Decode the SAML assertion (it's base64 encoded) and look for group attributes.

A sample SAML assertion with group information:


<saml:Attribute Name="Group">
  <saml:AttributeValue>instana-admins</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="Group">
  <saml:AttributeValue>instana-developers</saml:AttributeValue>
</saml:Attribute>
Note: Browser extensions like "SAML-tracer" (available for Chrome and Firefox) make it easier to view and decode SAML assertions.

After ADFS is configured to send group information, create mapping rules in Instana to map the SAML attributes to Instana roles by completing the following steps:

  1. In the Instana UI, go to Settings > Security & Access > Identity Providers > Role mapping.
  2. Click Create mapping rule.
  3. Configure each mapping rule:
    • Key: The SAML attribute name (for example, "Group", "Role", or whatever you configured in ADFS)
    • Value: The exact value sent by ADFS for a specific group (for example, "instana-admins")
    • Role: Select the Instana role to assign users to (for example, "Administrators")
    • Team (optional): Assign users to a specific team
  4. Click **Save**.
  5. Repeat for each AD group that you want to map.
Example mapping rules:
Table 1. Example mapping rules
Key Value Role Team
Group instana-admins Administrators (optional)
Group instana-developers Developers (optional)
Group instana-viewers Viewers (optional)
Note: The Key and Value are case-sensitive and they must exactly match what ADFS sends in the SAML assertion.
For detailed information about mapping rules, their behavior, and advanced options, see IdP Role Mapping.

To verify that role mapping works correctly, complete the following steps:

  1. Try to log out of Instana completely as a test user who is a member of a mapped AD group.
  2. Try to log in back to Instana as a test user with SAML.
  3. On Instana the GUI, go to Settings > Security & Access > Users.
  4. Find the test user and verify they are assigned to the correct Instana roles.
  5. Verify the user has the expected permissions based on their role membership.
Note: Role assignments are updated each time a user logs in via SAML. If you change a user's AD group membership, they need to log out and log back in for the changes to take effect in Instana.
Important considerations
  • Attribute-based mapping: The mapping is based on SAML assertion attributes, not a direct AD-to-Instana role link.
  • Dynamic updates: Role assignments are updated at each login based on the current SAML assertion.
  • Multiple roles: Users can be members of multiple AD groups and are assigned to all corresponding Instana roles.
  • Case sensitivity: SAML attribute names and values are case-sensitive.
  • Exact matching: The value in your mapping rules must exactly match what ADFS sends.
  • Deny access option: You can configure Instana to deny access to users who don't match any mapping rules. For more information, see IdP Role Mapping.

If role mapping is not working as expected, try the following troubleshooting steps:

  • Verify SAML assertion: Use browser developer tools or a SAML tracer extension to confirm ADFS is sending group information.
  • 2. Check attribute names: Ensure that the "Key" in your Instana mapping rules matches the SAML attribute name exactly (case-sensitive).
  • 3. Check attribute values: Ensure that the "Value" in your mapping rules matches the SAML attribute value exactly (case-sensitive).
  • 4. Review ADFS claim rules: Verify the claim rules in ADFS are configured correctly and applied to the Instana Relying Party Trust.
  • 5. Test with a fresh login: Have the user log out completely and log back in to ensure that the latest SAML assertion is processed.
  • 6. Check for typos: Even small differences (spaces, capitalization) prevents matching.
  • 7. Review Instana logs: Check Instana logs for any errors that are related to SAML or role mapping.