High Level Software Architecture: Authenticated Interactions with OAuth 2.0—Detailed API

Detailed API

Web Interaction Embedded Window API

In this use case, it is the Customer’s Web App responsibility to generate a valid token. The Live Assist Web SDK calls a JavaScript method located on the page, and provides it with a callback function to execute when it has a token as a response to the Live Assist Web Tag, and is able to continue the flow.

The callback method accepts two parameters:

• token - a string token

• error - any value except null or undefined to describe the error that has occurred

  The Customer web page method name can be either the default Live Assist method name (lpGetAuthenticationToken), or any specified name which can be accessed by traversing the global scope on the page.

Code Example

Customer method on the customer page:

<script>
    var lpMethods = {

        lpGetAuthenticationToken: function(callback) {
            log("LP asked for id_token");
            // Do your magic...
            // On Success

            callback(id_token);
            // On Failure
            callback(“”,”error reason”);

} };

</script>

OpenID Connect provider (OP) development details

API Request

• The interface is implemented as REST/JSON. In keeping with the REST specification, the verb is POST, since accessing this API changes the state on the server (is not idempotent).

• Live Assist POSTs the following data using the application/x-www-form-urlencoded format:

  code=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c grant_type=authorization_code
  redirect_uri=https://www.liveassist.com

• The token (JWT) must contain three base64url encoded segments separated by period ('.') characters.

• The following HTTP headers are required: header name: “Authorization”
  The value contains the standard basic authorization header [RFC2617], based on client_id:client_secret provided by the team to identify.

  Example: Authorization:

Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

POST /token HTTP/1.1

Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2F www.liveassist.com%2Fcb

API Response

If the transaction is successful, then the response will be an HTTP 200, and the following payload:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{

"access_token"
"token_type"
"id_token":

: "NotApplicabale",
: "Bearer",

"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MjU1NTUxMjEyIiwiY29uc3VtZXJfdHlwZSI 6ImNvcHBlciIsImlzcyI6Imh0dHBzOi8vd3d3LnQtbW9iaWxlLmNvbSIsImV4cCI6MTQ0NjExNTM1MjAwMCwi aWF0IjoxNDQ2MTExNzUyMDAwfQ.mMERThLDcoW51434sJyOtRUOZZVOVmB_evxTwduJ1Ht1Q78ZZ6ZLqH3tN3 idXI7-Qn7WOwej2OI- 8vsAENB_7gxxpZFUlQ8dCZFM1o7ZJd5gsXvjHbHgIlnRn1zxonZ5L8pIO8TByTNOgwDp847JyGStyzEZTYKky OwxB5p96Z8"

The id_token is a standard JSON web token (see http://jwt.io) [RFC 7519], with the following data:

{
“sub”: “4255551212”,
“iss” : “https://www.YourBrand.com”,
“exp” : 1446115352000,
“iat” : 1446111752000,
extended claims set  - ref: OpenIdConnect token structure
}

The following table describes the response fields:

The id_token is signed using RS256 ALG (see http://jwt.io ) [RFC 7519], and the public key for verifying it is supplied to Live Assist during the configuration stage.

Error Response

If an error is encountered during processing, an error message is returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{    "error": "invalid_code"   }

One of the following errors is returned:

OpenID Token Structure

Live Assist supports the following claims set, which are displayed to the agent after successful authentication.

Mandatory Claim Set:

Standard Claim Set:

Example for Mandatory+Standard Claims JWT:

{
“sub”: “4255551212”,
“iss” : “https://www.example.com”,
“exp” : 1446115352000,
“iat” : 1446111752000,
“preferred_username” : “JohnDoe”,
“phone_number” : “+1-10-344-3765333”
}

Custom Claim:

Custom Claims are added in LP SDE form from the SDEs list (see the Engagement Attributes overview).

Example for Mandatory+Standard+Custom Claims JWT:

Customized claim sets, for example credit card, will be supported in a future version.

OpenID JWT Encryption

• Encryption ensures that only the addressee is able to read it (for example the consumer themself are not able to read the content).

• In order to encrypt the JWT payload, use a public key supplied by Live Assist.

• The key is base64 decoded with X509 key spec.

• The encryption should use the RSA algorithm.

• JWE header should include header name “alg” with the value: RSA_OAEP_256.

OpenID JWT Signing

• Signature proves the authenticity of the issuer.

• The JWT should be signed with your RSA private key.

• The public key should be added to Live Assist OAuth configuration in the JWT Public Key field, and should be base64 encoded with X509 key spec.

Extract JWT Public and Private Keys

1. Generate RSA key:
openssl genrsa -out private_idp.pem 2048

2. Extract private key :
   openssl pkcs8 -topk8 -inform pem -in private_idp.pem -outform pem -nocrypt -out private_key_idp.pem

   (private key can be found in the file: private_key_idp.pem)

3. Extract public key:

   openssl rsa -in private_idp.pem -outform PEM -pubout -out public_key_idp.pem

   (public key can be found in the file : public_key_idp.pem)

Configure the JWT public key on LiveEngage UI:

1. Remove the header and tail ( "-----BEGIN PUBLIC KEY-----" & "-----END PUBLIC KEY-- ---" )

   Example:

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA/lnYC8lHMdEJz74m2WHr K8ndDE3LDto1xZ8HlyOwLWZWkvy71t43zzyMD1cpDfsymv6fSZSfP1NkwF6k9eTW RMYaK0TVivmAXdL4GoO/87XpPiEPn/lxICWL4VTJN/ju1by+h4qVlcpevJic4ZEK 5PXF1vhHqlawPcm/IsWRcYAkFb/Mk84d+i7+OQ7NK0ouqb1T57ijUUGTQEqpzLLo TWZ7wjlWnyteuHx2OtRwskfH/3U7A7GP9STFZDC0yyDh7bj9DSuI4ScQWhmXMRy9 OT/vxvJBf+pNrlNqto+dxNwJtSPKUQ0cnugdiI2mzw40HRtyQxzQONyuttdEMzMX 6wIDAQAB
-----END PUBLIC KEY-----

2. Wrap text of code to be structured as continuous line (remove any new line char). Example:

43zzyMD1cpDfsymv6fSZSfP1NkwF6k9eTWRMYaK0TVivmAXdL4GoO/87XpPiEPn/lxICWL4VTJN/ju1by+h4qVlcpevJic4ZEK
5PXF1vhHqlawPcm/IsWRcYAkFb/Mk84d+i7+OQ7NK0ouqb1T57ijUUGTQEqpzLLoTWZ7wjlWnyteuHx2OtRwskfH/3U7A7GP
9STFZDC0yyDh7bj9DSuI4ScQWhmXMRy9OT/vxvJBf+pNrlNqto+dxNwJtSPKUQ0cnugdiI2mzw40HRtyQxzQONyuttdEMzMX
6wIDAQAB

3. Paste the public key into Consumer Identity Provider set up: 

Impact on Existing Functionality