The Rublon PHP SDK library is a client-side implementation of the Rublon authentication service written in PHP, including methods for embedding the service's GUI in a HTML-based environment. It forms a convenient PHP coding language facade for the service's REST interface.
Rublon provides an additional secury layer:
To be able to perform an additional authentication using Rublon, the user must first be authenticated in a different way, e.g. with a username and password. It is a necessary step, because upon Rublon's initialization the service must receive certain information about the user:
To experience the full measure of two-factor authentication, the end-user should install the Rublon mobile app, available on all leading smartphone systems. However, having those with older phone devices in mind or those who do not want to install any additional apps on their phones, we prepared a Email2FA process, which does not require using an additional device of any kind.
User protection is active, when a user's email address in the integrated system can be matched to a user in the Rublon service. For this purpose, the user's email is sent to Rublon servers.
If the library finds an active user protection, a URL address pointing to Rublon servers will be generated. The user's web browser must be then redirected to that URL in order to carry out the identity confirmation.
If the web browser is the user's Trusted Device, the authentication will be performed automatically and invisibly. Otherwise, the user will be asked to verify his account in one of the following ways:
After a successful authentication, the web browser will be redirected to a callback URL address, which points to the integrated system servers. The integrated system should intercept that URL, retrieve its params and finalize the authentication using this library.
To start using the Rublon PHP SDK library you should:
In the following examples we assume the existence of the superglobal session
associative array $_SESSION, which has access to an object storing the currently logged
in user data.
The Rublon class implements a few public methods, which, when needed,
can be overriden with inheritance.
We strongly discourage you from modifying any part of the library, as it usually
leads to difficulties during future library updates. If you need to change the flow
or internal structure of the Rublon or RublonCallback
classes, don't hesitate to subclass them according to your needs.
To initialize the library you need to instantiate a Rublon class object.
Its constructor takes three arguments.
| Name | Type | Description |
|---|---|---|
$systemToken |
string | System token |
$secretKey |
string | Secret key |
$apiServer |
string | Rublon API Server URI |
An example of the library's initialization in PHP:
require_once "libs/Rublon/Rublon.php";
$rublon = new Rublon(
"A69FC450848B4B94A040416DC4421523",
"bLS6NDP7pGjg346S4IHqTHgQQjjSLw3CyApvz5iRjYzgIPN4e9EOi1cQJLrTlvLoHY8zeqg4ILrItYidKJ6JjEUZaA6pR1tZMwSZ",
"https://core.rublon.net"
);
Rublon protects users during their signing in processes. Even if a someone lears the user's password with malicious intent, such a person would be unable to log in to the user's account, because a physical access to the Rublon mobile app (installed in the user's smartphone) or to his email account is needed.
Administrator can force users to authenticate using the mobile app (to avoid the Email2FA process).
Authenticating a user with the second factor should be initiated, when the user has successfully passed the first factor of authentication (e.g. the valid user credentials have been provided) and the user's unique Id and email address are known.
The Rublon::auth() method will check the user's protection status (using
the email address) and return a URL address for the web browser to be redirected to
(if user protection is active).
| Name | Type | Description |
|---|---|---|
$callbackUrl |
string | The integrated system's callback URL |
$appUserId |
string | The integrated system's user's unique ID, which will allow to log in the user upon successful authentication |
$userEmail |
string | The user's email address in the integrated system, which will allow to check the user's protection status and match the user to a Rublon account |
$consumerParams |
array | Additional transaction parameters (optional) |
$isPasswordless |
boolean | Information if it is a login attempt using passwordless method (optional) |
An example of logging in a user on an integrated system:
/**
* An example method used to log the user in (integrated system's method)
*
* @param string $login
* @param string $password
*/
function login($login, $password) {
if (loginPreListener()) {
if ($user = authenticate($login, $password)) {
// The user has been authenticated.
$_SESSION["user"] = $user;
loginPostListener();
}
}
}
/**
* Listener (hook) invoked after a successful first factor user authentication,
* implemented for Rublon integration purposes.
*/
function loginPostListener() {
// Make sure that the user is not logged-in
unset($_SESSION['user']);
$rublon = new Rublon(
"A69FC450848B4B94A040416DC4421523",
"bLS6NDP7pGjg346S4IHqTHgQQjjSLw3CyApvz5iRjYzgIPN4e9EOi1cQJLrTlvLoHY8zeqg4ILrItYidKJ6JjEUZaA6pR1tZMwSZ",
"https://core.rublon.net"
);
try { // Initiate a Rublon authentication transaction
$url = $rublon->auth(
$callbackUrl = "http://example.com?rublon=callback",
$_SESSION["user"]["id"], // App User ID
$_SESSION["user"]["email"] // User email
);
if (!empty($url)) { // User protection is active
// Redirect the user's web browser to Rublon servers to verify the protection:
header('Location: ' . $url);
} else {
// User is not protected by Rublon, so bypass the second factor.
header('Location: index.php');
}
} catch (UserBypassedException $e) {
// User bypassed
header('Location: ./');
} catch (RublonException $e) {
// An error occurred
die($e->getMessage());
}
}
If the user's account is protected by Rublon, calling the Rublon::auth()
method will return a URL address pointing to Rublon servers, which the user's
browser should redirect to in order to verify a Trusted Device and user identity by using Rublon mobile app or his
email.
Because the user's web browser will be redirected to Rublon servers in order to confirm the user's identity, the user should be logged out (if he/she was logged in before) to prevent creating a user session. Otherwise Rublon will not protect the user effectively, because returning to the integrated system before a proper Rublon authentication is performed may grant the user access to an active logged in session in the system. The user should be logged in only after a successful Rublon authentication.
After a successful authentication, Rublon will redirect the user's browser to the callback URL. The callback flow continues the authentication process, i.e. the finalization of the authentication (logging in or identity confirmation).
The callback URL will receive its input arguments in the URL address itself (query string).
| Name | Type | Description |
|---|---|---|
state |
string | Authentication result: ok, error or logout |
token |
string | Access token (60 alphanumeric characters, upper- and lowercase), which allows authentication's verification using a background Rublon API connection |
http://example.com/auth,
the params will be appended to the URL address:
http://example.com/auth?state=ok&token=Kmad4hAS...d%token% and %state%, like so:http://example.com/auth/%state%/%token%After the callback is invoked, for proper finalization of the authentication
process you need to instantiate a RublonCallback class object.
| Name | Type | Description |
|---|---|---|
$rublon |
Rublon | An instance of the Rublon class. |
Next, the RublonCallback::call() method should be called. It takes two arguments:
| Name | Type | Description |
|---|---|---|
$successHandler |
callable | Name of a function/method, or an anonymous function/closure, which will be invoked on successful verification of the process, finalizing the authentication (logging the user in or confirming the user's identity for some operation). |
$cancelHandler |
callable | Name of a function/method, or an anonymous function/closure, which will be invoked on cancel RublonCallback:call()
method to cancel the authentication transaction.
|
| Name | Type | Description |
|---|---|---|
$appUserId |
string | The user's unique ID in the integrated system, given as an argument to the Rublon::auth()
method,
whose authentication is being confirmed by Rublon
|
$callback |
RublonCallback | An instance of the RublonCallback class |
| Name | Type | Description |
|---|---|---|
$callback |
RublonCallback | An instance of the RublonCallback class |
An example of the RublonCallback class usage in the callback:
$rublon = new Rublon(
"A69FC450848B4B94A040416DC4421523",
"bLS6NDP7pGjg346S4IHqTHgQQjjSLw3CyApvz5iRjYzgIPN4e9EOi1cQJLrTlvLoHY8zeqg4ILrItYidKJ6JjEUZaA6pR1tZMwSZ",
"https://code.rublon.net"
);
try {
$callback = new RublonCallback($rublon);
$callback->call(
$successHandler = function($appUserId, RublonCallback $callback) {
// The user is finally logged in
$_SESSION["user"] = $appUserId;
},
$cancelHandler = function(RublonCallback $callback) {
// Cancel the authentication process
header("Location: ./login");
exit;
}
);
// The authentication process was successful, redirect to the main page:
header("Location: ./");
exit;
} catch (RublonException $e) {
// Please handle this error in the better way
die($e->getMessage());
}
For users of an integrated system who do not possess a Rublon account (they do not want to sign up or don't own a smartphone), Rublon provides a simplified form of two-factor identity verification. This feature employs an email message with an identity confirmation link sent to the email address of the user being authenticated, assuming that no one but that user has access to his/her email inbox.
This feature is enabled by default. However developer can force users to authenticate using the mobile app, to avoid the Email2FA process, which can increase the security.
The use of Email2FA is by default active and looks the same as the Signing in process.
Passwordless Login is a way to integrate Rublon, which allows users to log into their accounts without login and password, only by scanning QR code with the Rublon App installed on a user smartphone.
First version of the README document.