Manage Federation with Okta

Okta is just one of the supported external identity providers (IdPs) that you can use with CXone Mpower. This page guides you, step-by-step, in setting up authentication for your CXone Mpower system using Okta.

If you're doing the initial implementation of your CXone Mpower system, there are additional steps to consider. We recommend reading the following online help pages which include these considerations:

Manage Federation with Okta with SAML 2.0

This page guides you, step-by-step, in setting up authentication for your CXone Mpower system using Onelogin as your external identity provider (IdP).

Complete each of these tasks in the order given.

Before you begin, make sure you have access to Okta. You will need to create an application.

Generate the Relay State Value

The relay state value is required for the SAML Okta application that you'll create in the next task. This value is different for every region your organization operates in.

  1. Locate your client ID, which you can obtain from your app registration.

  2. Format your client ID as {"clientId":"{UUID}"}, where UUID is your client ID. For example, {"clientId":"{10g9f8e7d6c5b4a3z2y1x}"}.

  3. Base64-encode the string from the preceding step. The example string from the preceding step becomes eyJjbGllbnRJZCI6InsxMGc5ZjhlN2Q2YzViNGEzejJ5MXh9In0= when base64-encoded.

  4. Save the string to use in the next task.

Create and Configure an Okta Application with SAML 2.0

  1. Log in to your Okta management account.
  2. Click Applications menu > Create App Integration.
  3. Select SAML 2.0 as the method, and click Next.
  4. Enter the name you want to use to identify this integration, and click Next.
  5.  Configure SAML:
    1. Enter a placeholder URL like https://need_to_change in the Single sign-on URL field. You will get the actual Assertion Consumer Service (ACS) URI from your CXone Mpower login authenticator in a later step.
    2. Select Use this for Recipient URL and Destination URL.
    3. Enter a placeholder URL like https://need_to_change in the Audience URI (SP Entity ID). In a later step, you will replace the placeholder with the Entity ID from your CXone Mpower login authenticator.
    4. Enter the Default Relay State value that you generated in the preceding step.
    5. Specify the Name ID format and Application username to correspond with how you want to identify your users to CXone Mpower. Choose the attribute to use as the name ID, such as Okta username or email. Your selection here determines what you use in the External ID field in each CXone Mpower user's employee profile, which you configure in a later step.
    6. Click Show Advanced Settings.

    7. Select a Signature Algorithm. RSA_SHA256 is recommended.

    8. Change Assertion Signature to Unsigned. Leave Response as Signed.
    9. Ensure that Assertion Encryption is Unencrypted.
  6. Click Next, complete the feedback, and then click Finish on the Feedback tab.
  7. Click View SAML setup instructions to open a new tab, then:
    1. Click Download certificate to download the signing certificate. Keep this file for your CXone Mpower configuration.
    2. Close the SAML Setup Instructions tab. Leave the Configure SAML tab open. You will make changes to your configuration based on CXone Mpower settings you will get in a later step.

Set Up a Location

Required permissions: Location Management Create

