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. |
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 |
|
Response |
Token exchange response: { "access_token": "eyJbGciO...", "token_type": "bearer", "expires_in": 7199, "scope": "read", "sites": [ "306" ], "jti": "a1bc11d1-11a1-1111-b111-d1111e1f11f1" } |