API token authentication

You need API credentials to obtain authorized access to the API. To obtain API credentials, you must create a user account in Portal with the required role. Once you access the API, a session is maintained, which enables the client to make data requests. The client can make data requests for the duration of the session based on the initial authentication.

To access the User Management API (UMAPI), you need an access token from the Nuance Auth Server.

  1. Create an RSA keypair, store the private key and send the public key to Nuance.

  2. Generate a JWTClosed (JSON Web Token) token signed with your private key.

  3. Call the Auth server with this JWT in an Authorization header to obtain an access token.

  4. Call the User Management API with this access token in an Authorization header.


Request user access to the User Management API

Request a dedicated user from your Nuance program manager with the SaaS Client Administrator role.

Obtain client ID and secret from Nuance

Your Nuance program manager provides the client ID and secret that the token exchange API uses.

Generate a key pair

Follow proposed industry security standards. For reference, see RFC7518 - JSON Web Algorithms (JWA).

Example of generating a key pair

Use OpenSSL to generate the key pair:

  1. Generate an RSA private key.
    openssl genrsa -out privatekey.pem 2048

  1. Extract the public key.
    openssl rsa -in privatekey.pem -pubout -out publickey.txt -outform PEM

Service-based access

  • Each application requires one key.

  • Each application can support multiple users with different roles.

Securely store the private key

  • Do not share the private key with anyone, not even with Nuance.

  • Store the private key inside the server or HSM that you use to sign the token. Apply proper security measures to ensure the key does not get leaked.

  • The private key is associated with a key ID included in the JWTClosed (JSON Web Token). Nuance uses this to locate the corresponding public key.

Provide the public key to Nuance

  1. Send the public key and key ID to Nuance.

    Nuance authenticates the user providing the public key to ensure that this user is your legitimate representative.

    Although the key content is public, Nuance must prevent any other user from replacing or adding public keys on your behalf.

  2. Nuance stores the public key and associates it with the key ID.

Tip: To allow key rollover, you can provide new keys before the existing keys expire. Existing keys remain valid until they expire.

Retire compromised public key

  • Report any compromised key IDs to Nuance.

  • Nuance removes from its storage the public keys that correspond to compromised key IDs. Any tokens signed with those keys will be rejected.

Construct a JWT with an RS256 signature

Generate the token header

The token header should contain the following:

  • The algorithm (RS256) in the alg header.

  • The token type (JWTClosed (JSON Web Token)) in the typ header.

  • The key ID in the standard kid header.

Note: You must generate a new key ID each time you create a new key pair, because Nuance uses the key ID to locate your public key.

Tip: You can hash the key to construct a key ID.

JWT header example

{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "acmekid1"
}

Generate the token payload

The token payload should contain the following:

  • The Issuer (identity of the token signer) in the iss claim.

  • The token expiry time represented as an epoch timestamp in the exp claim.

  • A unique identifier for this token in the jti claim.

  • The Portal username for authorizing access in the sub claim. (To be confirmed with Auth design.)

  • Optional. The email address of the end user on whose behalf the API is invoked in the email claim. (To be confirmed with Auth design.)

  • Other claims required by Auth design or by Keycloak token exchange.

  • See https://tools.ietf.org/html/rfc7519.

JWT payload example

{
    "iss": "ACME",
    "aud": "NUANCE",
    "exp": 1510095117,
    "jti": "LPJ3-DtFsDiXAUBKK_IhBQ",
    "iat": 1510095087,
    "nbf": 1510095087,
    "sub": "masteruser@acme.com",
    "email": "john.doe@acme.com"
}

Prepare the JWT content for signature

  1. Base-64 encode the header.

  2. Base-64 encode the payload.

  3. Concatenate the base-64 encoded header and payload separated with a ".".

Sign the JWT content

  1. Use the private key to sign the resulting string with RSA, using the SHA-256 hash algorithm.

  2. Base-64 encode the signature.

  3. Concatenate the base-64 encoded header, payload, and signature separated with a ".".

Exchange your JWT for a Nuance generated access token

  1. Use the token endpoint of the Auth server to exchange the JWTClosed (JSON Web Token) key you generated for an access token.

  2. Add the access token as a header in the HTTP request to the User Management API service.