How do I configure SAML for Azure Active Directory for AppDynamics? (2024)

The AppDynamics Controller can use an external SAML (Security Assertion Markup Language) identity provider to authenticate and authorize users.

Microsoft Azure Active Directory (Azure AD) simplifies authentication for developers by providing identity as a service, with support for industry-standard protocols such as OAuth 2.0 and OpenID Connect, as well as open-source libraries for different platforms to help you start coding quickly.

Azure AD can be used to authenticate users with SAML protocol. It can also use user’s Active Directory group membership as the source of “roles” that will drive authorization in AppDynamics.

This article describes that combined process.

Azure AD and AppDynamics Authentication and Authorization Flow Explained

Configure Azure AD for AppDynamics

Configure AppDynamics Controller

Validating the Configuration

Reference Links

Azure Active Directory identity authenticates users for access. Azure AD security groups are mapped to AppDynamics roles via Enterprise Application roles and are used to grant user permissions.

In the context of authentication, AppDynamics Controller is considered an “initiating party” and Azure AD is considered an “identity provider”. Azure AD holds user identity in a user record that includes things like name, email, address, phone and unique identity within its “userPrincipalName” attribute.

In Azure AD, a user can be a member of one or more “security groups”. Security groups can be nested, so when a user is a member of group A, and group A is part of group B, the user is also a member of group B.

Azure AD allows authentication by setting up one or more “Enterprise Applications”. Enterprise Applications are designed to establish trust and SAML authentication to third-party applications, such as AppDynamics Controller. Access to specific Azure AD Enterprise Applications can be scoped to all users in an organization or just some of them.

Azure AD Enterprise Applications map users and security groups to “roles”, which are configuration entities defined in the context of each Enterprise Application.

When Enterprise Application authenticates a user, it issues a SAML “token”. This XML document includes user identity and provides various “claims”, such as a user’s name, email, and roles. The “roles” claim lists the roles that are mapped to the user and to each of the user’s security groups in the context of Enterprise Application. The token is signed with a certificate.

AppDynamics Controller receives the SAML token, validates its digital signature, and uses user identity to either create a new account or find an existing one in AppDynamics. If there are Azure AD roles listed in the claim, AppDynamics Controller can map each of those to AppDynamics role or roles.

AppDynamics “roles” are associated with AppDynamics permissions. By possessing a certain role, the user is granted access to view and do specific things.

Step 1 - Prepare Azure AD Identities

Step 2 - Prepare Azure AD Security Groups

Step 3 - Assign Azure Active Directory users to security groups

Step 4 - Create Enterprise Application in Azure Active Directory using AppDynamics template

Step 5 - Create Roles for AppDynamics Enterprise Application

Step 6 - Configure Role to Group Mapping in AppDynamics Enterprise Application

Step 7 - Configure AppDynamics Enterprise Application Claims and Connection to AppDynamics Controlle...

Step 1 - Prepare Azure AD identities

Your directory services should contain the user principals you expect to use. Optionally, those can be DirSync’ed with your on-premises directory.

In this example, we have 4 Azure AD users that we will use to authenticate to AppDynamics:

• Agent Smith
• Agent Jones
• Agent Brown
• Agent Colson

Step 2 - Prepare Azure AD Security Groups

Although it’s possible to associate the AD user record directly with an Enterprise Application role, the mapping is strictly 1:1, so, in this configuration, the user would only have a single role.

Instead, you need to create AD security groups and assign the Enterprise Application role to the group. That way, users with more than one security group membership can be assigned more than one Enterprise Application role.

In this example, we’ve created 4 AD security groups to which we will assign Enterprise Application roles:

• AppD-SecGroup-Administrators
• AppD-SecGroup-AllGroups
• AppD-SecGroup-Power Users
• AppD-SecGroup-Read Only

Step 3 - Assign AzureAD users to the AD security groups

Use Azure Active Directory management tools, or any other tools you use, to assign AD users to AD security groups. Optionally, you can also assign AD security groups to AD security groups.

In this example, we’ve put certain users into certain groups, and combined all groups into the “AppD-SecGroup-AllGroups” group:

Step 4 - Create an Enterprise Application in Azure AD using AppDynamics template

In this part, we create Azure AD Enterprise Application that points at your AppDynamics Controller using a template provided in Azure Marketplace.

Though the steps are documented in the “Configuring and testing Azure AD Single Sign-On” section, these instructions are *not* fully correct. One section, “Creating an AppDynamics test user”, is completely wrong. Here is the correct sequence of steps:

1. Create a new AppDynamics application
2. Go Azure AD\Enterprise Applications\All Applications and click New Application
3. Search for AppDynamics under Business Management
4. Select it and click Add

Note: This template can only be used to connect to AppDynamics SaaS Controllers. For on-premise controllers, you must use generic Enterprise Application configuration instead. The configuration steps are virtually identical.

