Integrating Azure AD with the Contrast UI for SAML Authentication
Within Contrast UI
- Open up the user menu in the top left and select Organizational Settings and proceed to Single Sign-On.
- Select Get Started (this will not change your authentication method until fully saved).
- Select Copy Metadata URL and paste this into a new browser tab to download the
spring_saml_metadata.xml
file which will be imported in the following steps within Azure.
Within portal.azure.com
- Navigate to Home > Default Directory | Enterprise applications > Enterprise applications
- Select + New application
- Search for "Contrast" and select the Contrast Security tile and "Create".
- Select Get started for 2. Setup single sign on and select the SAML tile.
- Select Upload metadata file at the top of the SAML-based Sign-on page and choose the spring_saml_metadata.xml file that was saved earlier.
- Click "Save" in the Basic SAML Configuration screen after importing.
- On the Contrast Security | SAML-based Sign-on page:
- Select Edit for the Attributes & Claims pane
- Select Unique User Identifier (Name ID). Ensure the Source Attribute value maps to the users' e-mail address.
- On the Contrast Security | Users and groups page:
- Use the + Add user/group to assign users to the enterprise application
- Under SAML Certificates copy the App Federation Metadata Url.
Back to the Contrast UI's Single Sign-On page:
- Fill in the Identity Provider field: This is a name of your choosing and has no bearing on the SAML configuration.
- In the idP Metadata URL: Paste the copied value from Azure's App Federation Metadata Url
- Default Organization Role: This is the role new users will be assigned when utilizing provisioning.
-
Default Application Access Group: This is the level of access to onboarded applications a newly provisioned user will have.
- Enable user provisioning: Automatically creates new users in your organization when your idP approves login requests
- Selecting this will add a new Accepted Domain(s) field above. This is required and any email domains for your organization should be added. Example: acme.com, acme-org.com
- Add users to their Contrast groups upon SSO login: This allows you to map groups from AD with groups in Contrast's UI for application level access. Steps to configure this will be covered later (information in our docs here).
- Remove users from their Contrast groups upon SSO login: This will remove users from any groups not present in their SAML assertion, so if you make manual changes to users by adding them to new groups, they will be removed if the group is also not present in their assertion.
- Select Save
Do not log out of your current session until the login testing is complete in the next section.
Login Testing:
If you are configuring this for one of Contrast Security's SaaS orgs you will want to wait about 10-15 minutes after the last step before proceeding. It generally takes about this long for the authentication changes to propagate to all of our Contrast UI application nodes.
- Open a new Incognito browser window or utilize a different browser than you are otherwise using for your current session in the above steps (we want to avoid the cached tokens).
- Proceed to the Contrast UI's base DNS address. Example: https://app.contrastsecurity.com
- Login as your e-mail address associated with a user configured for access to the enterprise application within Azure.
- Make sure the login works correctly and you are forwarded over to Azure for authentication and then back to the Contrast UI successfully.
See this KB if you run into 405/500s or any other type of failure. You may need to revert the SSO authentication to avoid locking users out of the application while working on this.
Enabling Contrast Group provisioning for users:
Within portal.azure.com
- Navigate to Home > Default Directory | Enterprise applications > Enterprise applications > Contrast Security > SAML-based Sign-on
- Edit the Attributes & Claims pane
- Select Add a group claim and set the following.
- Select Groups assigned to the application
- Source attribute = Cloud-only group display names (preview)
-
Advanced options > Customize the name of the group claim
- Name (required) = contrast_groups
- Save the settings
Examples:
Note: If your groups are not cloud-only, select a Source attribute of sAMAccountName
instead.
For the group mappings
- Within Azure: Under the Users and groups section of the Contrast Security enterprise application.
- Note the exact names of the groups that show up here or add any that should
- Within Contrast UI: Organization Settings > Groups
- You will want to create a new group name via + Add Group for every group you have listed under Users and Groups in Azure.
- Set the appropriate access to applications you'd like to control with this group.
- Ensure Add users to their Contrast groups upon SSO login is selected under the Single Sign-On settings.
- Once complete, new users provisioned into the system will be assigned to the group configured in the mapping. This topic in our docs covers more information around that behavior.