Rublon

Secure Remote Access

By

Last updated on June 2, 2025

This document provides guidance on using the Rublon REST API to enable multi-factor authentication (MFA) for custom applications created and developed in your organization. The custom application can be either capable of displaying a web GUI (in which case it would support the Rublon Prompt) or operate as a promptless application. This documentation outlines the steps required to initiate transactions, handle authentication methods, and complete transactions securely for both of these application types.

Overview

The Rublon REST API enables you to integrate multi-factor authentication (MFA) into your applications seamlessly. Depending on whether your application supports the Rublon Prompt with a callback URL or operates without it (promptless), the API endpoints and transaction flows vary slightly.

This documentation provides detailed instructions for both application types, ensuring secure and efficient MFA implementation.

IMPORTANT: Using the Rublon SDK

If available for your programming language, use the Rublon SDK instead to simplify integration:

IMPORTANT: Application Type Configuration

Ensure that your application’s type is correctly configured in the Rublon Admin Console. The application type affects API behavior, and incorrect settings may lead to errors or unexpected behavior. Set the application type to:

IMPORTANT: Error Handling

  • Exception Handling: Handle exceptions based on the exception name and error code, not the errorMessage.
  • User Messages: Display the errorMessage from the API to users when appropriate, ensuring consistency with Rublon MFA’s messaging.

IMPORTANT: X-Rublon-Signature Header

For security purposes, every request to the Rublon API must include the X-Rublon-Signature header. This header contains an HMAC SHA-256 hash of the request body encrypted with your application’s secret key.

Generating the Signature:

  1. Prepare the Request Body: Obtain the JSON string of the request body.
  2. Compute the HMAC Hash: Use the HMAC SHA-256 algorithm with your application’s secret key to hash the JSON string.
  3. Include the Header: Set the X-Rublon-Signature header to the resulting hash.

Important: If the X-Rublon-Signature header is missing or invalid, the API will respond with an InvalidSignatureException.

Transaction Process for Applications That Support Rublon Prompt

This section describes the transaction process for applications that support web GUI (and thus support the Rublon Prompt).

Initializing a Transaction

Endpoint:

POST /api/transaction/init HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "[Your System Token]",
  "username": "user_identifier",
  "callbackUrl": "https://yourapp.com/callback",
  "params": {
    "appVer": "4.0.2",
    "hostName": "Optional Hostname",
    "logoutUrl": "https://yourapp.com/login",
    "os": "Optional OS Information",
    "userPhone": "+1234567890"
  },
  "userEmail": "user@example.com"
}
  • systemToken: Your application’s unique system token.
  • username: Identifier of the user attempting to authenticate.
  • callbackUrl: The URL to redirect the user after MFA completion.
  • params: Optional parameters providing additional context.
    • appVer: version of the connector (your custom application)
    • hostName: hostname of the client’s device
    • logoutUrl: URL to your application’s logout page or login form
    • os: operating system information of the client
    • userPhone: user’s phone number
  • userEmail: Optional user email address.

Response (MFA Required):

If the connector received a webURI, it should redirect the page to this address to continue MFA

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/process/[Transaction ID]"
  }
}

Response (Bypass MFA):

In this case, you should let the user into the application without MFA and display the message contained in result.errorMessage.

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "UserBypassedException",
    "code": 45,
    "errorMessage": "User bypassed",
    "details": null
  }
}

Response (Access Denied):

In this case, the user should NOT be allowed into the application. Redirect the page to the webURI address, where the user will see the message “Access Denied!”.

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/deny/[Transaction ID]"
  }
}

Response (Awaiting Admin Approval):

Redirect the user to the webURI with a message like “Your account must be approved. Please wait until an administrator accepts your login request.”

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/deny/[Transaction ID]"
  }
}

Completing the Transaction

After the user completes MFA, they will be redirected to your callbackUrl with the parameters:

https://yourapp.com/callback?rublonState=ok&rublonToken=[Access Token]
  • rublonToken: Access token required to finalize the transaction.

Endpoint:

POST /api/transaction/credentials HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Access Token from rublonToken]"
}

Response:

{
	"status": "OK",
	"result": {
		"systemToken": "F950953E5454435B9A59E3125F9E7879",
		"email": "bob@rublon.com",
		"username": "user-identifier",
	}
}

The user can now be logged in to the application.

