How To Integrate Okta SSO with N2W

Summary

This document details the steps needed to configure Okta Single Sign On IdP and N2W.

Description

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 N2W.  If you choose to label your Okta group with the "cpm_ " prefix, The group you create within N2W (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 N2W 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 N2W and Okta exactly the same. For example, if your group name in Okta is "custom group" then the group name you created in N2W 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 N2W. 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 N2W IDP groups. If you have not created the group in N2W yet and do not want to use one of the default ones that N2W has already created such as "default_root_delegates" then you can go create the group in N2W later, for now pick a name for the group and create it in Okta. Later when we configure N2W you can create the corresponding group name and choose permissions.
3. Click the newly created group name to add Okta users to the N2W group.
4. Click Manage People 
   
5. Click on the users on the left side that you want to add to the new cpm_users group. 
6. 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. 

7. 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.

8. For the next steps, you need the N2W certificate so you can upload it to Okta. 
   1. Login to your N2W we portal
   2. Go to Identity Provider 
   3. Check the Identity Provider box to enable the settings
   4. Click Download N2W's Certificate to download and save the certificate locally. 
      If you download the file and it has a .txt extension, simple remove it so it has only the .crt extension.  Leave N2W UI open until we come back to configure it, or logout for now without saving changes.
9. Back in your Okta Admin Dashboard, click "Add Application". 

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

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

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

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

14. Complete the General and Advanced General Settings as follows: 
    Single Sign on URL - https://<N2W_Address>/remote_auth/complete_login/ 
     - check the box "Use this for Recipient URL and Destination URL" 
    Audience URI (SP Entity ID)  -  https://<N2W_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://<N2W_Address>/remote_auth/complete_logout/
    Signature Certificate  -  Browse to the N2W certificate you downloaded from the N2W server and then click "Upload Certificate" and wait for the field to populate.
    Authentication Context Class  -  PasswordProtectedTransport

15. Scroll down to the attribute’s 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_", N2W will then search for this specific attribute (case sensitive), check its value and 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"

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

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

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

19. Go Back to your user groups in Okta and open the user group you created for N2W 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 N2W.

N2W Configuration

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

1. Login to N2W 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. 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. 
   N2W Entity ID - Okta Identity Provider Issuer 
   N2W Sign In URL - Okta Identity Provider Single Sign-On URL 
   N2W Sign Out URL - Okta Identity Provider Single Logout URL 
   N2W 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. Go back to your Okta dashboard and click on "My apps" then launch the app from Okta.

6. You will be logged into N2W as the Okta user you can check this in the top right corner of N2W.  
7. In the users section you can see that the user was created automatically by N2W when your Okta user logged in for the first time. 
   

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

Troubleshooting

Here are some common IdP errors and resolutions. 

• Common IdP login issues
• 503 The service is unavailable / 404 File or directory not found
• Invalid issuer in the Assertion/Response (invalid_response)
• A Problem Occurred (500) when configuring the IdP settings in N2W

If the above does not correct the error please open a support issue and also include the N2W logs by using the steps in this link: Gather N2W 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 N2W, in the Identity Provider configuration section.

3. Please provide screenshots of the Identity Provider settings and N2W IdP settings.