OAuth token exchange

The Nuance Reporting API v3 supports the use of OAuth 2.0 JSON Web Tokens (JWTs) for token exchange to facilitate the granting of access tokens, without necessitating the use of passwords. The following diagram illustrates the process flow and authentication mechanisms used.

Register the application

Clients may request application registration with Nuance by contacting their Client Services Manager (CSM). The CSM will register your application with the Nuance System Team.

The clientId identifies your application and builds login URLs.

The clientSecret authenticates the identity of your application. It must be kept private between the application and the API.

Note: The client is responsible for storing the clientID and the clientSecret securely. If this information is compromised, you must request a lock on the account and a new registration with your CSM.

Generate RSA key pair

Clients must generate the RSA Private Key and Public Key pair. The Private Key will be securely stored on the client-side, and the Public Key will be shared with Nuance.

Securely store the Private Key

The client must not share their Private Key with anyone, including Nuance. In addition, the client must apply proper security measures to ensure that the Private Key is not leaked or otherwise compromised. The Private Key will be associated with Key ID, which is included in the JWT and will be used by Nuance to locate the corresponding Public Key.

Provide Public Key to Nuance

The client must send its Public Key and Key ID to Nuance, who will store these in their database. Nuance uses the Public Key to verify the token signature in the token exchange flow to ensure that they are the legitimate and allowed representation of the client. To allow for key rollover, the client can provide new keys before their expiration of the existing keys, which will remain valid until they expire.

Retire compromised Public Keys

In the event that a Public Key is compromised, the client must report the compromised Key IDs to Nuance. The Public Key corresponding to the compromised Key IDs will be removed by Nuance from their database, and any tokens associated those keys will be rejected.

Sample RSA key pair generation

# Generate private key
openssl genrsa -out privatekey.pem 2048
# Generate public key
openssl rsa -in privatekey.pem -pubout -out publickey.txt -outform PEM

Construct a subject token to exchange

The subject token is the JWT that will be used to get the user access token using the token exchange grant type.

Request header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "unique-id"
}
Argument Description
alg The algorithm (RS256).
typ The type of access token (JWT).
kid The Key ID; may be constructed by hashing the key. Nuance uses the Key ID to locate the client's Public Key, so a new Key ID must be generated every time a new key pair is created.

Payload

{
  "iss": "BELISLE",
  "aud": "NUANCE",
  "jti": "LPJ3-DtFsDiXAUBKK_IhBQ",
  "sub": "sacha.belisle",
  "email": "agt@tc.com",
  "iat": 1635153011,
  "nbf": 1635153011,
  "exp": 1635239411
}
Argument Description
iss The identity of the client who signed the token.
exp The token's expiry time, represented as an epoch timestamp.
jti The ID for the access token that is used for tracking purposes. Clients can ignore this value.
sub The username in Portal used to authorize access.
email The email address of the client that will be invoking the API.

Note: For more information, see RFC JSON Web Token, Section 4.1.

Signature

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret/private key)

The signature is comprised of the encoded header, the encoded payload, either the clientSecret or Private Key and the algorithm specified in the header.

Exchange subject token for NDEP user access token

The token exchange is conveyed using an HTTP POST method via a token exchange request to the token endpoint. The NDEP authorization server will locate the Public Key stored in the NDEP database and verify it against the Key ID contained in the subject token. Then the NDEP authorization server will perform the standard token verification, which includes validation of the token signature and claims. After successful verification of the subject token, the NDEP authorization server will issue the standard user-level access token for the Portal user specified in the sub claim.

The following parameters are included in the HTTP request's entity-body using the "application/x-www-form-urlencoded" format.

Argument Description
Method POST
Header Authorization : "Basic bese64Encode(clientID:clientSecret)"
URL https://{auth.nuance.com}/oauth-server/oauth/token
Parameters
  • grant_type
    urn:ietf:params:oauth:grant-type:token-exchange

  • subject_token
    iJIzI1Ni...

Response

Token exchange response:

{
    "access_token": "eyJbGciO...",
    "token_type": "bearer",
    "expires_in": 7199,
    "scope": "read",
    "sites": [
        "306"
    ],
    "jti": "a1bc11d1-11a1-1111-b111-d1111e1f11f1"
}