Skip Navigation
Expand
Using JWT assertion to authenticate "Start a new chat" API method
Answer ID 12123   |   Last Review Date 03/18/2022

How can I authenticate "Start a new chat" API method?

Environment:

All versions of Oracle Field Service (OFS)

Issue:

I can not find the correct way to authenticate API calls for method "Start a new chat", despite configuring Field Collaboration API access.

Resolution:

The "Start a new chat" API method requires authentication using JWT assertion and does not work with either OFS token or Basic authentication.

To be able to authenticate this, you must prepare your instance and API client with the proper details.

 
 

Pre-requisites:

• You need a public certificate, which can be either self-signed or root certificate signed by a Certificate Authority (CA). For the purpose of this example, we will be using a self-signed certificate, generated with openssl.
 
• Along with the self-signed certificate, you will have generated a private key. For using this certificate in the respective step, the key must be unencrypted.
 
• You will also need a JWT assertion generation tool. Popular online tools are JWT.io or Token.dev
 
• To generate expiration time, you must use timestamps in epoch time so a converter is needed. For the purpose of this example, we will be using epochconverter.com/

 

 

Steps:

Click the plus sign next to the appropriate heading below to expand that section for viewing.

1. Generate a self-signed certificate and unencrypt the private key

a. Generate a self-signed certificate with openssl tool. You may use command "openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365".

b. Unencrypt the private key (key.pem) generated above, so it can be further used. You may use command "openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in key.pem -out private.pem".

You now have 2 self-signed keys: cert.pem and private.pem

2. OFS-side configuration

a. Go to OFS instance, into Configuration > Application > Your application, then enable "Authenticate using JWT assertion" and Upload "cert.pem" public certificate. Hit Save.

b. Click on "Assertion token example" and take note of the header and payload.

You now have completed the OFS-side configuration.

3. Obtain an encoded token

a. Go to epochconverter.com and obtain a time in the future in epoch format. For the sake of this example, you can use 1704067199 which translated to Dec 31st 2023, 23:59:59 UTC.

b. Go to JWT.io or Token.dev and paste the header and the payload into the respective fields. You will have to change <your user> with the user's login which must initiate the chat and <expiration timestamp> with the epoch time obtained above.

c. Open cert.pem and private.pem in any text editor, then copy paste their contents into their respective fields in JWT.io or Token.dev

Once you have performed these steps, you should have obtained an encoded token.

4. Make a POST call in the API client

a. Open your API client, say Postman, and make a POST call to https://{{Instance}}.fs.ocs.oraclecloud.com/rest/oauthTokenService/v2/token The authentication can be basic client_id@instance:client_secret, using the client_id of the application which you set the JWT authentication for. Body must be x-www-form-urlencoded and add the following parameters: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer assertion=<insert the encoded token here>

b. Above step should have obtained you an "access_token". You can go ahead now and make a POST call to https://{{Instance}}.fs.ocs.oraclecloud.com/rest/ofscCollaboration/v1/chats

The authentication must be "Bearer Token" and the token will be the "access_token" obtained above. Body of the request must contain the text message and the recipients which will receive the chat. 

Please make sure that the user's login which initiates the chat (step 3b) has appropriate access to start a chat with the recipients, otherwise the API will fail.