Close

Authentication

A JWE token is used for mutual authentication between a third-party service server and LG Commercial Laundry Server. This token follows JSON Web Encryption (RFC7516, RFC7519) standard. For encryption, the following algorithm is used.

  • Claim encryption: A256CBC-HS512
  • Random key encryption: RSA-OAEP-256

Basics

The basic authentication flow is as follows:

  1. At every API request, a requester server generates a JWE token in which the authentication data has been encrypted according to the agreed-upon encryption algorithm.
  2. The requester server includes the JWE token in the authorization bearer header of HTTPS and delivers it to the provider server.
  3. The provider server decrypts the authentication data obtained from the JWE token according to the agreed-upon encryption algorithm.
  4. The provider server processes the request only when the authentication data is valid.

Overall Flow

The following figure describes the overall authentication flow when a third-party service server calls the API of LG Commercial Laundry Server.

  • Requester server: Third-party service server
  • Provider server: LG Commercial Laundry Server

Brief architecture of the authentication flow

01. Generates a JWE token.

A JWE token is generated according to JSON Web Encryption RFC7516 standard. The token contains an encrypted claim (authentication data) and an encrypted random key. 

Claim  

It refers to the data necessary for authentication and is described as a name/value pair as follows:

{
  "iss" : "{{Third Party Service Server Domain Name}}", # token issuer
  "sub" : "/device", # token name (replaced with api url)
  "aud" : "{{Commercial Laundry Service Server Domain Name}}",# token receiver
  "exp" : 1480849147370, # token expiration time
  "iat" : 1480849147200 # token generation time
}

Encryption Algorithm

Claim encryption  

The claim (authentication data) is encrypted via the symmetric key method A256CBC-HS512. For every API call, the requester server generates a random key first, and uses this random key to encrypt the claim. 

Random key encryption

A random key is a symmetrical key used for claim encryption. The requester server uses an asymmetrical key method RSA-OAEP-256 to encrypt the random key. A public key used for this encryption is issued by the provider server.

02. Delivers the JWE token.

The requester server includes the JWE token in the authorization bearer header of HTTPS and delivers it to the provider server. For example, if the provider server is LG Commercial Laundry Server (if the partner server calls the API of LG Commercial Laundry Server), the JWE token is delivered as follows:

LG Commercial Laundry Server API - Common Header - Authorization

Content-Type: application/x-www-form-urlencoded
x-service-id: abab90a800033addb66821d4
x-service-key: abababababJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI3YmRhOTBhODAwMDMzYWRkYjY2ODIxZDQiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTYwNzMyMDA5Mn0.qj6wTknmFeiuYSFMd8nkXf7AvetBL0Qxqnv48CMPfrU
x-api-key: abababababababababbababbabbababababababxBp5
x-country-code: KR
x-service-phase: QA
x-thinq-client-type: SERVER

Authorization: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoiVEdYWExXcmQ0bG42bnhubEZ5OVFlVnZPMTlCTkd2dmNqSDlJU3VWVVpkUSIsInR5cCI6IkpXRSJ9.hfBRxEHwG0Xeutr51zXyxHWpqzvhu3xepLdsxM96mM9bQKkazuQgHQVOcRWLAS-A0aFXjyzOWW7GtWLT_oOJBiYUoVQ-i3xxKABAE5TijPjvnkM3kXB7J6knLw1Wh4xxFbl8AuIynNMMfrRZUFvPVLPFn2DRw4f6pE2-upg1tYBO77YNDDXPUQPP3yMEihS2e2VYI-cKiBpgQaK0YvHHn1jBPJy-5ND0O0KXj8rSCTC0LaJkUsmLCVZoelUrOHZtMzRqg-s5YtQ0Ju8JtzFuejfDoNdEll3d7ThfJ0KXHyyDOBeQWF-j6Y7NJ9_AOTjk9RpLX18T1tPO5KWcpb1Okw.F93UfH9k8ILKAMuGnt64ew.0SFDOmtZS6LaFcREXfjWqLOUYQ9F15Ey9xANrLTW6cWoo9noLkXHEcPQvgVX-yRAIaaPEODylhDBYy4d-0i1JRMiRrKxKxtzS4Fzn9DJPm73L1KY_24EdbQXkBDpeTML03_I3oKA8z5b9NAfVg653lunhJIK5leHCFkib4wgLUw.SSZIIg8mNJgK8-EG4meo9JqbXC7dQV3hE8zIcc52BZ8

03. Decrypts the JWE token.

The provider server decrypts the JWE token according to the following sequence.

  1. The provider server decrypts the random key according to the RSA-OAEP-256 algorithm. For decryption, the provider server uses a private key that it possesses.
  2. The provider server uses the decrypted random key as a symmetrical key to decrypt the claim (authentication data) according to the A256CBC-HS512 algorithm.

04. Processes the request.

The provider server processes the request only when the decrypted claim (authentication data) is valid.

When a Third-party Service Server Requests

The detiled flow when a third-party service server calls the API of LG Commercial Laundry Server is as follows:
•    Requester server: Third-party service server (Partner Server)
•    Provider server: LG Commercial Laundry Server
 

Sequence diagram when partner server calls LG commercial laundry API

 

 

When LG Commercial Laundry Server Requests 

The detailed authentication flow when LG Commercial Laundry Server calls the API of a third-party service server is as follows:

  • Requester server: LG Commercial Laundry Server
  • Provider server: Third-party service server

Sequence diagram when calling partner server's API from LG server