JSON Web Token (JWT) is a compact token format that lets you authorize yourself. A JWT has the username and the expiration period for the token and is passed by your client application to the Oracle Fusion Cloud Applications.
- Suppose you are using single sign to login to Oracle SaaS, but at the same time Rest API’s or SOAP API’s which are being used to integrate Oracle fusion with third party system will need to have some authentication (not SSO).
- To Authenticate you may choose Basic Authentication which is using user and password and this approach comes with risk i.e.
- With user and password, Rest API can be used by any other device and data can be download to any non-trusted application or system.
- The Risk of password hack.
- User password management.
Why JWT authentication?
- So other than Basic authentication, another option to make it secure is using LBAC i.e. Location based access control which means Oracle fusion can be accessed only via some IP range, but since Oracle SaaS is a cloud product your business may want to access it from anywhere in the world without a VPN
- To avoid all above issues, one approach which can be used is using JWT authentication for your Rest or Soap API’s
- Application created on paas can integrate to consume Rest API from Oracle cloud using JWT token which can be passed as Header
- With this approach you will generate a token which will have details in encoded format like user_name (for which it is trying to authenticate), generation time, expiration time etc.
JWT Token Details
As can be seen JWT token is an encoded string which consist of 3 parts
- Header – Identifies which algorithm used to generate the signature
- Payload – Contain set of claims like name, prn, usr, iat which provide details like this token is used for which user, when it was issued, what is the expiration time
- Signature – The tokens are signed either using a private secret or a public/private key.
In a nutshell, how do we configure the JWT Authentication?
Steps to enable JWT Token
Pair of private key and public certificate of application trying to establish a connection with Oracle fusion
1) Create X509 key pair (private key and corresponding certificate)
- a) Generate private key: openssl genrsa -out private.key 1024
- b) Using the created private key, create an X509 certificate (.cer file) containing your public key
Using the created private key, create an X509 certificate (.cer file) containing your public key
2) Upload certificate in Oracle fusion created in Step 1(Before 20D, for this we had to raise SR with oracle, after 20D, you can manage client certificate by following below steps)
2.1) Navigate to Tools >> Security Console >>API Authentication
2.2) Edit >>Token type as JWT
Trusted Issuer = ‘Free text field, this is to define name of third-party system which is trying to access Oracle fusion’
2.3) Save and close
2.4) Select the Inbound API Authentication Public Certificates as highlighted
2.5) Add new certificate, browse.cer file which was received from third party (who would have generated this in step1)
2.6) Give certificate alias and click done
3) Generate JWT token
Now, since we have created X.509 key pair and uploaded corresponding public.cer in oracle fusion, it is time to generate a token.
Which consists of a Header, Payload and and Signature
“x5t”: ” cfctAG1vSl82cRAk+PD9M4ltxeuSAA8=“
The header consists of three parts:
- The signing algorithm being used, such as HMAC SHA256 or RSA
- The token type, which is JWT
- The x5t which is the base64 encoded fingerprint of the trusted issuer cert. (Sourced from your newly created X509 key pair)
The x5t value is derived from the publickey.cer and can be viewed in a certificate viewer or output by running the following openssl command.
openssl x509 -sha1 -in publickey.cer -noout –fingerprint
Oracle HCM has the requirement for the following fields and values.
|iss||Issuer||Should be same as truster issuer in cer file and name mention while uploading in fusion|
|prn||Principal||The username of user that has the Fusion Applications Integration privilege (in this example ‘fusion_userA’)|
|iat||Issued At||Unix epoch time format of when the token was generated e.g ‘1596271154’ for 08/01/2020 @ 8:39am (UTC)|
|exp||Expiration||Unix epoch time format of when the token will expire e.g ‘1918081154’ for 10/13/2030 @ 12:19am (UTC)|
3.3) Generate the Verify Signature
The signature is created by encoding the encoded header, the encoded payload, a secret, the algorithm specified in the header, and then sign.
As can be seen in the image, it is combination of header, payload, and combination of public and private key.
Decoding the JWT
- Using JSON Web Tokens – jwt.io you can see the decoded value of JWT token generated or you can encode the JWT
Test and Confirm
Once JWT token is generated, test it against any user to authenticate REST or SOAP API
Add a Header: ‘Authorization’
Value: Bearer ‘token’, for e.g.
JWT authentication is a widely used technology and used for API authentication. It is a trusted authentication standards ensures secured exchange of information between servers to avoid any basic vulnerability issues.