Important
For information on how CXone authenticates users, see the online help. The help site provides information like setting up
SSO, MFA, login authenticators, and so forth. This page explains application authentication.
For instructions on setting up API authentication, see the Getting Started Page.
For your integration to interact with CXone via API, you must set up OAuth2.0 authentication. The authentication process generates an access token. Your integration must include this token in calls to CXone APIs. This verifies that your integration is authorized to work with your CXone system. CXone supports standard OAuth2.0 and OpenID Connect specifications for authentication. Your application type determines which auth flow you must implement.
There are many resources around the internet to help you understand OAuth flows. You may want to review or familiarize yourself with these resources.
Your app’s purpose and the actions it performs determines its type. NICE categorizes applications into two types: back-end apps and user apps. The type of application you build determines the type of authentication flow you must implement.
The following sections explain these two application categories in more detail.
A back-end application typically performs actions without direct user involvement. It must interact with CXone APIs in a high-trust environment. This means the app does not expose the client ID and secret. Back-end apps must set up standard OAuth2.0 authentication with a password grant type. This is for server-to-server authentication where no user is present.
Even though this app type does not include a present user, the app still interacts with CXone through a CXone user account. For back-end apps to communicate with CXone, you must create a CXone user account. This user account can be considered an API user. An API user should have:
The way your application communicates with CXone through this API user is with an Access Key ID and Access Key Secret. These two credentials are generated from the user account’s settings in CXone. During the authentication process, your app must provide these credentials to the authentication server. See tasks 3 and 4 on the Getting Started Page for more information.
For a back-end app to authenticate, it must exchange four credentials for an access token:
User application involve direct user involvement and require a login flow, like an agent client. An end-user interacts with your application, and the application interacts with CXone on behalf of the end-user. For these apps, the end-users must be authenticated, which you do through an OpenID Connect flow. This flow produces an auth code. Your app must exchange the auth code for an access key and ID token.
The following drop-down defines parameters used in OpenID Connect flows. Some are required for the authentication flow. Others are optional and let you change the behavior of the login.
| FIELD | VALUE | DETAILS |
|---|---|---|
| scope* | openid | The only supported value for CXone API authentication. |
| response_type* | code | The only supported value for CXone API authentication. |
| client_id* | application specific | The value that NICE CXone provided upon approval of your app registration. |
| redirect_uri* | application specific | This value changes based on your app. It is the URI that you want to redirect users to after they login with CXone user credentials. |
| state | application specific |
This value is for the use of the application. It's passed unmodified to the redirect callback. For example, this might be used to store the URL that the user is directed to after a successful login. |
| display | Either page or popup | Determines if the CXone login page opens in a new browser tab or a separate window that pops up. |
| max_age | Integer |
Indicates how recently the user must have authenticated to continue using the current user session. This is optional for the initial auth flow and not allowed in other cases.
Enter a value in seconds. When you include this parameter, the returned ID token includes an auth_time claim. |
| id_token_hint | A previously received id_token |
An existing id_token that you have already received. It identifies the user who must authenticate. This is optional for the initial auth flow and not allowed in other cases.
If the identified user matches the current valid user session, then no user interaction is required. If the identity does not match or if there is no current state available, then a new session is started that is constrained to authenticate the identified user. This parameter takes priority of login_hint if both are present. |
| login_hint | Username | This can be used to bypass the request for a username. The user may be able to change the username even with this parameter specified |
| code_challenge | Random string per PKCE standard | A PKCE code challenge, described in section 4.3 of the PKCE standard. This is optional for the initial auth flow and not allowed in other cases. |
| code_challenge_method | S256 | A PKCE code challenge method, described in section 4.3 of the PKCE standard.. This is optional for the initial auth flow and not allowed in other cases. |
| tenantId | The assigned tenant identifier |
This parameter is part of the CXone platform, not the OpenID Connect standard.
The identifier for your CXone tenant that is requesting authentication. This lets you include branding customization to the CXone login page, like a unique banner. This is optional for the initial auth flow and not allowed in other cases. |
User applications are separated into two sub-categories: public and confidential. The following sections explain the differences.
This type of app authenticates CXone users without handling their sensitive information. From your app, you direct the user to a CXone login page where they enter their credentials. After doing so, they're redirected back to your app with an auth code. Your app must then exchange the auth code for an access token and ID token. Your app doesn't handle credentials since the user enters credentials on the login page. Upon completion, your app then has an access token that lets it operate on behalf of the user. This whole process is an implementation of the OpenID Connect standard in an unframed browser window.
You can use a PKCE extension as a security mechanism for public applications. In this flow, you use a dynamically generated code verifier to prove the user's identity during the token exchange. Instead of using the client secret, PKCE introduces a code verifier to use during the auth flow. Your app generates a code challenge, which is derived from the code verifier, and sends it in the initial authentication request. When the auth server returns the auth code, your app then sends the code verifier with the code to the token endpoint to get the access token. The code verifier lets the auth server confirm that your app, which initiated the flow, is also the one exchanging the auth code for the token, without requiring a client secret. The PKCE flow uses the client ID and code verifier, instead of the client secret.
Key facts about public app authentication:
These applications are able to securely store and use a client secret. In this auth flow, you send the client ID and secret when making requests to the /token endpoint. The token request must include the client secret, grant type, authorization code, and redirect URI parameters. This returns an access token. Confidential apps are similar to back-end apps, but they also involve a user authentication step with the authorization code flow.
CXone authentication is based primarily on the idea of a bearer token. There are three different tokens returned:
The access and refresh token are opaque. This means that they should be treated as "black box". Even if the contents are understood, the internals must not be used directly as the contents may change at any time. If your application provides its own functionality based on CXone platform security, then the access token must be understood and any changes incorporated into the application. Except in this case an application shouldn't look at the contents of the access token. ID tokens are not opaque.
The ID token is a JSON web token (JWT). A JWT is meant to be decoded to understand who has authenticated. Many publicly available tools exist to decode JWTs, like jwt.io.
{
"sub": "user:11eb660f-4fdf-02d0-8f28-0242ac110002",
"icDomain": "nice-incontact.com",
"iss": "https://cxone.niceincontact.com",
"given_name": "first",
"userId": "11eb660f-4fdf-02d0-8f28-0242ac110002",
"aud": "NICEinContactDEVone13@NICEinContact Inc.",
"icBUId": 4596676,
"tenantId": "11eb660f-4c6d-34a0-8733-0242ac110002",
"name": "name@host.com",
"family_name": "last",
"tenant": "PRODUCT_APPLICATIONS",
"icClusterId": "C31",
"iat": 1626874686,
"exp": 1626878286
}
Most of the fields in the ID token are part of the OIDC specification. CXone does add a few CXone-specific fields like the business unit and server cluster IDs.
Access tokens expire after a time-to-live (TTL) duration. This means your apps must generate a new token periodically. The TTL is identified in the token details if you decode the token. This also means you should build in logic to handle 401 - Unauthorized responses from APIs.
The token endpoint returns you an access token, an ID token, and a refresh token. To receive a new access token, you can pass the refresh token to the token endpoint. Since public apps handle user credentials and a login process, you should use the refresh token. This lets the user skip the process of logging in every few minutes when the access token expires. For back-end apps, repeat the same process of generating a new access token.
When Getting Started, you must submit a registration form to NICE. This provides NICE with details about your integration. For example, you’ll specify its purpose, the API groups you plan to use, your authentication type, and so on. After processing your application, NICE responds back with a client secret and client ID. Your app must provide CXone with these credentials during the authentication process.