Skip to main content

Registration Flow

There are 3 major steps that your application should implement in order to have the registration flow completely implemented using RTAS:

  • Create Token (application-server) - Creates a RTAS token for the front-end to listen to events, and sends the registration created event.
  • Listen RTAS Events (front-end) - Front-end implementation for each RTAS event
  • Handle Callback (application-server) - Handles and sends registration events to the front-end user

There are two events for the RTAS registration flow.

Create Token​

The application server calls RTAS using the RTAS OpenAPI client to get an authentication token. This authentication token is then forwarded to the front-end module along with the address to which the front-end connects to the RTAS.

RTAS token must be created using the unique_id returned by the TF API.

After the registration token is created, the application server should notify the RTAS server that a new registration was created.

Registration Created event​

This event serves to provide some information to the frontend about the new registration, such as the user ID, username and other properties for a simpler implementation of the UI.

The OpenAPI client provided only has one API for the registration callback. This means that there are properties that are shared between the events and properties that are unique to the event. These are the properties of the registration created event:

PropertyIs Required
StatusYes
Application NameYes
User IDYes
User display nameYes
QR CodeYes
QR Code expirationYes
Deeplink URLYes

Example Implementation​

An application server implementation would look like:

package main

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "net/http"
    "time"

    tfsdkclient "securityside.com/tf/go-sdk"
    tfsdkrequests "securityside.com/tf/go-sdk/requests"
    rtas "securityside.com/rtas/go-sdk"
)

const (
    RTASFrontEndURL = ""                 // Load from config file. This value should be provided by SecuritySide team.
    ApplicationName = "Your application" // Value representing the application name.
    RTASAddress     = ""                 // Load from config file. This value should be provided by SecuritySide team.
    ClientID        = ""                 // Load from config file. This value should be provided by SecuritySide team.
    ClientSecret    = ""                 // Load from config file. This value should be provided by SecuritySide team.
)

var (
    RTASClient, _ = initializeRTAS(RTASAddress, ClientID, ClientSecret)
)

func initializeRTAS(rtasAddress, clientID, clientSecret string) (*rtas.APIClient, error) {
    rtasCnf := rtas.NewConfiguration()
    rtasCnf.Servers = rtas.ServerConfigurations{{URL: rtasAddress}}
    apiClient := rtas.NewAPIClient(rtasCnf)

    token, resp, err := apiClient.LoginApi.LoginExecute(apiClient.LoginApi.Login(context.Background()).Body(*rtas.NewLoginRequest(clientID, clientSecret)))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    rtasCnf.AddDefaultHeader("Authorization", fmt.Sprintf("Bearer %s", token.Token))
    go tokenRenew(apiClient, 30*time.Minute) // The token renews every 30 minutes. This token is used in order to authenticate the application server with the RTAS application.

    return apiClient, nil
}

func tokenRenew(apiClient *rtas.APIClient, timerInterval time.Duration) {
    ticker := time.NewTicker(timerInterval)
    for range ticker.C {
        token, resp, err := apiClient.TokenRenewApi.RenewTokenExecute(apiClient.TokenRenewApi.RenewToken(context.Background()))
        if err != nil {
            panic(err.Error())
        }
        _ = resp.Body.Close()

        apiClient.GetConfig().AddDefaultHeader("Authorization", fmt.Sprintf("Bearer %s", token.Token))
    }
}

type registrationFlowResponse struct {
    QRCode      string `json:"qr_code"`
    DeepLinkURL string `json:"deep_link_url"`
    RTASToken   string `json:"rtas_token"`
    RTASURL     string `json:"rtas_url"`
}

