Web Socket Communication Protocol

PowerAuth 2.0 WebAuth Server uses Web Sockets for communication between the user interface and the WebAuth backend. This chapter describes the communication protocol.

Introduction

WebAuth server uses Web Sockets for two-way communication between UI frontend and backend. The UI usually sends user input and the backend sends back responses or asynchronous requests to the UI to do actions such as showing different messages, forms, and performing redirects. Web Sockets are used to provide better responsiveness over polling, when available. All messages use the JSON format.

Registration of new Web Socket client

Each web socket client needs to register to initiate communication with the WebAuth server using Web Sockets. The server responds with a sessionId which is used in all future communication with this client until communication is terminated. In case the sessionId is not recognized by either the client or the server, or the state of this session is not active, the message is discarded.

CLIENT => SERVER

{
    "action": "REGISTER"
}

Direct response to client request:

SERVER => CLIENT

{
    "action": "REGISTRATION_CONFIRM",
    "sessionId": "12345678"
}

Messages for user authentication

Server asks the client to display the login form

This action is called when the authentication is required.

SERVER => CLIENT

{
    "action": "DISPLAY_LOGIN_FORM",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239",
    "showCaptcha: "false"
}

The client displays the login form and waits for user input. Captcha is optional.

User fills in the login form and clicks "Log In"

CLIENT => SERVER

{
    "action": "LOGIN_CONFIRM",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239",
    "method": "BASE64",
    "credentials": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

The credentials value is a string - a username and password separated by colon (same format as in HTTP Basic authentication). This value is base64encoded to ensure special characters are transferred properly via web sockets.

User cancels the login form

CLIENT => SERVER

{
    "action": "LOGIN_CANCEL",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239"
}

The server handles the canceled login state.

Messages for payments

Server asks the client to display the payment information form

This action is called when the payment is initialized.

SERVER => CLIENT:

{
    "action": "DISPLAY_PAYMENT_INFO",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239",
    "amount": "100",
    "currency": "CZK"
}

The client displays the payment details and waits for user to confirm the payment.

User confirms the payment

CLIENT => SERVER

{
    "action": "PAYMENT_CONFIRM",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239",
}

The server processes the payment confirmation.

User cancels the payment

CLIENT => SERVER

{
    "action": "PAYMENT_CANCEL",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239"
}

The server processes the payment cancelation.

Server asks the client to display the payment authorization form

This action is called when the payment authorization is required.

SERVER => CLIENT

{
    "action": "DISPLAY_PAYMENT_AUTHORIZATION_FROM",
    "sessionid": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239"
}

The client displays the payment authorization form and waits for user input.

User fills in the payment authorization form and clicks "Authorize"

CLIENT => SERVER

{
    "action": "PAYMENT_AUTHORIZATION_CONFIRM",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239",
    "authorizationCode": "54873215"
}

The server processes the authorization message from the client.

User cancels the payment authorization

CLIENT => SERVER

{
    "action": "PAYMENT_AUTHORIZATION_CANCEL",
    "sessionId": "12345678",
    "operationId": "40269145-d91f-4579-badd-c57fa1133239"
}

The server processes the cancel authorization message from the client.

General communication - messages and redirects

Server asks the client to show a message

This action is called when a message needs to be displayed to the user. This message is used to display both information and error messages to the client.

SERVER => CLIENT

{
    "action": "SHOW_MESSAGE",
    "sessionId": "12345678",
    "messageType": "information",
    "message": "Payment was authorized, redirecting..."
}

Similarly for error messages the server would send following message:

SERVER => CLIENT

{
    "action": "SHOW_MESSAGE",
    "sessionId": "12345678",
    "messageType": "error",
    "message": "Transaction was rejected."
}

Server asks the client to close the communication channel

This message is sent to terminate the communication without a redirect (the last message remains displayed, usually an error in this case).

SERVER => CLIENT

{
    "action": "CLOSE",
    "sessionId": "12345678"
}

Server asks the client to close the communication channel and proceed with a redirect

This message is sent to terminate the communication with a redirect to an external URL.

SERVER => CLIENT

{
    "action": "CLOSE_REDIRECT",
    "sessionId": "12345678",
    "redirectUrl": "https://...",
    "delay": 5
}

The delay parameter specifies how many seconds to wait before performing the redirect (unless user clicks the redirect link).