Step 5 - Create Roles for AppDynamics Enterprise Application

To send Azure AD security groups as roles when using a newly created AppDynamics Enterprise Application, you must first create the roles to be used by Enterprise Application. At the time of writing, Azure management UI does not provide ability to create those roles.

Instead you must use the Azure AD Graph Explorer tool to add roles programmatically. The steps are nicely documented in Microsoft’s Azure educational documentation:

1. Follow the steps in the “Open Azure AD Graph Explorer in another window” chapter, sections a, b, c and d to grantDirectory.AccessAsUser.All, Directory.Read.All and Directory.ReadWrite.All to the administrative account that will perform additional configuration. This is a one-time configuration step.

You will be signed out and signed in with the following style prompt:

2. Before proceeding, get the Object ID of the newly created AppDynamics Enterprise Application from the properties tab:

Select the the newly created AppDynamics Enterprise Application's Object ID from the Properties tab

3. Now follow the steps “Open Azure AD Graph Explorer in another window” chapter, sections e-j to read the current roles and create new ones.As the instructions state, switch to the “Beta” version and run a GET query against https://graph.microsoft.com/beta/servicePrincipals endpoint.

4. Find your Enterprise Application by looking for its Object ID:

5. Now run a new GET query against https://graph.microsoft.com/beta/servicePrincipals/<objectID> with the Object ID of your AppDynamics Enterprise Application.

6. Look for and extract appRoles object, which contains a JSON array of custom objects that are the current application roles. Put the data into a text editor.

7. In your newly created AppDynamics Enterprise Application, you should only have “msiam_access”.

8. You will now need to generate new roles for your application by constructing a new JSON object and executing a PATCH operation against the same management endpoint.A few notes on that object:

• You must preserve “msiam_access” role.
• You also must generate new GUIDs for each of the roles
• The role names must be unique

Here is an example JSON file defining the following roles:

msiam_access (existing)
AppD-AppRole-Administrators
AppD-AppRole-PowerUsers
AppD-AppRole-ReadOnly
AppD-AppRole-All

The names of roles are in orange, and unique IDs of items are in blue. A description field is not necessary. Use your favorite GUID generator (for example, https://guidgenerator.com) to make those unique identifiers:

{
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "msiam_access",
"displayName": "msiam_access",
"id": "48383f87-53cf-4ff0-ac40-06798faf26a8",
"isEnabled": true,
"origin": "Application",
"value": null
},
{
"allowedMemberTypes": [
"User"
],
"description": "This role will be administrators",
"displayName": "AppD-AppRole-Administrators",
"id": "BFECB407-1121-4B5C-8468-76BEE81B5F68",
"isEnabled": true,
"origin": "ServicePrincipal",
"value": "AppD-AppRole-Administrators"
},
{
"allowedMemberTypes": [
"User"
],
"description": "This role will be power users",
"displayName": "AppD-AppRole-PowerUsers",
"id": "C0003602-0404-49B0-9A5C-3F29C56DA451",
"isEnabled": true,
"origin": "ServicePrincipal",
"value": "AppD-AppRole-PowerUsers"
},
{
"allowedMemberTypes": [
"User"
],
"description": "This role will be read only",
"displayName": "AppD-AppRole-ReadOnly",
"id": "5924E9BE-4DD2-4782-8887-F7522F4C6A47",
"isEnabled": true,
"origin": "ServicePrincipal",
"value": "AppD-AppRole-ReadOnly"
},
{
"allowedMemberTypes": [
"User"
],
"description": "This role will be all groups",
"displayName": "AppD-AppRole-All",
"id": "F21990FD-CA27-4D37-A2E8-08CF9A1AD28A",
"isEnabled": true,
"origin": "ServicePrincipal",
"value": "AppD-AppRole-All"
 }
 ]
}

9. Using the constructed JSON, execute the PATCH operation https://graph.microsoft.com/beta/servicePrincipals/<objectID> with the Object ID of your AppDynamics Enterprise Application:

You should get a success 204 error code.

Step 6 - Configure Role to Group Mapping in AppDynamics Enterprise Application

Now that the roles have been created, use the Users and Groups tab of AppDynamics Enterprise Application to map the AD security groups to the newly created roles.

Example:our AD groups are mapped to Enterprise Application Role in the following way:

The final result should reflect this:

Step 7 - Configure AppDynamics Enterprise Application Claims and Connection to AppDynamics Controller

We are finally ready to connect AppDynamics Enterprise Application to AppDynamics Controller.

Resuming Microsoft’s Active Directory SaaS AppDynamics tutorial instructions in the “Configuring Azure AD Single Sign-On” section, specify the following values in AppDynamics Enterprise Application Single Sign-on tab:

