Set Up CXone Authentication Using an External Identity Provider

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

Before You Begin

• Gain a basic understanding of authentication and authorization concepts and terminology if you've never set up a process like this before.
• Review the CXone-specific process if this is the first time you've worked with authentication in CXone.
• Consider your human users and the levels of access they need. Decide whether people with greater access should have greater levels of security.
• Decide whether you will use custom password requirements, multi-factor authentication (MFA), or both to enforce.
• Based on your decisions, make a list of login authenticators. The list should include the password requirements and MFA status you want to use for each login authenticator. You don't have to create custom login authenticators if the default login authenticator meets your password management needs.
• Consider whether you need to include authentication and authorization for applications like bots or intelligent virtual assistants (IVAs). If so, you will need to create access keys.
• Identify your external IdP. CXone supports both hosted and cloud service IdPs. If necessary, involve your company's authentication experts in this process. There may already be established processes for integrating systems like CXone with your external IdP. Following these processes and meeting your specific security needs is ultimately your responsibility.
• Define your authentication protocol. CXone supports SAML 2.0 and OpenID Connect.
• Evaluate the combination of IdP and protocol to ensure your use cases and user flows are supported, and to identify potential issues. This should include actual testing.

• If you use IdP-initiated authentication, use the following table to determine if your CXoneapplications support it:

  application	IdP-Initiated	SP-Initiated	*Notes
  MAX	Yes	Yes
  CXone Agent	*Yes	Yes	IdP-initiated is only supported when users access CXone Agent from the app selector in the CXone product. Accessing CXone Agent using the direct URLs requires SP-initiated authentication.
  CXone Agent Embedded, CXone Agent Integrated, CXone Agent for Microsoft Teams, Agent for Service Cloud Voice	No	Yes
  Salesforce Agent	*No	Yes	Standalone applications don’t support IdP-initiated.
  CXone Studio	Yes	Yes
  Desktop Studio	*No	Yes	Standalone applications don’t support IdP-initiated.
  Developer Portal	No	Yes

  All existing and future CXone products support SP-initiated authentication.

Your NICE CXone team can support and guide you in this planning process. Good planning makes for a smoother implementation. Implementing authentication and authorization as immediate needs come up is more likely to lead to issues.

Create External Login Authenticators with SAML 2.0

Required permissions: Login Authenticator Create

To create external login authenticators with OpenID Connect, skip this section. Login authenticators are used to manage password criteria. You can create different login authenticators for different users.

You can use external authentication when you want a user's password to be managed by another system or identity provider. CXone currently supports SAML 2.0 and OpenID Connect federation protocols.

You can set up IdP-initiated authentication or SP-initiated authentication with the steps in this section.

IdP-Initiated Authentication: IdP stands for identity provider. IdP-initiated authentication means that the external identity provider starts the login process.

SP-Initiated Authentication: SP stands for service provider. SP-initiated authentication means that CXone starts the login process.

1. Ensure that you have access to the external identity provider. You will need to create an integration specific to CXone.
2. Create the integration in the external identity provider. Different systems use different names for these integrations, see specific instructions for Okta or Azure.
   1. You will need to provide an Entity ID which you don't know at this point. Use https://cxone.niceincontact.com/need_to_change as a placeholder.
   2. You will need to provide an ACS URL which you don't know at this point. Use https://cxone.niceincontact.com/need_to_change as a placeholder.
   3. The identity provider will generate a specific URL where SAML requests must be sent. Copy and save this URL to a place where you can find it. You will need to enter this value in later steps.
   4. The identity provider will generate a public signing certificate for the integration. Download the certificate. You will need to use it in later steps.
3. Create an external login authenticator in CXone.
   1. Click the app selector and select Admin.
   2. Click Security > Login Authenticator.
   3. Enter the Name and Description of the login authenticator.
   4. Select SAML as the Authentication Type.
   5. If you select FICAM, the SAML response must have a single AuthnContextClassRef entry. Also, the NamespaceURI of the assertion subject must be: urn:oasis:names:tc:SAML:2.0:assertion. The AuthnContextClassRef and NamespaceURI fields are controlled by the identity provider.
   6. Enter the SAML request Endpoint you received from your provider above as the Endpoint URL.
   7. Click Choose File and select the public signing certificate you received from your provider. This file must be a PEM file. It will be a text file and the first line will contain BEGIN CERTIFICATE with some other text.
   8. Click Save and Activate.
   9. Open the login authenticator.

   10. Note the Entity ID and ACS URL. You will need them when updating your IdP settings.