func registrationFlowController(w http.ResponseWriter, r *http.Request) {
    const (
        userID   = "john.doe"
        userName = "John Doe"
    )

    // Call TF SDK to create a registration code for the user
    registerResponse := tfsdkrequests.RegisterCodeV2Response{}
    // Initialize Client with a ClientBuilder struct
    client := tfsdkclient.Client{}
    qrCodeByte, _ := client.GetRegistrationQRCode(context.Background(), registerResponse, 200)
    qrCode := string(qrCodeByte)
    deeplinkURL, _ := client.GenerateRegistrationDeeplinkURL(registerResponse)

    rtasToken, err := rtasCreateRegistrationFlowToken(r.Context(), userID, registerResponse.UniqueID)
    if err != nil {
        panic(err)
    }

    // Send registration created RTAS event here
    if err := rtasSendRegistrationCreatedCallback(r.Context(), userID, userName, qrCode, deeplinkURL, registerResponse.UniqueID, registerResponse.ExpiresAt); err != nil {
        panic(err)
    }

    resBytes, err := json.Marshal(registrationFlowResponse{
        QRCode:      qrCode,
        DeepLinkURL: deeplinkURL,
        RTASToken:   rtasToken,
        RTASURL:     RTASFrontEndURL,
    })
    if err != nil {
        panic(err)
    }

    w.WriteHeader(http.StatusOK)
    if _, err := w.Write(resBytes); err != nil {
        panic(err)
    }
}

func rtasCreateRegistrationFlowToken(ctx context.Context, userID, registrationCodeUniqueID string) (string, error) {
    token, resp, err := RTASClient.EndUserRegistrationTokenApi.RegistrationEndUserTokenV2Execute(RTASClient.EndUserRegistrationTokenApi.RegistrationEndUserTokenV2(ctx).Body(*rtas.NewEndUserRegistrationTokenRequestV2(userID, registrationCodeUniqueID)))
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    return token.Token, nil
}

func rtasSendRegistrationCreatedCallback(ctx context.Context, userID, userName, qrCode, deepLinkURL, registrationCodeUniqueID string, qrCodeExpiration int64) error {
    body := *rtas.NewRegistrationCallbackRequestV3(registrationCodeUniqueID, rtas.REGISTRATION_CREATED_V2, userID)
    body.SetUserDisplayName(userName)
    body.SetQrCode(qrCode)
    body.SetQrCodeExpiration(qrCodeExpiration)
    body.SetApplicationName(ApplicationName)
    body.SetDeeplinkUrl(deepLinkURL)

    // signalr connection properties
    body.SetCloseConnectionOnReceive(false)
    body.SetStoreInCache(true)
    body.SetCacheExpiresAfterMinutes(15)

    resp, err := RTASClient.RegistrationCallbackApi.RegistrationCallbackV3Execute(RTASClient.RegistrationCallbackApi.RegistrationCallbackV3(ctx).Body(body))
    if err != nil {
    var e rtas.GenericOpenAPIError
    if errors.As(err, &e) {
    fmt.Printf("RTAS Error\n%s\n%s\n", e.Error(), string(e.Body()))
        return err
    }
    fmt.Printf("RTAS Error\n%s\n", err.Error())
        return err
    }
    defer resp.Body.Close()

    return nil
}

Listen RTAS Events​

In order to listen for RTAS Events the end-user should receive a RTAS Token and Endpoint URL from the application server so it can initialize the RTAS UI module.

Web​

@securityside/rtas-ui to see library specifics

example.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"></meta>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"></meta>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"></meta>
    <title>RTAS- Registration</title>
