Knowledge Base

cancel
Showing results for 
Search instead for 
Did you mean: 

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

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

Picture1.png

 

 

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

 

Picture2.png

 

 

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

 

 

2 agent AppD SecGrp Admins@3x.png

 

5 agent AppD SecGrp AllGrps@3x.png

 

2 agent AppD SecGrp PowerUsrs@3x.png

 

2 agent AppD SecGrp ReadOnly@3x.png

 

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

 

Picture8.png

 

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.

8 modify permissions.png

 

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

9 graph explorer.png

 

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

10 Azure AD props AppD object id.pngSelect the the newly created AppDynamics Enterprise Application's Object ID from the Properties tab

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

 

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

11 obj id EntApp@3x.png

 

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

 

12 run get qry@3x.png

 

 

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

 

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

 

  1. 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"
    }
    ]
}

 

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

 

13 execute patch@3x.png

 

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

 

14 AD groups a@3x.png15 AD groups add assignmt@3x.png

 

 

The final result should reflect this:

16 AD groups add assignmt b@3x.png

 

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

 

17 edit uer attribute@3x.png

 

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:

 

18 sso certificate@3x.png

 

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:

 

19 config sign on@3x.png

 

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

20 edit group mapping.pngMapping the Azure AD Enterprise Application role "AppD-AppRole-PowerUsers" to AppDynamics' "AppD-Role-Power-Users"

Click Save.

The final configuration may look like this:

21 authentication pro SAML .pngSAML 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.

22 AppD login.png

 

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.

23 ms signin.png

 

User specifies the password and clicks “Sign in”.

24 ms signin b.png

 

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:

25 send to appd controller in SAML token.pngAzure 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>

26 grp membership roles assigned to id.png

 

 

27 appd controller with role permissions.png

 

 

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:  

28 roles agent smith@3x.pngAgent Smith: Administrators29 roles agent brown.pngAgent Brown: Power Users

30 roles agent jones.pngAgent Jones: Read Only

31 roles agent colson.pngAgent 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/