4. Update your identity provider settings, replacing the placeholders used above with the values you just noted.

5. Ensure that the External Identity for each user that uses the login authenticator is set to the correct value.

   Your identity provider determines the value that must be used. The value must match exactly what you put in the External Identity field in CXone.

6. Have the user log in. They must use the latest login URL. After entering their username they will be directed to the external identity provider if needed.

Create External Login Authenticators with OpenID Connect

Required permissions: Login Authenticator Create

You can use external authentication when you want a user's password to be managed by another system or identity provider. CXone currently supports SAML 2.0 and OpenID Connect federation protocols.

You can set up SP-initiated authentication with the steps in this section.

SP-Initiated Authentication: SP stands for service provider. SP-initiated authentication means that CXone starts the login process.

1. Ensure that you have access to the external identity provider. You will need to create an integration specific to CXone.
2. Create the integration in the external identity provider.
   1. 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.
   2. 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.
   3. The identity provider will generate a Client ID and a Client Secret. Copy and save these values where you can find them. You will need to enter them in later steps.
3. Create an external login authenticator in CXone.

   1. Click the app selector and select Admin.

   2. Click Login Authenticator.

   3. Click Create New 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 have a discovery endpoint for your IdP, 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.
   7. 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 your IdP.

   8. If you don't have a discovery endpoint for your IdP, enter your IdP-provided Issuer, JsonWebKeySet Endpoint, Authorization Endpoint, Token Endpoint, UserInfo Endpoint, Revocation Endpoint, and End Session Endpoint.

      Learn more about fields in this step

      Field	Details
      Issuer	The URL of your IdP without any parameter.
      JsonWebKeySet Endpoint	The URL of your IdP's JWK Set.
      Authorization Endpoint	The URL of your IdP's OAuth 2.0 Authorization Endpoint.
      Token Endpoint	The URL of your IdP's OAuth 2.0 Token Endpoint.
      UserInfo Endpoint	The URL of your IdP's UserInfo Endpoint.
      Revocation Endpoint	The URL of your IdP's Revocation Endpoint.
      End Session Endpoint	The URL of your IdP's End Session Endpoint. This field allows you to create a single logout experience for your users. If configured, when they log out of CXone, they will also be logged out of their IdP account. For single logout to work, you must whitelist the Sign-out Redirect URI in your IdP.

   9. Select a Client Authentication Method. The method you select must be an authentication method that your IdP supports. If you select private_key_jwt, you must select Enable Encryption and enter your Client Assertion Verification Key.
   10. You can select Enable FICAM Profile to turn on U.S. government-specific settings.
   11. Click Create Login Authenticator to validate the provided information and to link your CXone account to your IdP account.
   12. Open the login authenticator.

   13. Note the Sign-in Redirect URI and Sign-out Redirect URI. You will need them when updating your IdP settings.

4. Update your identity provider settings, replacing the placeholders used above with the values you just noted.

5. Ensure that the External Identity for each user that uses the login authenticator is set to the correct value.

   Your identity provider determines the value that must be used. The value must match exactly what you put in the External Identity field in CXone. 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.

6. Have the user log in. They must use the latest login URL. After entering their username they will be directed to the external identity provider, if needed.

7. When your IdP asks you to authenticate, do so as the user on the IdP you want associated with your currently logged in CXone account.
8. If your OpenID Connect settings in CXone don't show as validated, use your IdP logs to diagnose the problem.

Linking New Users with Claim-based OpenID Connect

CXone can use a different claim value, like an email address, to establish the user's identity at their first login. CXone then automatically switches to the unique OpenID Connect subject identifier. This allows you to pre-configure a user's federated identity.

PKCE for Front-End Authentication

