How do I configure SAML for Azure Active Directory for AppDynamics?

[Christine.Chang]

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.

Table of Contents

Azure AD and AppDynamics Authentication and Authorization Flow Explained

Configure Azure AD for AppDynamics

Configure AppDynamics Controller

Validating the Configuration

Reference Links

Azure AD and AppDynamics Authentication and Authorization Flow Explained

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.

Configure Azure AD for AppDynamics

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 Azure AD 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:

Group	Members
AppD-SecGroup-Administrators	Agent Smith
AppD-SecGroup-AllGroups	Agent Colson AppD-SecGroup-Administrators AppD-SecGroup-Power Users AppD-SecGroup-Read Only
AppD-SecGroup-Power Users	Agent Brown
AppD-SecGroup-Read Only	Agent Jones

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 grant Directory.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:

AD Group	Enterprise Application Role
AppD-SecGroup-Administrators	AppD-AppRole-Administrators
AppD-SecGroup-AllGroups	AppD-AppRole-All
AppD-SecGroup-Power Users	AppD-AppRole-PowerUsers
AppD-SecGroup-Read Only	AppD-AppRole-ReadOnly

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 enable SSO	Single Sign-on Mode = SAML-based Sign-on
To connect to the Controller (Microsoft document subtopics 1, 2, 3)	Single Sign-on URL = https://<YOURTENANT>.saas.appdynamics.com Identifier (Entity ID) = https://<YOURTENANT>.saas.appdynamics.com/controller Check the “Show advanced URL Settings” checkbox Reply URL = https://<YOURTENANT>.saas.appdynamics.com/controller/saml-auth Leave the Relay State blank
To add roles as claims	Check “View and edit all other user attributes” Click “Add attribute” Specify “Group-Membership” in “Name” textbox Specify “user.assignedroles” in “Value” drop-down Leave “Namespace” textbox blank Click OK

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 URL and Azure AD Sign Out URL in the Quick Reference section:

You are now ready to configure the AppDynamics Controller to accept SAML authentication and authorization from this Enterprise Application.

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.

Configure AppDynamics Controller

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:

SECTION	SETTINGS
SAML Configuration	Login URL = value from “Azure AD Single Sign-On Service URL” For example, https://login.microsoftonline.com/a99339a7-e38d-42ff-839c-72996be62ccb/saml2 (your GUID will be different!) Logout URL = value from “Azure AD Sign Out URL” Typicaly lhttps://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0 Certificate = value from .cer file downloaded from Azure AD
SAML Attribute Mappings	Leave all 3 text boxes blank
SAML Group Mappings	SAML Group Attribute Name = Group-Membership Group Attribute Value = Multiple Nested Group Values Mapping of Group to Roles: Click + button to add new mapping Specify AppDynamics Enterprise Application role name in "SAML Group Name" Add necessary AppDynamics roles to the selector Click OK Repeat as necessary for all groups
SAML Access Attribute	Leave unchecked

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"

Click Save.

The final configuration may look like this:

SAML Configuration on AppDynamics Authentication Provider

Validating Configuration

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

Agent	AD Security Group	Enterprise Application Role	AppDynamics Role
Agent Smith	AppD-SecGroup-Administrators	AppD-AppRole-Administrators	AppD-Role-Administrators
Agent Brown	AppD-SecGroup-PowerUsers	AppD-AppRole-PowerUsers	AppD-Role-PowerUsers
Agent Jones	AppD-SecGroup-ReadOnly	AppD-AppRole-ReadOnly	AppD-Role-ReadOnly
Agent Colson	AppD-SecGroup-AllGroups	AppD-AppRole-All	AppD-Role-Administrators, AppD-Role-PowerUsers, AppD-Role-ReadOnly

The table above is reflected in the following screenshots:  

Agent Smith: AdministratorsAgent Brown: Power Users

Agent Jones: Read Only

Agent Colson: All Groups

Reference Links

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/

[Mahesh.Ravji]

The instructions in this article Step 7 (https://community.appdynamics.com/t5/Knowledge-Base/How-do-I-configure-SAML-for-Azure-Active-Directo...) state 'Sign on URL = https://<YOURTENANT>.saas.appdynamics.com', however the AppDynamics documentation (https://docs.appdynamics.com/display/PRO45/Configure+Basic+SAML+Authentication) states 'Single Sign-On URL = http://<controller_domain>/controller/saml-auth?accountName=<account_name>'.

Does it matter which syntax is used? Maybe worthwhile syncing up the two articles?

[Claudia.Landivar]

Good eye, @Mahesh.Ravji : thank you! I've edited the line so it reads "Single Sign-on..."

With regard to the rest of the line, the account name parameter is optional, so there's not a functional difference. In this case, we were using that syntax represent the url parts with a different (hopefully helpful) perspective.

[Ben.Snowden]

I cannot get idp initiated sso to work from Azure AD. I just end up at the normal controller login screen in which I have to enter the account. Then once the account is entered, sp initiated sso to AAD works fine. Any ideas? I have gotten idp initiated sso to AppD to work with other providers.

[Ben.Snowden]

OK I figured it out. The gallery app does not allow idp initiated sso because it requires a sign on url. I created a custom app with just the Entity ID and Reply URL and then both idp and sp initiated sso worked.

[Primoz.Rajbar]

Regarding Step 5 (Create Roles for AppDynamics Enterprise Application), where it says: [...] Azure management UI does not provide ability to create those roles. 

App roles in Azure can now be added through the UI:
https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps

[Claudia.Landivar]

Thanks for the update, @Primoz.Rajbar  — I'll queue the article up for revision.

[Silvia.Moreno]

Hi @Claudia.Landivar another customer raised that this is not updated, could you please revise the article?

Thank you

Silvia

[Claudia.Landivar]

@Silvia.Moreno — reaching out to you directly to connect on revision status.