</head>
<body>
    <div id="rtas"></div>

    <script src="https://cdn.securityside.com/packages/realtime-auth/rtas-ui/0.0.3/index.umd.js"></script>
    <script>

        // Make a request that initialize registration flow
        fetch("https://your_backend_url.com/tf/create-qr", { method: "POST" })
        .then((response) => response.json())
        .then((responseData) => {

            // responseData: {
            //     "rtas_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJncm91cHNpZCI6ImFwcDp0Zi1kZXYtYmFja29mZmljZToyZmYyNjU4NC1mYWYxLTQwYmQtODg4My0xY2VhMjE1YTRlNWIsdXNlcjp0ZXN0ZV92YTQsdH...",
            //     "rtas_url": "https://signalr-ha.dev.securityside.com"
            // }

            new rtasui.RTASUI()
                .setTargetElement("#rtas")
                .setUrl(responseData.rtas_url)
                .setToken(responseData.rtas_token)
                .setOnErrorCallback((errorData) => console.log("OnError -> ", errorData))
                .setOnConnectionEstablishedCallback(() => console.log("-= OnConnectionEstablished =-"))
                .setLanguage("PT_PT")
                .setRegistrationType()
                .setOnRegistrationPendingCallback((data) => {
                	console.log("OnRegistrationPending -> ", data);
                	// data: {
                	// 	"application_name": "Your application",
                	// 	"deeplink_url": "https://open.dev.trustfactor.securityside.com/register?payload=djIAAAAAAABkB...",
                	// 	"qr_code": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAIAAABEtEjdAAAfr0lEQVR4nOzdT6gkV/k38Lm372RmMiZxM...",
                	// 	"qr_code_expiration": 1678104748,
                	// 	"user_display_name": "John Doe",
                	// 	"user_id": "john.doe"
                	// }
                })
                .setOnRegistrationSuccessCallback((data) => {
                	console.log("OnRegistrationSuccess -> ", data);
                	// data: {
                	// 	"application_name": "Your Application",
                	// 	"contract_key": "7D/Iw9i3NdYLbHfw0UsVk3LcJo8PpQXoOPIRBhvF4Bk=",
                	// 	"device_info": {
                	// 		"device_model": "TFVA",
                	// 		"manufacturer": "SecuritySide",
                	// 		"marketing_name": "SecuritySide TFVA",
                	// 		"name": "Virtual Agent #1",
                	// 		"operating_system": "TFVA",
                	// 		"os_version": "1.0"
                	// 	},
                	// 	"device_key": "N+RlRWij82dHZ4TJ/slTbRP+UltX9SGC5DMhZOULbP4=",
                	// 	"user_display_name": "John Doe",
                	// 	"user_id": "john.doe"
                	// }
                })
                .setOnRegistrationExpiredCallback((data) => {
                	console.log("OnRegistrationExpired -> ", data);
                	// data: {
                	// 	"application_name": "Your Application",
                	// 	"user_display_name": "John Doe",
                	// 	"user_id": "john.doe"
                	// }
                })
                .build();
        })
        .catch((error) => {
            console.error("Error:", error);
        });

    </script>
</body>
</html>

Mobile​

In order to properly implement RTAS on a mobile application, the application server should expose an endpoint serving a static HTML page with the following content:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div id="rtas"></div>
        <script src="https://cdn.securityside.com/packages/realtime-auth/rtas-ui/0.0.3/index.umd.js"></script>
    </body>
</html>
package com.securityside.realtime.kt

import android.annotation.SuppressLint
import android.os.Bundle
import android.util.Log
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.webkit.WebView
import android.webkit.WebViewClient
import android.widget.Button
import androidx.fragment.app.Fragment
import com.securityside.realtime.R

class WebViewFragmentKt : Fragment() {
    // URL for RTAS endpoint
    private val URL = "https://signalr.rtas.trustfactor.cloud"
    // Authentication token
    private val TOKEN = "YOUR_AUTH_TOKEN_HERE";

    private val TAG = WebViewFragmentKt::class.java.simpleName