You may have difficulty using the OpenID Connect authorization code flow. This flow requires a client_secret as part of the token exchange. Coding the client_secret into a web application is a security risk. OpenID Connect allows an alternative flow called PKCE (Proof Key for Code Exchange). PKCE uses a different authentication method. NICE CXone supports PKCE flows for front-end integrations.

Create Security Profiles

Required permissions: Security Profile Create

1. Use one of the following methods to create the security profile and give it a name: 

   • To create a new blank security profile:

     View image

     
     1. Click the app selector and select Admin.
     2. Go to Security Profiles.

     3. Click Create New.

     4. Enter a unique Name for the security profile.

     5. Enter a Description if you want one.

     6. For Create, select a blank Security Profile.

   • To quickly create a new security profile that copies an existing one:

     View image

     
     1. Click the app selector and select Admin.
     2. Go to Security Profiles.

     3. Open the security profile you want to copy.

     4. Click Copy.

     5. Enter a unique Name for the security profile.

     6. Enter a Description if you want one.

2. Click Next.

3. Enable permissions for each product and feature you want users to have. Some permissions, like User Settings and Security, are grouped. To see the permissions inside the groups, click Individual next to the group name.

4. Click Next.

5. Enable permissions for each report you want users to have.

6. Click Next.

7. Restrict data access by Campaigns A grouping of skills used to run reports., Teams, Assignable Profiles, Groups, and Business Units High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment. For each data type, select whether you want users to access All & Future data of that type, None, or Custom.

8. If you chose Custom for a data type, use the pop-up window to specify which entities of that data type the users can access. Click Done.

   New campaigns, teams, security profiles, groups, and business units aren't automatically added to custom lists when they're created. You must update the custom list if you want users to access the new data.

9. Click Next.
10. Click Create Security Profile.

Create or Edit Users

Required permissions: Users Create

When you create new users, you have the option to create new individual users or to upload multiple new user accounts at the same time. These instructions are for creating single users in the Admin application. See Manage Multiple Users at Once for instructions on creating or editing multiple users at the same time.

1. Click the app selector and select Admin.

2. Click Users.

3. Open the new user creation form in one of the following ways: 

   • If you want to create a new user with a blank form, click Create New and select Single User.
   • If you want to create a new user based on an existing user's profile, open that user's profile and click Copy.

