Manage Federation with Azure

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

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

Before you begin, make sure you have access to the Microsoft Azure ID management console. You will need to create an application.

Manage Federation with Azure with SAML 2.0

Complete each of these tasks in the order given.

Configure the Relay State Value

The relay state value is required when configuring the SAML Okta application in the next task. Use the value that corresponds to your environment.

Relay State Values by Environment

The following table lists currently supported environments:

Environment Relay state value
Production eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9
FedRAMP eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9
AUSOV1 eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9
EUSOV1 eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9
UKSOV1 eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9
UKSOV2 eyJjbGllbnRJZCI6IjBiNjk3ZWJiLTRlYTItNDA1Mi1iMTJiLWQzY2YxMmE1M2VjYSJ9

Although the Relay State value is currently the same across all environments, each environment has its own unique client ID. Future environments may use different values. Always use the value listed for your environment to ensure forward compatibility.

  1. Identify the environment your organization uses.

  2. Copy the corresponding Relay State value from the table.

  3. Use this value when configuring the SAML Okta application in the next task. 

Create and Configure an Azure Application with SAML 2.0

  1. Log in to your Azure AD management account with your Azure AD administrator account.
  2. Create an application:
    1. Click Enterprise applications > New Application.
    2. Click Create your own application.
    3. Enter a Name (for example, NiCE CXone).
    4. Select Integrate any other application you don’t find in the gallery (Non-gallery).
    5. Click Create.
  3. Assign users and groups to the application as appropriate. Go to the Users and Groups tab and click Add user/group.
  4. In the application's management page, locate the Manage section. Under Set up single sign on, click Get Started and then select SAML.
  5.  On the Basic SAML Configuration panel, click Edit and configure SAML:
    1. Enter an App Name.
    2. Under Identifier (Entity ID), click Add Identifier and enter https://need_to_change. In a later step, you will replace the placeholder with the Entity ID from your NiCE CXone login authenticator.
    3. Under Reply URL, click Add reply URL and in the Audience URI field, enter https://need_to_change. You will get the actual Assertion Consumer Service (ACS) URI from your NiCE CXone login authenticator in a later step.
    4. In the Sign on URL Relay State field, enter the encoded relay state value you generated in the preceding task.
  6. Click Save and close the Basic SAML Configuration panel.
  7. In the Attributes & Claims section, select the correct Unique User Identifier. The value you choose will be the External Identity in NiCE CXone.
  8. Azure AD should automatically create a SAML signing certificate. Download the certificate named Certificate (Base64). You will upload this certificate to your login authenticator in NiCE CXone in a later step.
  9. On the SAML Signing Certificate panel, click Edit and then:
    1. Choose a Signing Option.
    2. Click Save and close the SAML Signing Certificate panel. Keep this file for your NiCE CXone configuration in a later step.
  10. If you want to enable SP-initiated login, complete this step. In the Set up <application name> section, copy the Login URL value. Keep this for your NiCE CXone configuration.
  11. Keep your window open. You will make changes to your Azure application settings based on values you receive in the next task.

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 SAML 2.0 in NiCE CXone

Required permissions: Login Authenticator Create

  1. Click the app selector icon of app selector and select Admin.
  2. Go to Security Settings > 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 Azure in the previous task. This file 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 & 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 NiCE CXone Values to Azure task.

Configure NiCE CXone Users

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

  1. In NiCE CXone, 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 Azure. If an email ID has been configured as the external ID, make sure to format it correctly. In Azure, the email ID format is firstname.lastname@domain.com and it is case sensitive.

  6. Save your changes.

Add NiCE CXone Values to Azure

  1. Return to your Azure application and on the Basic SAML Configuration panel, click Edit.
  2. For Identifier (Entity ID), enter the Entity ID value from your NiCE CXone login authenticator.
  3. For Reply URL, enter the ACS URL value from your NiCE CXone login authenticator.
  4. Click Save and close the Basic SAML Configuration panel.

Test the SAML Integration

Before assigning the SAML login authenticator to users in NiCE CXone, 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 Azure dashboard.
  2. Verify that the SAML authentication flow works as you expect it to.

Verify User Access with Azure Single Sign-On

  1. Have one or more test users log in using the latest login URL. After entering their username, they will be directed to Azure if needed.

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

This is the last step in setting up Federation with SAML 2.0.

Manage Federation with Azure with OpenID Connect

Complete each of these tasks in the order given.

Configure an Azure Application with OpenID Connect

  1. Log in to your Azure management account.

  2. Under App registrations, click New Registration.

  3. Go to Authentication > Web.

  4. You will need to provide Redirect URIs, which you don't know at this point. Use https://cxone.niceincontact.com/need_to_change as a placeholder.

  5. Click Certificates and secrets.

  6. Select client_secret_basic or client_secret_post as your authentication method. The authentication method, private_key_jwt, is not currently supported in NiCE CXone.

  7. In the Client secrets field, select New client secret.

  8. Add a description and select Expires.

  9. 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 NiCE CXone.

  10. Go to Token Configuration > Optional Claims.

  11. Click Add Optional Claim.

  12. Select ID as your Token type.

  13. Select email and add your email address.

  14. Click Save.

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 NiCE CXone Login Authenticator with OpenID Connect

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

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

    Field

    Details
    Issuer

    Azure's URL without any parameter.
    JsonWebKeySet Endpoint The URL of Azure's JWK Set.
    Authorization Endpoint The URL of Azure's OAuth 2.0 Authorization Endpoint.
    Token Endpoint The URL of Azure's OAuth 2.0 Token Endpoint.
    UserInfo Endpoint The URL of Azure's UserInfo Endpoint.
    Revocation Endpoint The URL of Azure's Revocation Endpoint.
    End Session Endpoint

    The URL of Azure's End Session Endpoint. This field allows you to create a single logout experience for your users. If configured, when they log out of NiCE CXone, they will also be logged out of their Azure account. For single logout to work, you must whitelist the Sign-out Redirect URI in Azure.

    If Salesforce is your IdP, then you need to configure a logout URL in Salesforce. To do so, go to Settings > Security > Session Settings > Logout Page Settings. Update the Logout URL field. You'll use this URL as your End Session 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 Azure supports.
  11. You can select Enable FICAM Profile to turn on United States government-specific settings. This step is for FedRAMP users only.

  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 NiCE CXone account to your Azure account.
  14. Open the login authenticator.

  15. Note the Sign-in Redirect URI and Sign-out Redirect URI. You will need them when you update your Azure settings.

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

  17. Ensure that the NiCE CXone 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.

    Azure determines the value that must be used. It can be found in the user's profile in Azure. The value must match exactly what you put in the External Identity field in NiCE 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.

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

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

Add NiCE CXone Values to Azure

  1. Return to your Azure application and on the Basic SAML Configuration panel, click Edit.
  2. For Identifier (Entity ID), enter the Entity ID value from your NiCE CXone login authenticator.
  3. For Reply URL, enter the ACS URL value from your NiCE CXone login authenticator.
  4. Click Save and close the Basic SAML Configuration panel.

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

    1. Your identity provider determines the value that must be used. The value must match exactly the Unique User Identifier in Azure and the External Identity in NiCE 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.

Verify User Access with Azure 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 match exactly the Unique User Identifier in Azure and the External Identity in NiCE CXone.

  2. Have one or more test users log in using the latest login URL. After entering their username, they will be directed to Azure if needed.

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