Transaction Process for Applications That Do Not Support Rublon Prompt

This section describes the transaction process for promptless applications (applications that do not support the Rublon Prompt).

Initializing a Transaction

Endpoint:

POST /api/transaction/init HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "F950953E5454435B9A59E3125F9E7879",
  "username": "bob",
  "params": {
    "appVer": "4.0.2",
    "hostName": "22-88-AB",
    "os": "Windows-10-10.0.20348-SP0",
    "userIP": "127.19.3.124",
    "userPhone": "+48666777888"
  },
  "userEmail": "bob@rublon.com"
}
  • appVer: version of the connector (your custom application)
  • userIP: public IP address of the client
  • userPhone: optional, if it was fetched from Active Directory
  • userEmail: optional, if it was fetched from Active Directory

Response (MFA Required):

Challenge the user for MFA.

{
  "status": "OK",
  "result": {
    "methods": [
      "email",
      "totp",
      "qrcode",
      "phoneCall",
      "push",
      "sms",
      "smsLink",
      "webauthn",
      "yotp"
    ],
    "tid": "CCF19A8CE2D1406586278D961AB620F2",
    "status": "pending",
    "companyName": "Rublon",
    "applicationName": "Demo"
  }
}
  • methods: Available authentication methods for the user.
  • tid: Transaction identifier.
  • status: transaction status

Response (Bypass MFA):

In this case, you should let the user into the application without MFA and display the message contained in result.errorMessage.

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "UserBypassedException",
		"code": 45,
		"errorMessage": "User bypassed",
		"details": null
	}
}

Response (Access Denied):

In this case, the user should NOT be allowed into the application. Display the message “Access Denied!”.

{
	"status": "OK",
	"result": {
		"methods": [],
		"tid": "CCF19A8CE2D1406586278D961AB620F2",
		"status": "denied",
		"companyName": "Rublon",
		"applicationName": "Demo"
	}
}

Response (Awaiting Admin Approval):

Inform the user that their account is pending approval.

{
  "status": "OK",
  "result": {
    "methods": [],
    "tid": "CCF19A8CE2D1406586278D961AB620F2",
    "status": "waiting",
    "companyName": "Rublon",
    "applicationName": "Demo",
    "webURI": "https://core.rublon.net/api/user/enrollment/114de367d58e706aba1030f6cc5615fca162323129d33f2a00479b0a1a6e"
  }
}

Selecting an Authentication Method

Prompt the user to select one of the available authentication methods from the methods array.

Endpoint:

POST /api/transaction/methodSSH HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "F950953E5454435B9A59E3125F9E7879",
  "tid": "CCF19A8CE2D1406586278D961AB620F2",
  "method": "email"
}
  • tid: transaction ID taken from the response to the transaction init
  • method: the authentication method selected by the user

Available Authentication Methods:

Response:

{
  "status": "OK",
  "result": {
    "action": "authentication",
    "method": "email",
    "tid": "CCF19A8CE2D1406586278D961AB620F2",
    "qrText": "994a113db56f39cbc177cd84d1d1410896359a096bcff23dbea1d487bdf7",
    "vericodeLength": 6,
    "phoneNumber": "********7888",
    "token": "b9a1757f987a77237672d0fd4716fb30119fc0c7a73dccd51d1527dcbfab"
  }
}
  • qrText: when the user selects the QR Code authentication method; display this to the user
  • vericodeLength: when the user selects the SMS Passcode or Passcode authentication method
  • phoneNumber: when the user selects the SMS Passcode, SMS Link, or Phone Call authentication method
  • token: when the user selects the YubiKey OTP authentication method; required for another request

After receiving the response to this query, you should establish a connection with Socket.IO (https://core.rublon.net/ws/socket.io).

Confirming Identity

Based on the selected method, follow the appropriate steps:

Email Link

Process:

  • The user receives an email with a confirmation link.
  • Upon clicking the link, the API emits a TransactionConfirmedEvent.

Action:

Listen for the event via WebSockets to proceed

Passcode (TOTP & Bypass Code)

Process:

The user enters the passcode.

Endpoint:

POST /api/transaction/confirmCode HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "[Your System Token]",
  "tid": "[Transaction ID]",
  "vericode": "[User's Passcode]"
}

Response (Success):

Listen for the TransactionConfirmedEvent. The event contains a token attribute (containing the transaction access token), which will be required to perform the next REST query.