4. Enter the user's First Name, Last Name, Email, Username (in the form of an email address), Security Profile, Team, User will use (timezone), City, and Country. If the fields are available, set the password using the Password and Confirm Password fields. Enter any other information you want to add to the user profile.

   Learn more about fields in this step

   Field	Details
   Internal ID	The internal ID assigned to the user. This is not a system-assigned ID and can be any number you choose.
   User Type	Visible and required only if your system includes NICE CXone WFO or NICE CXone WFMv2 and if the user has been assigned to a team that is NICE CXone WFO- or NICE CXone WFM-enabled. Both applications treat agents differently from other users. While you can designate users as Supervisor or Admin if appropriate for your organization’s needs, it is critical to correctly select Agent for all users who should be treated as agents in the NICE CXone WFO and WFMv2 applications.
   Telephone 1	Visible only if your system includes NICE CXone WFMv2 and if the user is assigned to an NICE CXone WFM-enabled team. It allows you to add a telephone number to the user record, other than their NICE CXone PBX Internal telephone network that manages an enterprise's incoming, outgoing, and internal voice calls.-associated number. The field is informational, and the value is not used by the NICE CXone WFMv2 application itself.
   Telephone 2	Visible only if your system includes NICE CXone WFMv2 and the user is assigned to an NICE CXone WFM-enabled team. It allows you to add a second telephone number to the user record, other than their NICE CXone PBX-associated number. The field is informational, and the value is not used by the NICE CXone WFMv2 application itself.
   External Identity Type	Visible only if you have SAML 2.0 or OpenID Connect enabled in your business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment. Use it to specify whether this user's credentials are managed by SAML2 or OpenID Connect.
   Federated Identity	The unique value that is passed to your IdP as part of the authentication assertion. The value is tied to the user requesting authentication to NICE CXone. When your IdP makes an authentication assertion to the NICE CXone platform, it must contain an LDAP claim with the same Federated Identity value configured for the user. The claim value is: Name ID (required) — Exactly matches the user's configured Federated Identity. Name ID is case-sensitive. To configure the signing message, sign only the message ("response") and not the claim.
   SIP User	If you have configured SIP Protocol used for signaling and controlling multimedia communication sessions such as voice and video calls. in your environment, the SIP username of this user in the format sip:user@domain.com.
   Subject	Visible only if you use an external IdP and OpenID Connect. It's the name of this user's IdP account.
   Address line 1 Address line 2 State/Province/Region ZIP/Postal Code	Optional full address details for the user. These fields are used to set up emergency dialing.
   No Fixed Address	Indicates that the user's address is not permanent and should not be used in emergency dialing.
   Location	Customizable location of the user. This can be the building where the user works, the floor of the building, or any other location you choose. This value does not impact emergency calls.
   Hire Date	The date the user was hired.
   Termination Date	The date the user was terminated.
   Rehire Status	Whether the user is Eligible or Not Eligible for rehire in the future.
   Hourly Cost	The user's hourly salary.
   NT Login Name	The user's NT login name.
   Employment Type	The user's current employment type. It can be Full-Time, Part-Time, Temporary, Outsourced, or Other.
   Referral	Referral information about the user.
   At Home Worker	When selected, indicates that the user works remotely.
   Hiring Source	How the user was hired. Click New Hiring Source to add custom options for the drop-down. Example could be Internal Hire, Employee Referral, Recruiter.
   Custom Properties	These five fields are called Custom 1, Custom 2, Custom 3, Custom 4, and Custom 5 by default. However, you can customize the names of the fields in your business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment settings. You can use these properties to meet the needs of your specific organization, such as listing your agents' favorite flavor of ice cream or favorite super hero. Because the fields vary by organization, contact your contact center manager to find out how to use these fields in your business unit. All five fields have a character limit of 40.

5. Select a login authenticator (LA).

   All users must be assigned to a login authenticator, or they won't be able to log in to CXone.

   The type of LA will determine how the user will log in to CXone. You can set up two types of login authenticators.

   System LAs: Users assigned to a system LA will log in using credentials managed by CXone.

   External LAs: Users assigned to an external LA will complete their log in through an external identity provider (IdP). External LAs are configured with either SAML 2.0 or OpenID Connect.

6. If you have Integrated Softphone (WebRTC) custom URLs enabled, configure the Integrated Softphone URLs and URL Weights as needed.

   Learn more about fields in this step

   Field	Details
   Integrated Softphone URL 1-2	Visible only when custom Integrated Softphone (WebRTC) URLs are enabled for your business unit. Specifies which Integrated Softphone URL to apply to the user profile. Custom URLs override the default URLs. For some agents operating under certain conditions, the default URLs can lead to call quality issues. For more information or to enable this feature, contact your CXone Account Representative.
   URL 1-2 Weight	Visible only when custom Integrated Softphone (WebRTC) URLs are enabled for your business unit. If you specified two Integrated Softphone (WebRTC) URLs for the user profile, the URL weights specify the priority of the URLs compared to each other. The higher-weighted URL will be attempted before the lower-weighted URL. If a URL is set to Default, the corresponding field is disabled and has a blank value.

   The following table details the results of each configuration option: 

   Integrated Softphone URL 1	Integrated Softphone URL 2	URL 1 Weight	URL 2 Weight	Resulting Behavior
   Default	Default	Blank	Blank	Default URLs are used.
   Active URL A	Active URL B	Higher	Lower	Custom URLs are used. URL A is attempted first, and then URL B.
   Active URL A	Active URL B	Lower	Higher	Custom URLs are used. URL B is attempted first, and then URL A.
   Active URL A	Active URL B	Equal	Equal	Custom URLs are used. Either URL A or URL B is randomly attempted first, and then the other is attempted.
   Active URL A	Active URL A	Any	Any	Invalid configuration.
   Inactive URL A	Inactive URL B	Any	Any	Default URLs are used.
   Inactive URL A	Inactive URL A	Any	Any	Invalid configuration.
   Active URL A	Inactive URL B	Any	Any	Custom URLs are used. URL A is attempted first, then the default URLs at equal weights.
   Inactive URL A	Active URL B	Any	Any	Custom URLs are used. URL B is attempted first, and then the default URLs at equal weights.
   Default	Active URL B	Any	Any	Invalid configuration.
   Active URL A	Default	Any	Any	Custom URLs are used. URL A is attempted first, and then the default URLs at equal weights.
   Default	Inactive URL B	Any	Any	Invalid configuration.
   Inactive URL A	Default	Any	Any	Default URLs are used.