    private lateinit var mWebView: WebView
    private lateinit var mBtnRegistration: Button

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        return inflater.inflate(R.layout.fragment_web_view_kt, container, false)
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        mWebView = view.findViewById(R.id.webView) // Initialize the WebView element
        mBtnRegistration = view.findViewById(R.id.btnRegistration) // Initialize the Registration button
        mWebView.settings.javaScriptEnabled = true
        mWebView.settings.domStorageEnabled = true
        mWebView.settings.allowFileAccess = false
        mWebView.settings.allowContentAccess = false
        setListeners() // Load WebView content
    }

    private fun setListeners() {
        // Set click listener for the Registration button
        mBtnRegistration.setOnClickListener {
            try {
                // Add a JavaScript interface for Registration
                mWebView.addJavascriptInterface(
                    WebAppInterfaceRegistrationKt(requireActivity(), URL, TOKEN),
                    "WebAppInterfaceRegistrationKt"
                )
                mWebView.webViewClient = object : WebViewClient() {
                    override fun onPageFinished(view: WebView?, url: String?) {
                        super.onPageFinished(view, url)
                        // Add and execute JavaScript code for Registration

                        val javascriptCode = """
                            javascript:(function () {
                                var url = WebAppInterfaceRegistrationKt.getUrl();
                                var token = WebAppInterfaceRegistrationKt.getToken();
                                new rtasui.RTASUI()
                                    .setTargetElement("#rtas")
                                    .setLanguage("PT_PT")
                                    .setToken(token)
                                    .setUrl(url)
                                    .setOnErrorCallback(function(errorData) { 
                                        WebAppInterfaceRegistrationKt.onError(JSON.stringify(errorData)); 
                                    })
                                    .setOnConnectionEstablishedCallback(function() { 
                                        WebAppInterfaceRegistrationKt.onConnectionEstablished(); 
                                    })
                                    .setRegistrationType()
                                    .setOnRegistrationPendingCallback(function(data) { 
                                        WebAppInterfaceRegistrationKt.onPending(JSON.stringify(data)); 
                                    })
                                    .setOnRegistrationExpiredCallback(function(data) { 
                                        WebAppInterfaceRegistrationKt.onExpired(JSON.stringify(data)); 
                                    })
                                    .setOnRegistrationSuccessCallback(function(data) { 
                                        WebAppInterfaceRegistrationKt.onSuccess(JSON.stringify(data)); 
                                    })
                                    .build();
                            })();
                        """.trimIndent()
                        // Execute the JavaScript code using evaluateJavascript
                        mWebView.evaluateJavascript(javascriptCode) { value ->
                            if (value != null) {
                                Log.d("WebView", "JavaScript executed: $value")
                            } else {
                                Log.d("WebView", "JavaScript execution returned null")
                            }
                        }
                    }
                }
                // Load the registration HTML page from the assets folder
                mWebView.loadUrl("file:///android_asset/sample.html")
            } catch (exception: Exception) {
                Log.e(TAG, exception.message ?: "Exception")
            }
        }
    }
}

The application should inject javascript after the document is loaded on the webview in order to properly initialize the RTAS client and create the WebSocket connection.

Handle Callback​

Handle the TrustFactor registration callback.

Registration Success event​

If the registration flow is completed (by registering a successfully TrustFactor contract), the application server should notify the RTAS Server using the callback received from TF to send a request to the RTAS server notifying the success of the operation.

The OpenAPI client provided only has one API for the registration callback. This means that there are properties that are shared between the events and properties that are unique to the event. These are the properties of the registration created event:

PropertyIs Required
StatusYes
Application NameYes
User IDYes
User display nameYes
Contract keyYes
Device InfoYes
Device KeyYes
Wrong Device TokenNo
Custom DataNo

Wrong Device Token is short-lived token (ie: 2 minutes duration) that the application-server transmits to the front-end using the RTAS so the user can remove the newly registered device. This might be useful if the user registers the wrong device or someone else reads the QR Code from the screen of the legitimate user. The application server should have an endpoint validating this token that calls TF SDK ResetContract API.

Example Implementation​

In order to notify the end-user about the success of the registration flow, your code should look like:

package main

import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "time"

    tfsdkcallback "securityside.com/tf/go-sdk/callback"
    tfsdk "securityside.com/tf/go-sdk/models"
    tfsdkcrypto "securityside.com/tf/go-sdk/util/crypto"
    rtas "securityside.com/rtas/g-sdk/v4"
)

const (
    RTASAddress     = ""                 // Load from config file. This value should be provided by SecuritySide team.
    ApplicationName = "Your application" // Value representing the application name.
    ClientID        = ""                 // Load from config file. This value should be provided by SecuritySide team.
    ClientSecret    = ""                 // Load from config file. This value should be provided by SecuritySide team.
)

var (
    RTASClient, _ = initializeRTAS(RTASAddress, ClientID, ClientSecret)
)

