How to Integrate CPM with ADFS to allow Idp logins from windows AD users

How to Integrate CPM with ADFS to allow Idp logins from windows AD users

Background:

This How-To guide will outline how to configure CPM and a windows ADFS server to allow IdP logins. Before you get started you will need to check the prerequisites. This is very important. If they are not met or the Domain and any of the roles are incorrectly configured, this process will fail.

Prerequisites: You must have a fully configured and functional domain (Active directory services) and the following roles DNS, IIS, ADFS, and Certificate Authority fully operational before proceeding. You will also need to have your public SSL or a self-signed SSL. If you do not already have one you will need to stop and obtain one before proceeding.  Ensure that DNS is functioning properly and that the domain controller and all other servers that hold AD roles are reachable by their IP addresses and hostnames from the CPM instance to avoid name resolution issues later.

It is also important as you complete the configuration steps that you use either the IP addresses of the Windows server(s) and the N2WS server OR the host names in all address fields required. Do not use a mix of the two in any configuration fields on either the IdP or the N2WS side. This will cause errors and the IdP login will fail.

Please check the following link if to see if ldP integration is supported on your edition of CPM -  Edition Features
For additional information about IdP integration, read our user guide: CPM User guide - IDP Configuration

This document is separated into three sections

ADFS Configuration

CPM Configuration

Troubleshooting
 

ADFS Configuration

Download the CPM Certificate
First, you will need to have the SSL Certificate you will be using, make sure it is available. Also, you will need to go download the N2WS x509 certificate. See steps below to obtain this.
1. Login to N2WS and go to General Settings.



2. Select Identity Provider on the left and select Settings to see the options for IDP. If this is your first time in this section you may see the warning that IDP has been disabled, Click Settings.



3. Check the box to enable Identity Provider and the following options will show up. 



4. Click Download CPM's Certificate – and save a copy of it. You will use this on the IDP side. You can leave the page without saving your settings for now.

For N2WS to work with ADFS, the X.509 certificate used by N2WS needs to be added to the ADFS Trusted Root Certification Authorities list. If you installed your own certificate when you first configured N2WS (using the instructions in the N2WS user guide) then your certificate may already be in your ADFS root trust. Otherwise, you will need to add it. If you used the certificate N2WS creates during installation (the one you can download using the steps above), you will need to add that certificate into the ADFS Trusted Root Certification Authorities. Steps are provided later in this document. 

Create a Relying Party Trust within ADFS management.
 
1. Open ADFS management.  In the left pane of the ADFS console, click Relying Party Trusts.
Right click on the Relying Trust Party folder on the left and choose Add Relying Party Trust, or in the right pane, click Add Relying Party Trust.



2. You will be asked if you want “claims aware” choose claims aware, then click Start.


 
3. Choose “Enter data about the relying party manually”  and click Next.



