Push Protocol – Challenge/Response & Registration Redux

Overview

Push authentication depends on the secure verification of information sent from the server to the client, and from the client to the server. This lets the server verify that the notification was received by the original device, and for the device to verify that only the server sent the original request.
This approach is achieved by a combination of communication channels:

  • QR Code over HTTPS: Required for setup of the account on the user’s device. This allows an out-of-band setup of the device, and is of a sufficient security level for the goal of push authentication
  • Amazon Simple Notification Service: Used for delivering push messages to clients, which will trigger the authentication flow.

The high-level flow of operations is best summarized with the following diagram:

Registration

Registration is the process of registering the user’s phone with their account, so they can use it for push authentication-based login.

The flows described below assume an inline registration is being performed; that is, the user completes authentication using a conventional authentication chain, and within that, starts the registration process for the phone:

Authentication

The authentication flow assumes that both server and client have been preconfigured with the secret, and that the communication link between the server and the client has been established:

Data Contents

REG0 : Message sent from server to device via QR code

Format: URL-encoded within QR code
Scheme: pushauth://push.forgerock:<username>/?params

Where <username> is defined as:

The name of the account to display to the user on the phone’s app, usually the user-facing username of the account.

Where params are defined as:

Where loadbalancer is defined as:

Base64Url(loadbalancerName + “=” + loadbalancerValue)
The client should Base64Url-decode the string value as its cookie.

REG1 : Message sent from device to server in response to REG0

Format: JSON data payload , sent over HTTPS POST to the endpoint defined as the registration endpoint taken from REG0.

Where payload is defined as:

Where claims are defined as:

AUTH0 : Message sent from server to device via push

Format: Json data payload

Where payload is defined as below:

Signed JWT, with claims:

Where loadbalancer is defined as:
Base64(loadbalancerName + “=” + loadbalancerValue)

The client should first Base64-decode the string, and finally, use the value presented.

AUTH1 : Message sent from device to server in response to AUTH0

Format: JSON data payload , sent over HTTPS POST to the endpoint defined as the authentication endpoint taken from REG0.

Where payload is defined as:

Signed JWT, with claims: