About SAML Authentication
The Controller supports single sign-on through its SAML integration. With SAML enabled, the AppDynamics Controller delegates authentication to the Controller UI to an external SSO identity provider.
The AppDynamics SAML integration conforms to the Security Assertion Markup Language 2.0 (SAML 2.0) specification, so any SAML 2.0-compliant identity provider can be used with AppDynamics.
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 your x.509 certificate supplied by your identity provider.
If OneLogin is your identity provider, use the widget described in SAML Configuration for OneLogin to configure OneLogin for AppDynamics. For other SAML identity providers, you need to provide the following SAML authentication assertion custom attributes to be sent by the identity provider:
- accountName – required only if the controller is multi-tenant
- emailAddress – the user's email address.
- New in 3.8.1 Groups – required if mapping SAML groups to Controller roles.
- 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.
The specific configuration steps applicable for your environment depend on your SAML identity provider. See SAML Configuration for OneLogin for an example of AppDynamics' integration with One Login.
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 SAML Configuration for OneLogin for sample steps that show how to configure SAML with an actual identity provider.
To Configure a SAML Identity Provider
- As an administrator or account owner in the Controller UI, click Settings -> Administration.
- Click the Authentication Provider tab.
- Select the SAML radio button for the authentication provider to use.
The SAML configuration screen appears:
- In the Login URL field, enter the SAML Login URL. The SAML Login URL is the URL to the SSO service at the identify provider. The identity provider provides this URL to the Controller.
- 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.
- 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.
- 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.
- Click Save.
Use Automated SAML Groups and Controller User Role Associations
New in 3.8.1 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.
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.