This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


Skip to end of metadata
Go to start of metadata

On this page:

You can configure the Controller to use SAML as an external authentication provider for the Controller UI. The Controller's SAML support allows you to include Controller UI access control into your organization's existing single sign-on systems.  

Before Starting

To configure SAML-based single sign-on for the Controller, you must have:

  • An account with a supported identity provider. You need your SAML Login URL and the x.509 certificate supplied by your identity provider. The Controller performs Service Provider (SP)-initiated logins using the SAML identity provider login URL you specify. 
  • An account and access to an AppDynamics SaaS or on-premise Controller. The client browser must have access to both the Controller and the identity provider service.
  • Account Administrator privileges on the AppDynamics Controller, as described in Administrative Users.
    Before configuring the SAML settings in the AppDynamics Controller, verify that the Account Administrator user who will log into the Controller and set up the SAML authentication also exists as a user in the identity provider. After configuring the SAML settings in AppDynamics and logging out, this user will be forced to log in again as that Account Administrator this time using the identity provider for authentication.

SAML Response Requirements

The Controller expects the following custom attributes in the SAML assertion sent by the identity provider:

  • NameID  – SAML Response should identify the user who is logging in. This value must be unique among all users in the Controller account, so typically this value will be the unique username for the user. The Controller uses the SAML authentication assertion NameID value as the user name for the user account in the Controller UI. 
    If this field is not specified in the response or for any reason you do not want to map this field to the username in the Controller user account, you can use the custom userName SAML attribute to specify the value to use for the username for the Controller user. 
  • emailAddress – The user's email address.
  • Groups – This is required if you want to map SAML groups to Controller roles.
  • Assertion Consumer (ACS) URL – The assertion consumer value should be http[s]://{appdynamics_controller_url}/controller/saml-auth

  • Relay State – For the relay state parameter, the provider should use http[s]://{appdynamics_controller_url}/controller

  • entityid (PingIdentity) – For the entity ID  parameter, the provider should use http[s]://{appdynamics_controller_url}/controller

  • accountName – If the Controller is multi-tenant mode, the SAML response must contain a custom SAML attribute named accountName that indicates the account to which the user is attempting to authenticate. 

Note that the display name for a user is constructed by combining the firstName and lastName attributes from the SAML response, if present. If the attributes are not present, the Controller uses the userName value as the display name for the user.

The Controller does not expect the SAML response to be encrypted, but it should be signed and is typically BASE-64 encoded.

The OneLogin widget described in Configure SAML for OneLogin provides mappings for the required parameters. For other SAML providers, you need to ensure that the values are returned directly. 

Sample Request and Response

Here is a sample request from the Controller to the SAML service provider:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
          ID="_161f8cdf-3c27-4a60-9158-b7be76ba2090"
          Version="2.0"
          IssueInstant="2014-07-08T18:58:09.42Z"
          ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
          AssertionConsumerServiceURL="http://{appdynamics_controller_url}/controller/saml-auth?accountName={account_name}”
       >
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://{appdynamics_controller_url}/controller</saml:Issuer>
    <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
          AllowCreate="true"
       />
</samlp:AuthnRequest>

 

Here is a sample response from the SAML service provider:

<samlp:Response xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
          xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
          ID="Rb178cb4b8e8b9bcdc2634b4a50a16031f26f56d61"
          Version="2.0"
          IssueInstant="2014-07-08T19:01:36Z"
          Destination=""
          InResponseTo="_161f8cdf-3c27-4a60-9158fdfd-b7be76ba2090"
        >
    <saml:Issuer>https://{saml_provider_url}</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>
    <saml:Assertion xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           Version="2.0"
           ID="pfxef90db96-f96f-5187-b381-4dd890e07105"
           IssueInstant="2014-07-08T19:01:36Z"
           >
        <saml:Issuer>https://{saml_provider_url}</saml:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
                <ds:Reference URI="#pfxef90db96-f96f-5187-b381-4dd890e07105">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                    <ds:DigestValue>QaG4sf2JpLvlynfsyVkU9OyaK92FmFo=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>{Signature}</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>{Cert}</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress”>{username}</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData NotOnOrAfter="2014-07-08T19:04:36Z"
                                   Recipient=""
                                   InResponseTo="_161f8cdf-3c27-4a60-9158-b7be76ba2090"
                                   />
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2014-07-08T18:58:36Z"
                         NotOnOrAfter="2014-07-08T19:04:36Z"
                         >
            <saml:AudienceRestriction>
                <saml:Audience/>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2014-07-08T19:01:35Z"
                         SessionNotOnOrAfter="2014-07-09T19:01:36Z"
                         SessionIndex="_350bd2d0-e900-0131-e7a8-782bcb56fcaa"
                         >
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute Name="Groups"
                         NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                         >
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:type="xs:string"
                         >{group1}</saml:AttributeValue>
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:type="xs:string"
                         >{group2}</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="accountName"
                         NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                         >
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:type="xs:string"
                         >{account_name}</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="emailAddress"
                         NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                         >
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:type="xs:string"
                         >{user@domain.com}</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

 