If you want to require that users log in from a certain IP address, create a location with the IP addresses, IP address ranges, or IP address subnets you want to allow. When you require a configured location for a user, that user must have both the correct credentials and IP address to log in. Otherwise, their login attempt fails and they receive an error. You can have up to 20 locations at a time and up to 10 rules per location.

  1. Click the app selector icon of app selector and select Admin.
  2. Go to Locations > Location Definitions.
  3. Click New Location.
  4. Give the location a descriptive Name. If you want to add more details about the location, enter a Description.
  5. You can select the Set as Default Location or Remote Location to indicate the type of location. You can only have one default location. These fields don't currently affect any functionality and selecting them is for your own reference.

  6. Add any other information you would like using the remaining fields, including the physical address, country, GPS coordinates, time zone, or assigned groups. These fields don't currently affect anything, and the information entered there would be only for your own reference.

    If you add groups to the Assigned Groups field, the users belonging to those groups appear on the Assigned Users tab. However, the location settings won't apply to them. If you assign a location to a login authenticator, the location applies to users who are assigned to that login authenticator and restricts their ability to log in based on their IP address. However, those users will not appear on the Assigned Users tab.

  7. Click Save.

  8. Back on the Location Definitions page, click the location you just created to open it.

  9. Click the Auto-Detection Rules tab.

  10. Create a new rule. To do so: 

    1. Click New Rule.

    2. Give the rule a descriptive Name.

    3. Select the Rule Type from the following: 

      • List: A list of specific IP addresses allowed for this location. For example, 100.0.1.100, 100.0.1.101, and 100.0.1.102.

      • Range: An IP address range allowed for this location. For example, 100.0.1.100-100.0.1.125.

      • Subnet: A subnet allowed for this location. For example, 100.0.0.1/32.

    4. Specify the IP Version as one of the following:

      • IPV4: A 32-bit IP address

      • IPV6: A 128-bit hexadecimal address.

    5. Enter the actual IP addresses, range, or subnet in the Rule Definition field, following the formats of the examples in the preceding steps. If you selected List, you can enter up to 100 IP addresses. If you selected Range or Subnet, you can only enter one value.

    6. Click Confirm.

  11. Add more rules as needed. You can have up to 10.

  12. Click Save.

Set Up a CXone Mpower Login Authenticator with SAML 2.0

Required permissions: Login Authenticator Create

  1. Click the app selector icon of app selector and select Admin.
  2. Click Security > Login Authenticator.
  3. Click New Login Authenticator.
  4. Enter the Name and Description of the login authenticator. For the description, use plain text only. URLs or markup such as HTML will not be saved.
  5. Select SAML as the Authentication Type.

  6. If you want to require that users log in from a certain IP address, select the Location you set up in the preceding section.

  7. Click Choose File and select the public signing certificate you downloaded from Okta in the previous task. This certificate must be a PEM file. It will be a text file and the first line will contain BEGIN CERTIFICATE with some additional text.

  8. Select the Assigned Users tab. Select the users that you want to assign to the login authenticator you are creating. You can also assign users directly to the login authenticator in their employee profile.

  9. Click Save and Activate.
  10. Open the login authenticator.

  11. You will notice two additional read-only fields displayed: the Entity ID and the ACS URL. Make a note of these values. You will need them in the Add CXone Mpower Values to Okta task.

Configure CXone Mpower Users

Complete this task in CXone Mpower fir all CXone Mpower users who require single sign-on with Okta. You can also complete this step using the bulk upload template.

  1. In CXone Mpower, click the app selector and select Admin.

  2. Click Employees.

  3. Select the employee profile to modify and click Edit.

  4. If you haven't already done so, go to the Security tab and select the login authenticator you created previously.

  5. Ensure that the External Identity is set to the correct value. The value must match exactly the Unique User Identifier in Okta.

  6. Save your changes.

Add CXone Mpower Values to Okta

  1. Return to your Okta application and go to the General tab.
  2. Click Edit on the SAML Settings window, then click Next.
  3. For Single Sign On URL, enter the ACS URL value from your CXone Mpower login authenticator.
  4. For Audience URI (SP Entity ID), enter the Entity ID value from your CXone Mpower login authenticator.
  5. Click Next, then click Finish to complete the change.

Test the SAML Integration

Before assigning the SAML login authenticator to users in CXone Mpower, you should test the SAML integration. If the test fails, review your configurations and make changes to the settings.

  1. Initiate a login from the Okta dashboard.
  2. Verify that the SAML authentication flow works as you expect it to.

Verify User Access with Okta Single Sign-On

  1. Have one or more test users log in using the latest login URL, https://cxone.niceincontact.com. For FedRAMP, use https://cxone-gov.niceincontact.com. After entering their username, they will be directed to Okta if needed.

  2. When you're ready, roll out Okta single sign-on to all employees.

Manage Federation with Okta with OpenID Connect

Complete each of these tasks in the order given.