func initializeRTAS(rtasAddress, clientID, clientSecret string) (*rtas.APIClient, error) {
    rtasCnf := rtas.NewConfiguration()
    rtasCnf.Servers = rtas.ServerConfigurations{{URL: rtasAddress}}
    apiClient := rtas.NewAPIClient(rtasCnf)

    token, resp, err := apiClient.LoginApi.LoginExecute(apiClient.LoginApi.Login(context.Background()).Body(*rtas.NewLoginRequest(clientID, clientSecret)))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    rtasCnf.AddDefaultHeader("Authorization", fmt.Sprintf("Bearer %s", token.Token))
    go tokenRenew(apiClient, 30*time.Minute) // The token renews every 30 minutes. This token is used in order to authenticate the application server with the RTAS application.

    return apiClient, nil
}

func tokenRenew(apiClient *rtas.APIClient, timerInterval time.Duration) {
    ticker := time.NewTicker(timerInterval)
    for range ticker.C {
        token, resp, err := apiClient.TokenRenewApi.RenewTokenExecute(apiClient.TokenRenewApi.RenewToken(context.Background()))
        if err != nil {
            panic(err.Error())
        }
        _ = resp.Body.Close()

        apiClient.GetConfig().AddDefaultHeader("Authorization", fmt.Sprintf("Bearer %s", token.Token))
    }
}

func tfRegisterCallbackController(w http.ResponseWriter, r *http.Request) error {
    // Handle TF Callback
    callback := tfsdkcallback.Register{
        DeviceKey:            tfsdkcrypto.PublicKey{},
        ContractKey:          tfsdkcrypto.PublicKey{},
        DeviceInfo:           tfsdk.DeviceInfo{},
        DeviceIP:             "",
        DeviceLocation:       nil,
        AppUserUniqueID:      "jonh.doe",
        RegisterCodeUniqueID: nil,
    }
    const (
        userName = "Jonh Doe" // This value should have a relation with AppUserUniqueID from the callback
    )

    var (
        wrongDeviceToken = "" // Optional. The application server should expose an API that validates this token and allows the removal of the newly registered device.
    )

    if err := rtasSendRegistrationSuccessCallback(r.Context(), callback, userName, &wrongDeviceToken); err != nil {
        panic(err)
    }

    w.WriteHeader(http.StatusOK)

    return nil
}

func rtasSendRegistrationSuccessCallback(ctx context.Context, callback tfsdkcallback.Register, userName string, wrongDeviceToken *string) error {
    tfSDKDeviceInfoToRTASDeviceInfo := func(deviceInfo tfsdk.DeviceInfo) *rtas.RegistrationCallbackRequestV2DeviceInfo {
        registrationCallbackDeviceInfo := rtas.NewRegistrationCallbackRequestV2DeviceInfo(deviceInfo.Name, deviceInfo.Manufacturer, deviceInfo.Model, deviceInfo.OS, deviceInfo.OSVersion)
        registrationCallbackDeviceInfo.MarketingName = &deviceInfo.MarketingName
        return registrationCallbackDeviceInfo
    }

    body := *rtas.NewRegistrationCallbackRequestV3(*callback.RegisterCodeUniqueID, rtas.REGISTRATION_SUCCESS_V2, callback.AppUserUniqueID)
    body.SetUserDisplayName(userName)
    body.SetApplicationName(ApplicationName)
    body.DeviceInfo = tfSDKDeviceInfoToRTASDeviceInfo(callback.DeviceInfo) // This method converts the TrustFactor SDK device into a RTAS device.
    body.SetDeviceKey(callback.DeviceKey.ToString())
    body.SetContractKey(callback.ContractKey.ToString())
    body.WrongDeviceToken = wrongDeviceToken

    // signalr connection properties
    body.SetCloseConnectionOnReceive(true)
    body.SetStoreInCache(true)
    body.SetCacheExpiresAfterMinutes(15)

    resp, err := RTASClient.RegistrationCallbackApi.RegistrationCallbackV3Execute(RTASClient.RegistrationCallbackApi.RegistrationCallbackV3(ctx).Body(body))
    if err != nil {
    var e rtas.GenericOpenAPIError
    if errors.As(err, &e) {
        fmt.Printf("RTAS Error\n%s\n%s\n", e.Error(), string(e.Body()))
        return err
    }
    fmt.Printf("RTAS Error\n%s\n", err.Error())
        return err
    }
    defer resp.Body.Close()

    return nil
}