4. On the Welcome screen, type the display name for N2WS (e.g. N2WS Backups, and click Next.


 
5. You will be asked for a display name.


 
6. In the Configure Certificate screen click Next to skip this section.

 

7. On the Configure URL screen , Select the Enable support for SAML 2.0 WebSSO protocol check box.  In the Relying Party SAML 2.0 SSO Service URL box, type https:// followed by the CPM DNS name or IP address, and then followed by /remote_auth/complete_login
For example, the resulting string might look like:
Click Next.



8. In the Configure Identifiers screen, type https:// followed by the CPM DNS name or IP address, and then followed by “/remote_auth/metadata” in the Relying party trust identifier box. For example, the resulting string might look like:
Click Add on the right then click Next.



9. On the Issuance Authorization Rules / Access control screen, click the Permit all users/ Permit everyone to access this relying party option, and click Next.

 

10. On the Ready to Add Trust screen, review the setting of the Relying party trust configured with the Wizard. When finished, click Next.


 
11. On the Finish/summary screen of the Wizard, click Next. Do not check the “Open the Edit Claim Rules dialogue for this relying party trust” option if it is presented then click Close



Now you will need to set the ADFS properties using the steps below


ADFS properties
 
To set the ADFS properties:
 
1. Go back to the ADFS management console, and in the middle pane, right-click the CPM trust under Relying Party Trust, and select Properties or choose the option “Properties” on the right.


 
2. On the screen that opens, select the Endpoints tab, and click Add SAML.



 
3. In the Edit Endpoint screen, select SAML Logout from the Endpoint type list. Choose POST for the Binding field.
 In the Trusted URL: box, type the DNS name or IP address of the ADFS server followed by:
/adfs/ls/?wa=wsignout1.0

4. In the Response URL: box, type DNS name or IP address of the CPM server followed by:
/remote_auth/complete_logout



5. Click OK at the bottom, then in the same window, Click Apply and go to the Advanced tab, and in the Secure hash algorithm list, select SHA-256. Click Apply.  Click OK to close the window.
 

 
Add a root certificate to the ADFS Trusted Root Certification Authorities

1. In the ADFS management console, choose Relying Party Trusts, right click on the Trust you just created and click properties.




2. Go to the Signature tab under properties and click Add. Then locate and choose the CPM x.509 certificate we downloaded at the beginning of this document. OR if you had created your own SSL certificate for the CPM server, you can upload that now. 



 3. Once you add the certificate The CPM certificate is now visible in the center pane in the Signature tab, you can see it in the image above. In the center pane of the Signature tab, double-click the CPM certificate. The certificate will open. Click Install Certificate.

 
 
4. In the Certificate Import Wizard screen, click Local Machine, and click Next. Choose Place all certificates in the following store option, click Browse…, and then select the Trusted Root Certification Authorities store. Click OK.

5. Click the Place all certificates in the following store option, click Browse…, and then select the Trusted Root Certification Authorities store. Click OK. then click Next.


 
6. On the Completing the Certificate Import Wizard,  Click Finish. Then click OK on the Successfull message, click OK on the General tab, and click OK on the Properties screen to close the window.




Creating an ADFS Name ID Claim

1. Open the ADFS management console. In the main page of the management console, select Relying Party Trusts in the left pane. In the middle Relying Party Trust pane, select CPM’s party (e.g. CPM by N2WS). In the right pane, click Edit Claim Rules/Edit Claims Issuance Policy.


 
2. In the Edit Claim Rules/Edit Claims Issuance Policy screen, click Add Rule.
 

   
 
5. In the Claim rule template list, select Transform an Incoming Claim and click Next.


 
Complete the Add Transform Claim Rule Wizard screen:
6. In the Claim rule name box, type a name for the claim. "nameid"
7. In the Incoming claim type list, select Windows account name.
8. In the Outgoing claim type list, select Name ID.
9. In the Outgoing name ID format list, select Unspecified.
10. Click the Pass through all claim values option.
11. Click Finish.


 
Adding a Token-Groups Claim

An ADFS Token-Groups claim must be configured so that ADFS will send CPM the list of groups a user is a member of. To configure the Token Groups claim click Add rule again at the bottom and continue with the steps below.


1. In the Claim rule template list, select Send LDAP Attributes as Claims and click Next.



2. In the Claim rule name box, type a name for the rule you are creating. "user claims"
3. In the Attribute store list, select Active Directory.
4. In the Mapping of LDAP attributes to outgoing claim types table:
 In the left column (LDAP Attribute), select Token-Groups – Unqualified Names.
 In the right column (Outgoing Claim Type), type “cpm_user_groups”.
Click Finish to create the rule

 

Configuring an ADFS User Claim

Once a user attribute has been configured with the correct permissions, an ADFS claim rule with Outgoing Claim Type “cpm_user_permissions” must be created before the user-level permissions can take effect. 
To create the claim rule:
1. Open the ADFS management console.
2. In the main page of the management console, in the left pane, select Relying Party Trusts.
3. Select CPM’s party (e.g. CPM by N2WS) in the middle pane, and in the right pane, click Edit Claim Rules/Edit Claim Issuance Policy, or right click and choose Edit Claim Rules/Edit Claim Issuance Policy.



4. In the Edit Claim Rules screen, click Add Rule again. 



5.In the Add Transform Claim Rule Wizard screen, select Send LDAP Attributes as Claims in the Claim rule template list, and click Next.


6. The Claim Rule Wizard opens the Edit Rule screen. Complete as follows:
7. In the Claim rule name box, type a name for the rule you are creating. "user permissions"
8. In the Attribute store list, select Active Directory.
9. In the Mapping of LDAP attributes to outgoing claim types table:
In the left column (LDAP Attribute), type the name of the user attribute containing the user permissions “msDS-cloudExtensionAttribute1”.
In the right column (Outgoing Claim Type), type “cpm_user_permissions”.
Click Apply, then click Ok to create the rule



Once the user-level claim is enabled, the user will be able to log on to CPM with permissions that are different from the group’s permissions.

CPM Configuration

Configuring CPM to Work with Active Directory / ADFS
To configure CPM to work with the organization’s AD server:
1. Go to the CPM General Settings page.
2. Select the Identity Provider Configuration.
3. In the Identity Provider list, select Enabled. Several IDP related parameters are presented.


4. In the Entity ID box, type the ADFS Federation Service Identifier, as configured in ADFS. Open ADFS management and go to Edit Federation Service Properties to obtain this address. NOTE: you may have to change the Federation Service Properties to reflect your public AWS DNS names to allow the server to be publicly available for IDP login – if this server is not otherwise made publicly available.


 
5. In the Sign in URL box, type the URL to which CPM will redirect users to enter their AD credentials.
This parameter is configured as part of ADFS. The ADFS server’s DNS name, or IP address, must be prepended to the URL Path listed in ADFS.  Using the example below our Sign In URL would be:



6. For the Sign out URL in CPM: enter the same address as you entered for the sign in URL above. i.e. https://ec2-12.123.345.678.us-east-2.compute.amazonaws.com/adfs/ls
7. For the NameID format choose Unspecified.       
8. In the x509 cert box, upload the X509 certificate of the ADFS server. The certificate file can be retrieved from the ADFS management console under Service -> Certificates. See below.

To export the certificate: Open ADFS management console.
Double click the Token signing field to open the Certificate screen.



Click the Details tab and click Copy to File . . . on the bottom right.



Click Next to continue with the Certificate Export Wizard.



Click the Base-64 Encoded X.509 (.cer) option and click Next.



Type a name for the exported file and click Next.



Click Finish.

9. Back in the CPM IDP configuration, Click the Choose File button next to x509 cert: choose the certificate you just downloaded.



10. Once it has been uploaded, click Save in the bottom right.



At this point, ADFS has been configured to work with CPM. It is now possible to perform a connectivity test between CPM and ADFS. 
Click the "Test Connection button"

You should see a success message similar the one below depending on how you customized your ADFS settings. The example below is default. You likely cannot login yet if you have not configured groups on each side, but the below shows the connection from CPM to the ADFS server is successful.




CPM User Groups and User Claims

Next, you will need to create the CPM user group and a CPM user group on the AD side.
Important notes about groups: You can use a group name with or without a prefix of "cpm_". for our example here i have used the "cpm_" prefix that was required in previous versions of CPM.  If you choose to create a group with the "cpm_ " prefix on the AD side, The group you create within CPM (for AD users) cannot have the "cpm_" prefix added to it. For example, if you use a group name on the AD side named "cpm_users" then you will create a group on the cpm side named only "users".  
Group names on the AD/IdP side no longer need the "cpm_" prefix. This means that if you decide to use a custom group name in AD without the "cpm_"  prefix, you can name your group in CPM and AD  exactly the same. For example, if your group name in AD is "custom group" then the group name you create in CPM would be "custom group". Spaces and special characters are also allowed to be used in group names. 

In the example here we are creating a group named "Users" The effect  being that adding users to the group “cpm_users” on the AD side will sync these two groups together. The reason this is needed for this particular group name is due to AD already having a default group named "Users" so we must differentiate between them. CPM will recognize the "cpm_" prefix on the AD group name and it will use this group. If you are using another group name, anything other than "Users" on the cpm side, then this is not needed. For example if you create a group on the CPM side named "custom_group" then you would also create a group on the AD side named "custom_group".

You also have the option of using "default_root_delegates”,  (create the corresponding group named: "cpm_default_root_delegates" in the AD and add users to that IDP group).
This is usually done to make the IDP user able to see the root/admin user accounts and Policies in CPM.
 
Note: Do not add IDP/AD users to more than one cpm group as it can cause this process to fail. You will need to choose one CPM group for each IDP user in AD – they cannot be a part of “cpm_users” and “cpm_default_root_delegates” at the same time. Any user in the AD who is part of the “cpm_users” group will have access to login to CPM using IDP credentials.
For more details on adding groups to the Cloud Protection Manager see the CPM User Guide.
 
1. Login to CPM , go to General Settings and then Identity Provider on the left, and choose groups. Click the + New link

 
 
Name the group “users”, or whatever you named the group in AD and then set your desired options.
Note: The other values can be set to values that meet your deployment situation. If you leave the fields blank, your user will have unrestricted access in those areas.


Once you are happy with the options, click Save at the bottom right. This will save the group. Then you should see your new group listed.


 
Now you can test the IDP login from a web browser. To do this open a web browser and enter the https://<CPM SERVER ADDRESS> and click the Identity Provider Button.
You will have the same login prompt that you saw when you tested the connection. see below.



This shows my IDP user logged into CPM.



If you see any errors please first refer to the troubleshooting list below.


Troubleshooting


Here are some common errors encountered when configuring IDP with ADFS. Please click the corresponding link for a full description of the error and instructions on how to correct it.

CPM IDP configuration may fail if CPM is configured with custom DNS

Login to the CPM using an IDP may fail with the "Invalid issuer" error message

IDP/SAML integration may fail with "Failed to get CPM public hostname"

Failed to open IDP login page or to test the connection with the errors: "HTTP Error 503. The service is unavailable." or "404 - File or directory not found."

SAML Identity Provider user login issues

CPM server may display error "Signature validation failed. SAML Response rejected"

CPM Server may display error "Problem Occurred (500)" during the Identity Provider configuration

Cannot open ADFS login page while testing connection or trying to log in with an error "err_connection_reset"

Logging into CPM using Identity Provider may fail with an error "An error occurred"

Failed to login to ADFS with the error: "The status code of the Response was not Success, was Requester -> urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy (invalid_response)"

Login failure with the reason: https://%cpm servername%/remote_auth/metadata is not a valid audience for this Response (invalid_response) ​
 
NOTE:
If you cannot locate your issue in the above links OR the steps in the above links do not correct the issue, please collect the logs outlined in the link below and contact support.