7. Click Save and Continue.

8. Set the user's Refusal Timeouts for each channel, default Dialing Pattern, and Agent Voice Threshold. If you want to, select Suppress Ringing - Personal Connection.

   Learn more about fields in this step

   Field	Details
   Phone, Voicemail, Chat, SMS, Email, Work Item	The number of seconds the agent can have a request in the personal queue without responding. When the time limit has been reached, the interaction transfers to another agent. If you leave the field blank, the system uses the business unit default value, which is usually 45 seconds. Values for refusal timeouts must be between 15 and 300 seconds. The hardcoded value for WebRTC is 30 seconds, which cannot be changed at the user or station level.
   Dialing Pattern	The default dialing pattern assigned to the user. A dialing pattern specifies the way each call is dialed. For instance, a dialing pattern can specify that each call must begin with '1'. Agents don't need to dial a '1' before every call, because the system prepends it to the number dialed.
   Phone # Timeout	The amount of time an agent's voice path stays connected. This field is set to Default which uses the value specified in the business unit settings. Changing this value overrides the business unit level setting for this user.
   Agent Voice Threshold	The volume level of the agent's voice. This setting helps to accurately distinguish the agent's voice from background noise. The threshold range is based on a custom volume unit computed by the frequency analyzer. Users with proper permissions can change this value themselves through the Voice Threshold tuning setting in MAX.
   Suppress Ringing - Personal Connection	When the agent uses a Personal Connection skill, this setting prevents them from hearing a ringing sound before the system answers the call. Instead, the agent first hears audio when they receive the answered call from the network. This setting overrides the skill setting for Treat Progress as Ringing.

9. If your environment enabled for static delivery, set the default number of Concurrent Chats and Auto-Parked Emails. Specify whether the user can Request Contact.

   Learn more about fields in this step

   Field	Details
   Concurrent Chats	The maximum number of chats the user may engage in simultaneously. It's either the Team Default, or the maximum number of chats allowed for the team to which the user belongs, or a number between 1 and 12.
   Auto-Parked Emails	The maximum number of emails the user may contain in the inbox at one time. It's either the Team Default, or the maximum number of emails allowed for the team to which the user belongs, or a number between 1 and 25.
   Request Contact	When selected, allows the agent to request the next available contact instead of having it routed automatically.

10. If your environment is enabled for dynamic delivery, set the maximum number of simultaneous contacts the user can handle per channel. If you have granular dynamic delivery settings enabled, set the Delivery Mode and Total Contact Count for the user.

    Learn more about fields in this step

    Field	Details
    Voice, Chats, Emails, SMS, Work Items	The maximum number of simultaneous contacts the user can handle. Voice includes both phone calls and voicemails. Setting Voice to Off disables voice for the user. SMS applies to CXone SMS Messaging.
    Delivery Mode	Available only when your NICE CXone account representative enables granular dynamic delivery settings, it specifies whether you want agents on the team to use Omnichannel or Single Contact handling. See Manage Contact Delivery Settings for Dynamic Delivery for more information. The Omnichannel Delivery Mode allows agents to handle multiple contacts using various channels at the same time. Agents can also elevate contacts to other channels. The Single Contact Delivery Mode allows agents to handle only one contact using one channel at a time. Those agents also have the ability to elevate contacts to other channels.
    Request Contact	Available only in a dynamic delivery environment, enables the user to manually request an additional digital (non-voice) contact, if the current state is Working.
    Channel Lock	Available only for an Omnichannel Delivery Type. Temporarily locks an agent to the channel they're currently handling. For example, if the agent configured to handle 2 chat interactions and 1 voice interaction has a Total Contact Count of 3, they can receive one voice or two chat interactions, but not both at the same time. When the agent's interactions have ended, the lock will end. The agent will then be able to receive interactions from any configured channel.
    Contact Auto-Focus	Available only in a dynamic delivery, forces MAX to set the active focus to the newest contact after the contact is connected in the interface.
    Total Contact Count	Available only when your NICE CXone account representative enables granular dynamic delivery settings, specifies the maximum number of total contacts the agent can handle at a time. For example, if you set Chats to 5, Emails to 5, and Total Contact Count to 7, the agent would receive a maximum of seven contacts at any given time. Up to five of those seven contacts could be chat contacts and up to five of them could be email contacts. See Manage Contact Delivery Settings for Dynamic Delivery for more information.