Configure an Okta Application with OpenID Connect

  1. Log in to your Okta management account.
  2. Click Applications menu > Create App Integration.
  3. Select OIDC - OpenID Connect as the Sign-in method.
  4. Select Web Application as the Application type, and click Next.
  5. In the App integration name field, enter the name you want to use to identify this integration.
  6. You will need to provide a Sign-in Redirect URI which you don't know at this point. Use https://cxone.niceincontact.com/need_to_change as a placeholder. You will change this value with the URI you receive later.
  7. You may need to provide a Sign-out Redirect URI which you don't know at this point. Use https://cxone.niceincontact.com/need_to_change as a placeholder. You will change this value with the URI you receive later.
  8. In the Controlled access drop-down, select Skip group assignment for now.
  9. Click Save.
  10. On the General tab under Client Credentials, select Client authentication.
  11. Select one of the following authentication methods:
    1. client_secret_basic: client credentials are passed in a basic header during authentication. After selecting this method, configure the following:
      1. Select Client authentication as the Client secret.
      2. Copy the Client ID and Client Secret and paste them to a secure place on your device. You will need to use them when you configure a login authenticator in CXone Mpower.
    2. client_secret_post: client credentials are passed in a body during authentication. After selecting this method, configure the following:
      1. Select Client authentication as the Client secret.
      2. Copy the Client ID and Client Secret and paste them to a secure place on your device. You will need to use them when you configure a login authenticator in CXone Mpower.
    3. client_secret_jwt: JWT bearer tokens are used for client authentication. After selecting this method, configure the following:
      1. Select Client authentication as the Client secret.
      2. Copy the Client ID and Client Secret and paste them to a secure place on your device. You will need to use them when you configure a login authenticator in CXone Mpower.
    4. private_key_jwt: JWT bearer tokens are used for client authentication. The JWT is signed by the Client Private Key that you will provide in later steps. After selecting this method, configure the following:
      1. Select Client authentication as the Public key / Private key.
      2. Enter a placeholder public key in the Add public key field. You will need to replace the placeholder with the key provided by CXone Mpower when you configure your login authenticator.
  12. On the Assignments tab, click Assign, then click Assign to People.
  13. Assign users to this application.

Set Up a Location

Required permissions: Location Management Create

If you want to require that users log in from a certain IP address, create a location with the IP addresses, IP address ranges, or IP address subnets you want to allow. When you require a configured location for a user, that user must have both the correct credentials and IP address to log in. Otherwise, their login attempt fails and they receive an error. You can have up to 20 locations at a time and up to 10 rules per location.

  1. Click the app selector icon of app selector and select Admin.
  2. Go to Locations > Location Definitions.
  3. Click New Location.
  4. Give the location a descriptive Name. If you want to add more details about the location, enter a Description.
  5. You can select the Set as Default Location or Remote Location to indicate the type of location. You can only have one default location. These fields don't currently affect any functionality and selecting them is for your own reference.

  6. Add any other information you would like using the remaining fields, including the physical address, country, GPS coordinates, time zone, or assigned groups. These fields don't currently affect anything, and the information entered there would be only for your own reference.

    If you add groups to the Assigned Groups field, the users belonging to those groups appear on the Assigned Users tab. However, the location settings won't apply to them. If you assign a location to a login authenticator, the location applies to users who are assigned to that login authenticator and restricts their ability to log in based on their IP address. However, those users will not appear on the Assigned Users tab.

  7. Click Save.

  8. Back on the Location Definitions page, click the location you just created to open it.

  9. Click the Auto-Detection Rules tab.

  10. Create a new rule. To do so: 

    1. Click New Rule.

    2. Give the rule a descriptive Name.

    3. Select the Rule Type from the following: 

      • List: A list of specific IP addresses allowed for this location. For example, 100.0.1.100, 100.0.1.101, and 100.0.1.102.

      • Range: An IP address range allowed for this location. For example, 100.0.1.100-100.0.1.125.

      • Subnet: A subnet allowed for this location. For example, 100.0.0.1/32.

    4. Specify the IP Version as one of the following:

      • IPV4: A 32-bit IP address

      • IPV6: A 128-bit hexadecimal address.

    5. Enter the actual IP addresses, range, or subnet in the Rule Definition field, following the formats of the examples in the preceding steps. If you selected List, you can enter up to 100 IP addresses. If you selected Range or Subnet, you can only enter one value.

    6. Click Confirm.

  11. Add more rules as needed. You can have up to 10.

  12. Click Save.