Configure SAML Settings

You configure a SAML identity provider for the Controller from the authentication provider tab in the Controller UI. 

This page contains general steps for setting up SAML integration. See Configure SAML for OneLogin for sample steps that show how to configure SAML with an actual identity provider.

To configure a SAML Identity Provider
  1. As an administrator or account owner in the Controller UI, click Settings -> Administration.
  2. Click the Authentication Provider tab.
  3. Select the SAML radio button for the authentication provider to use.
    The SAML configuration screen appears: 
  4. In the Login URL field, enter the SAML Login URL. This is the address to which the Controller will send Service Provider (SP)-initiated login requests. 
  5. In the Logout URL field, enter the URL to which the browser should redirect when the user logs out. This is useful for redirecting the user back to the identity provider instead of to the AppDynamics login screen. This field is optional.
  6. In the Certificate field, paste the x.509 certificate from your identity provider configuration between the BEGIN CERTIFICATE and END CERTIFICATE delimiters. Do not copy the BEGIN CERTIFICATE and END CERTIFICATE from certificate field.
  7. In the Default Roles section, select the roles to grant to new users of the SAML-enabled controller by checking the Member check box for the role.  You must grant at least one default role, and you can select multiple roles. See Configure Roles for information about roles and permissions.
    The roles that you assign here will be granted to new users when they first log in to the SAML-enabled controller if those users have not been previously created directly in the Controller. Users created prior to SAML enablement or directly within the controller prior to the user's initial login retain their original roles.
    Typically SAML users get the default roles assigned in this configuration. In exceptional cases an account owner may want to grant individual users different roles. See To Assign A Role to a User.
  8. Click Save.

Use Automated SAML Groups and Controller User Role Associations

The Controller can assign roles to SAML-authenticated from attributes drawn from the SAML identity assertion for the user. The Controller takes the group name from the user identity assertion from SAML and matches it to the role with the same name defined in the Controller configuration.

To use automated mapping between SAML group and Controller role:

  • The SAML identity response from the authentication provider must return the group associations for authenticated users.
  • The group names must be in an attribute named "Groups".  
  • The group name as presented by the SAML system and the role name in the Controller must be identical.

As an example, given the following SAML assertion, the Controller would map the "Workflow Executor" and "CartAppAdmin" group names to the identically named roles in the Controller. 

<saml:AttributeStatement>
   <saml:Attribute Name="Groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml:AttributeValue xsi:type="xs:string">Workflow Executor</saml:AttributeValue>
      <saml:AttributeValue xsi:type="xs:string">CartAppAdmin</saml:AttributeValue>
   </saml:Attribute>
</saml:AttributeStatement>

No additional SAML configuration is required in the Controller to use SAML group-to-role mapping. If SAML authentication is enabled in the Controller, as described in the previous section, it automatically checks SAML assertions for the Groups attribute. 

However, be sure to note the following behavior related to SAML group-to-role mapping:   

  • If the SAML system returns the Groups attribute, but the values of the attribute cannot be matched to any role in the Controller, the user authentication succeeds (the user logs in) but will not have any privileges in the Controller UI. 
  • If the SAML assertion does not include the Groups attribute, the Controller assigns the default roles you configure for authentication, as described in the previous section.    
  • If the SAML assertion identifies multiple groups that map to roles in the Controller, the privileges defined by all matching roles are aggregated for the user. 
  • No labels