11. If you have a WFO integration enabled other than CXone WFO (such as Uptivity WFO) and want to set up recording, enter the System Domain, System Username, and Phones.

    Learn more about fields in this step

    Field	Details
    System Domain	The domain associated with the System Username.
    System Username	Adds a Windows username to the user account (that is, the name with which the user logs in to your network). This field is mandatory if your organization uses NICE CXone Screen Recording. NICE CXone WFO uses it to locate the user's desktop via the screen recording client. Each user must have a unique system username, regardless of Windows domain, and they must log in to their desktop PC with that system username. For example, if your organization has two Elizabeth Bennets, they cannot both have "ebennet" as their Windows username even if they are on separate Windows domains.
    Phones	The CXone phone ID associated with the user that will be recorded. Consider the following when you add information to the Phones field: You cannot assign an extension to more than one user. For example, extension 1234 cannot be assigned to Elizabeth Bennet and Charlotte Lucas, even if they sit at the same extension on different shifts. You can assign multiple extensions to the same user. For example, Elizabeth Bennet may take incoming calls on extension 1234 and make outbound calls on extension 4321.

12. In the MAX Version section, you can determine which version of MAX you want this user to use.
    Learn more about options in this step

    Field	Details
    Default	The user will use the version defined in the business unit settings.
    Previous	This option is only available if the Permit MAX Per-Agent Versioning setting is enabled in the business unit settings. When selected, the user will use the MAX version prior to the current release. For example, if the current release version is Spring 2021, the user will use the Fall 2020 MAX version with this option selected. This option is typically only useful if the default business unit version is set to Current.
    Current	This option is only available if the Permit MAX Per-Agent Versioning setting is enabled in the business unit settings. When selected, the user will use the up-to-date MAX version according to the current major release, such as Fall 2020 or Spring 2021. This option is typically only useful if the default business unit version is set to Previous.

13. If you have CXone WFM enabled, configure the agent's notification settings.

    Learn more about fields in this step

    Field	Details
    WFM Notifications minutes	The number of minutes before an event in the agent schedule occurs that the agent receives a reminder. This setting applies only to systems that include NICE CXone CXone WFM.

14. If you have NICE CXone WFO and you want to integrate with a CRM, enter the agent's CRM Username to associate it with the user.

15. Click Save.

Authenticate Applications

Users and applications are authenticated in very similar ways. The main difference is that applications are authenticated with an access key while users are authenticated with a username and password. Unlike users, applications are not required to interact through a browser. Applications typically are either back-office functionality or intelligent virtual agents Chatbot or similar application that interacts with a user based on artificial intelligence (IVAs).

To set up an application to interact with CXone, create a user profile and name the profile after the application. Then create an access key for the application user as follows:

Authorization in CXone

Authorization is the process of verifying what resources a user is allowed to access. Resources can include applications, files, and data. You can define users' access to resources with role-based access control. CXone manages authorization automatically during authentication. When a user is authenticated they are given access only to the resources they're authorized for.

A user's authentication method doesn't impact authorization. CXone uses the same authorization process for all users. It doesn't matter whether they are authenticated with access keys or passwords.