Set Up a Login Authenticator with OpenID Connect in CXone Mpower

  1. Click the app selector icon of app selector and select Admin

  2. Go to Security Settings > Login Authenticator.

  3. Click New Login Authenticator or select the login authenticator you want to edit.
  4. Enter the Name and a Description of the login authenticator.
  5. Select OIDC as the Authentication Type.

  6. If you want to require that users log in from a certain IP address, select the Location you set up in the preceding section.

  7. If you have a discovery endpoint from Okta, click Discover Settings. Enter your discovery endpoint and click Discover. The remaining fields are populated for you. Discover Settings does not work with Salesforce discovery endpoints.
  8. Enter your Client Identifier and Client Password. Re-type the password in Client Confirm Password. The Client Identifier is the Login ID assigned to your account by Okta.

  9. If you don't have a discovery endpoint from Okta, enter your Okta-provided Issuer, JsonWebKeySet Endpoint, Authorization Endpoint, Token Endpoint, UserInfo Endpoint, and Revocation Endpoint.

    Field

    Details
    Issuer

    Okta's URL without any parameters.
    JsonWebKeySet Endpoint The URL of Okta's JWK Set.
    Authorization Endpoint The URL of Okta's OAuth 2.0 Authorization Endpoint.
    Token Endpoint The URL of Okta's OAuth 2.0 Token Endpoint.
    UserInfo Endpoint The URL of Okta's UserInfo Endpoint.
    Revocation Endpoint The URL of Okta's Revocation Endpoint.
  10. Select a Client Authentication Method. The method you select must match what you set up in the previous task. It must be an authentication method that Okta supports. If you select private_key_jwt, you must enter your Client Private Key.
  11. You can select Enable FICAM Profile to turn on United States government-specific settings. This step is only for FedRAMP users.

  12. Select the Assigned Users tab. Select the users that you want to assign to the login authenticator you are creating. You can also assign users directly to the login authenticator in their employee profile.

  13. Click Save & Activate to validate the provided information and to link your CXone Mpower account to your Okta account.
  14. Open the login authenticator.

  15. Note the Sign-in Redirect URI and Sign-out Redirect URI. You will need them to update your Okta settings.

  16. Update your Okta settings, replacing the placeholders used in the previous task with the values you just noted.

  17. Ensure that the CXone Mpower External Identity for each user that uses the login authenticator is set to the correct value. This field can be accessed in the security section of the employee's profile.

    Okta determines the value that must be used. It can be found in the user's profile in Okta. The value must match exactly what you put in the External Identity field in CXone Mpower. The value for this field must be in this format: claim(email):{email configured by your IdP}. For example, if the user's email in the IdP is nick.carraway@classics.com, you would enter claim(email):nickcarraway@classics.com.

  18. Have the user log in to CXone Mpower. They must use the latest login URL. After entering their username, they will be directed to Okta if needed.

  19. When Okta asks you to authenticate your own account, do so as the user you want associated with your currently-logged in CXone Mpower account.
  20. If your OpenID Connect settings in CXone Mpower don't show as validated, use Okta's logs to diagnose the problem.

Add CXone Mpower Values to Okta

  1. Return to your Okta application and go to the General tab.
  2. Click Edit on the SAML Settings window, then click Next.
  3. For Single Sign On URL, enter the ACS URL value from your CXone Mpower login authenticator.
  4. For Audience URI (SP Entity ID), enter the Entity ID value from your CXone Mpower login authenticator.
  5. Click Next, then click Finish to complete the change.

Verify User Access with Okta Single Sign-On

  1. Ensure that the External Identity for each employee who uses the login authenticator is set to the correct value. The value must exactly match External Identity in CXone Mpower. The External Identity field is case sensitive.

  2. Have one or more test users log in using the latest login URL, https://cxone.niceincontact.com. For FedRAMP, use https://cxone-gov.niceincontact.com. After entering their username, they will be directed to Okta if needed.

  3. When you're ready, roll out Okta single sign-on to all employees.