How To Integrate Okta SSO IdP with CPM 3.0 and above

How To Integrate Okta SSO IdP with CPM 3.0 and above



Background:

This document details the steps needed to configure Okta Single Sign On IdP and N2WS Cloud Protection Manager 3.0+. This KB will walk through configuring a new application in Okta to use with CPM as well as configuring CPM with Okta's information. Please note that integration with CPM and Okta is supported only for Advanced, Enterprise, and custom versions of CPM.


This KB is has 2 sections that must be complete in order for CPM to allow Okta IDP logins, in addition we have included a troubleshooting section.
  1. Okta Configuration
  2. CPM Configuration
  3. Troubleshooting

Okta Configuration

1.  Login to your Okta Admin Dashboard. To do this, login to the Okta website then click the arrow next to your name and choose "Your Org" (login if prompted) then click the Admin Button. In the Admin Dashboard  click "Directory" and then choose "Groups", See below for quick steps. 







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 label your Okta group with the "cpm_ " prefix, The group you create within CPM (for okta users) cannot have the "cpm_" prefix added to it. For example, if you use a group name on the Okta side named "cpm_users" then you will create a group on the cpm side named only "users".  
Group names on the Okta/IdP side no longer need the "cpm_" prefix. This means that if you decide to use a custom group name in Okta without the "cpm_"  prefix, you can name your group in CPM and Okta exactly the same. For example, if your group name in Okta 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. 

2. We will now create a user group in Okta for CPM. After clicking on  "Directory" and then "groups" from step 1, you will land in the Okta Group Creation screen, name your group the same as the group name you want to use from your CPM IDP groups. If you have not created the group in CPM yet and do not want to use one of the default ones that cpm has already created such as "default_root_delegates" then you can go create the group in CPM later,  for now pick a name for the group and create it in Okta. Later when we configure CPM you can create the corresponding group name and choose permissions.



4.  Click the newly created group name to add Okta users to the cpm group.



5.  Click "Manage People"



6.  Click on the users on the left side that you want to add to the new cpm_users group.




7.  The users on the left side will move to the "Members" list on the right side when you click on them. When you are finished, click Save.



8.  After you save the changes you will see your new group and a list of the users you just added to it. We will come back here later to assign the application to this user group, once its created in Okta.



9.  For the next steps, you need the CPM certificate so you can upload it to Okta. Login to your CPM we portal and go to "Identity Provider", check the "Identity Provider" box to enable the settings, then click "Download CPM's Certificate" to download and save the certificate locally. If you download the file and it has a .txt appended to it, simple remove it so it has only the .crt extension.  Then you can leave CPM open until we come back to configure it, or logout for now without saving changes.




10.  Back in your Okta Admin Dashboard, click "Add Application".



11.  Choose "Create New App" in the top left



12.  Choose "Web" for your platform and SAML 2.0 for the sign on method.



13.  Name the application, upload a logo if you want to and click Next.



14.  Next we come to the SAML Settings. Click "Show Advanced Settings"



15.  Complete the General and Advanced General Settings as follows.
Single Sign on URL  -  https://<CPM_Address>/remote_auth/complete_login/
 - check the box "Use this for Recipient URL and Destination URL"
Audience URI (SP Entity ID)  -  https://<CPM_Address>/remote_auth/metadata/
Name ID format  -  Unspecified
Signature Algorithm  -  RSA-SHA256
Digest Algorithm  -  SHA256
Enable Single Logout  -  Check the box "Allow application to initiate Single Logout"
Single Logout URL  -  https://<CPM_Address>/remote_auth/complete_logout/
Signature Certificate  -  Browse to the CPM certificate you downloaded from the CPM server and then click "Upload Certificate" and wait for the field to populate.
Authentication Context Class  -  PasswordProtectedTransport



16.  Scroll down to the attributes statements. Enter the following for the Group Attribute Statement. this is case sensitive so do not include the quotes and keep it all lower case.
Name  -  "cpm_user_groups"
Name Format  - Unspecified
Filter  - Starts with cpm_
Okta will send an attribute/claim called "cpm_user_groups" which will contain a group name that starts with "cpm_" , CPM will then search for this specific attribute (case sensitive), check its value and can then locate the group the user belongs to in Okta.



If you used a group name without the "cpm_" prefix, then you will fill out the attributes like below, this is case sensitive so do not include the quotes and keep it all lower case.
Name  -  "cpm_user_groups"
Name Format  - Unspecified
Filter  - Equals "your group name"



17.  Complete the feedback section for Okta and then click Finish.



18.  After clicking Finish, you will be taken to the Sign on Settings tab, click the "View Setup Instructions".




19.  A new Tab will open with the details below, you will need to copy the following information to enter into CPM (in the following steps)  and download the Certificate now, or leave this tab open until you configure CPM so you can copy the URL's into CPM.





20.  Go Back to your user groups in Okta and open the user group you created for CPM and click the Manage Apps button and assign the Application to this group. Any user who is part of this group in Okta will have access to CPM.




CPM Configuration

In this Section we will go through the Steps needed to configure CPM to allow Okta IDP users to login to CPM.

1.  Login to CPM as the root user and go to General Settings.



2.  Then choose Identity Provider and then  "Groups". Click + New to create the group name that you will use with Okta. In our example here we are created a group named "users" and made it an Independent user account.



3.  Now Click the "Settings" tab next to groups. Check the Box to enable the Identity Provider options and then complete the fields using the Okta SAML 2.0 settings you copied earlier in step 18 of the Okta configuration steps, or if you still have it available in an open tab, you can copy the details from there.
CPM Entity ID - Okta Identity Provider Issuer
CPM Sign In URL - Okta  Identity Provider Single Sign-On URL
CPM Sign Out URL - Okta  Identity Provider Single Logout URL
CPM NameID Format - Unspecified
x509 Certificate - Upload Okta certificate that you downloaded in step 19 of the Okta configuration.



4.  Click Save in the bottom right, and then Test the connection.



You should see the following successful message



5.  Now go back to your Okta dashboard and click on "My apps" then launch the app from Okta.





6.  You will be logged into CPM as the Okta user, you can check this in the top right corner of CPM.



7.   In the users section you can see that the user was created automatically by CPM when your Okta user logged in for the first time.



You have now successfully configured CPM to allow IDP logins from Okta.

Troubleshooting

Here are some common IdP errors and resolutions. 
  1. Common IdP login issues
  2. 503 The service is unavailable / 404 File or directory not found
  3. Invalid issuer in the Assertion/Response (invalid_response)
  4. A Problem Occurred (500) when configuring the IdP settings in CPM
  5. Login Failure: Not a valid audience for this response/Invalid response errors
If the above does not correct the error please open a support issue and also include the CPM logs by using the steps in this link: Gather CPM logs for support

In Addition to save time when you open a Support ticket please gather these additional items:
1. Please send a copy of the error, with a description of when you receive it.
2. Copy of the error or results when you hit the Test Connection button in CPM, in the Identity Provider configuration section.
3. Please provide screenshots of the Identity Provider settings and CPM IdP settings.

Thanks for reading this guide,
N2WS Support Team.