{
  "status": "OK",
  "result": true
}

Response (Invalid Code):

Prompt the user to retry.

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "PasscodeException",
    "code": 18,
    "errorMessage": "Hmm, that's not the right code. Try again.",
    "details": null
  }
}

QR Code

Process:

  • Display the QR code using qrText.
  • The user scans it with the Rublon Authenticator app.

Action:

Listen for the TransactionConfirmedEvent.

Mobile Push

Process:

  • The user receives a push notification.
  • Upon approval, the API emits a TransactionConfirmedEvent.
  • If denied, a TransactionDeniedEvent is emitted.

Action:

Listen for events to proceed accordingly.

SMS Passcode

Process:

  • The user receives a passcode via SMS.
  • Follow the same steps as the Passcode method.

SMS Link

Process:

  • The user receives an SMS with a confirmation link.

Action:

Listen for the TransactionConfirmedEvent after the user clicks the link.

YubiKey OTP Security Key

Process:

  • The user touches the YubiKey to input an OTP.

Endpoint:

POST /api/transaction/confirmSecurityKeySSH HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Token from methodSSH response]",
  "otp": "[User's YubiKey OTP]"
}

Response (Success):

{
  "status": "OK"
}

Action:

Listen for the TransactionConfirmedEvent.

WebAuthn/U2F Security Key

Not supported for promptless applications. Do not present this option to the user.

Phone Call

Process:

  • The user receives a phone call with voice instructions.
  • To confirm their identity, the user presses any numeric key on their phone’s keypad during the call.
  • After completing this action, the API emits a TransactionConfirmedEvent.

Action:

Listen for the TransactionConfirmedEvent to proceed with the transaction.

Note:

The event contains a token attribute (the access token of the transaction), which is required for the next REST request.

Completing the Transaction

After receiving the TransactionConfirmedEvent, finalize the transaction.

Endpoint:

POST /api/transaction/credentials HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Request Body:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Access Token from TransactionConfirmedEvent]"
}

Response:

{
  "status": "OK",
  "result": {
    "username": "user_identifier",
    "email": "user@example.com",
    "consumerParams": null
  }
}

Action:

Log the user into your application.

Exceptions

Invalid System Token

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "APIException",
		"code": 10,
		"errorMessage": "Project error",
		"details": null
	}
}
  • Cause: The systemToken provided is invalid.
  • Action: Verify and correct the systemToken.

Invalid X-Rublon-Signature

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "InvalidSignatureException",
		"code": 9,
		"errorMessage": "X-Rublon-Signature is invalid",
		"details": null
	}
}
  • Cause: The signature is missing or incorrect.
  • Action: Ensure the signature is correctly generated using the HMAC SHA-256 algorithm with your secret key.

Transaction ID Expired

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "TransactionIdExpiredException",
    "code": 11,
    "errorMessage": "The session has expired due to inactivity.",
    "details": "You must log in again."
  }
}
  • Cause: The transaction has expired.
  • Action: Prompt the user to initiate authentication again.

Access Token Expired

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "TransactionAccessTokenExpiredException",
    "code": 11,
    "errorMessage": "Authentication took too long to complete.",
    "details": "Return to the application and select the authentication method again."
  }
}
  • Cause: The access token is no longer valid.
  • Action: Prompt the user to select an authentication method again.

Missing Parameters or Incorrect Application Type

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "MissingFieldException",
    "code": 3,
    "errorMessage": "Parameter required",
    "details": null,
    "name": "callbackUrl"
  }
}
  • Cause: Required parameters are missing or the application type is incorrectly set.
  • Action: Verify all required parameters are included and the application type is correctly configured in the Admin Console.

Additional Notes

  • Socket.IO Communication:
    • For promptless applications, establish a WebSocket connection to listen for transaction events (TransactionConfirmedEvent, TransactionDeniedEvent).
    • The event channel follows the pattern: transactionConfirmation.{tid}.{eventName}.
  • Handling Timeouts and Retries:
    • Implement appropriate timeouts for user responses.
    • Handle TooManyRequestsException when users exceed allowed attempts.
  • Security Best Practices:
    • Use HTTPS for all API communications.
    • Protect your systemToken and secretKey.
    • Validate and sanitize all user inputs.

Troubleshooting

If you encounter any issues, please contact Rublon Support.

Related Posts