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: /? 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 :
Helpful Links
- Download and install the ForgeRock Authenticator app
- AM 7.2.0 > Push Notification service
- AM 7.2.0 > Authentication and SSO > MFA: Push authentication
- AM 7.2.0 > Authentication and SSO > Manage devices for MFA