To get Certificate (Microsoft document subtopic 4):

• On the SAML Signing Certificate section, click “Certificate (Base64)” and then save the certificate file on your computer.

Click "Save". Your final screen should look like this:

Scroll to the bottom of the page and click "Configure AppDynamics."

Find the values of Azure AD Single Sign-On Service URLand Azure AD Sign Out URLin theQuick Referencesection:

Notes on Microsoft’s Tutorial:
Azure Active Directory integration with AppDynamics Document

The referenced Tutorial: Azure Active Directory integration with AppDynamics section called “Configuring Azure AD Single Sign-On” is incorrect. Do not execute this section of the referenced tutorial.

The “Assigning the Azure AD test user” section is only necessary if you turn on “User assignment required” on the Properties of AppDynamics Enterprise. It is not a default setting, so these steps are not required.

Here we will follow the steps in the AppDynamics document SAML Authentication, in the Authenticating SAML Authentication section.

Step 1 - Sign in to AppDynamics

In AppDynamics UI, sign in with administrative privileges.

Step 2 - Prepare AppDynamics Roles

In AppDynamics with administrative use in the Roles tab, prepare the roles and assign permissions that you intend to map to roles sent by Azure AD Enterprise Application.

Step 3 - Configure SAML Authentication

Go to Administration and switch to the Authentication Provider tab. Click the SAML tab and complete each section:

In this screenshot, we are mapping the Azure AD Enterprise Application role “AppD-AppRole-PowerUsers” to AppDynamics’ “AppD-Role-PowerUsers” role.

Mapping the Azure AD Enterprise Application role "AppD-AppRole-PowerUsers" to AppDynamics' "AppD-Role-Power-Users"

ClickSave.

The final configuration may look like this:

SAML Configuration on AppDynamics Authentication Provider

Step 1 - Set up SAML Debugging Tools in your Browser

Troubleshooting SAML authentication is best done with Chrome SAML DevTools extension or Firefox SAML-tracer. When neither is available, SAML data in the response is just base64 encoded and can easily be turned back into readable XML using any base64 decoder.

Step 2 - Initiate Login in AppDynamics

User that comes to “initiating party” - AppDynamics Controller and specifies their account name. Because the Controller is enabled for SAML, the user is not prompted for credentials by AppDynamics. Instead, the Login dialog only offers a “Login” button.

Once Login is clicked, the user is redirected to Azure AD for authentication.

Step 3 - Sign in into Azure AD using AppDynamics Enterprise Application

User specifies the username.

User specifies the password and clicks “Sign in”.

Azure AD collects information about user including the user name and roles (mapped from AD security groups) and sends them to AppDynamics Controller in SAML token:

Azure AD SAML token sent to AppDynamics Controller

The token contains NameID with user identity:

<Subject>
<NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">agentsmith@danielodievichhotmail.onmicrosoft.com
</NameID>
<SubjectConfirmation
Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData
InResponseTo="_45040ca0-c2f1-48f4-b870-78281fc2472d"
NotOnOrAfter="2018-05-21T23:16:08.456Z"
Recipient="https://appdynamics639.saas.appdynamics.com/controller/saml-auth?
accountName=appdynamics639"/>
</SubjectConfirmation>
</Subject>

It also contains Group-Membership claim with roles assigned to this identity:

<AttributeStatement>
<Attribute
Name="http://schemas.microsoft.com/identity/claims/tenantid">
<AttributeValue>a99339a7-e38d-42ff-839c-72996be62ccb</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
<AttributeValue>fa68aefa-e648-4f8c-b18e-83181ab2958a</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.microsoft.com/identity/claims/displayname">
<AttributeValue>Agent Smith</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.microsoft.com/identity/claims/identityprovider">
<AttributeValue>https://sts.windows.net/a99339a7-e38d-42ff-839c-72996be62ccb/</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
<AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>AppD-AppRole-Administrators</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
<AttributeValue>Agent</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
<AttributeValue>Smith</AttributeValue>
</Attribute>
<Attribute
Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
<AttributeValue>agentsmith@danielodievichhotmail.onmicrosoft.com</AttributeValue>
</Attribute>
<Attribute
Name="Group-Membership">
<AttributeValue>AppD-AppRole-Administrators</AttributeValue>
</Attribute>
</AttributeStatement>

Step 4 - Review resulting User Mapping

The table above is reflected in the following screenshots:

Agent Smith: AdministratorsAgent Brown: Power Users

Agent Jones: Read Only

Agent Colson: All Groups

https://docs.microsoft.com/en-us/azure/active-directory/active-directory-enterprise-app-role-managem...

https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/appdynamics-tutorial

https://docs.appdynamics.com/display/latest/SAML+Authentication#SAMLAuthentication-EnablingSAMLAuthe...

https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio

https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/