Tutorial: Standalone authentication

Serverless Authentication Standalone authentication

The Webcom Authentication Service may be used independently of the ServerlessDb Service when you only need to authenticate users or have your own back end to provide other application-specific services.

On the client side

On the client application side, you must take care of never initializing the ServerlessDb Service, by never invoking the property of your Webcom application instance that refers to the ServerlessDb Service.

In JavaScript, never invoke the serverlessDb property of your WebcomApp instance, and use the Authentication Service (through the authentication property) as usual to get a Webcom authentication token:

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const auth = app.authentication; // we retrieve only the Authentication Service
// the `app.serverlessDb` property is never invoked so the serverlessDb is not instanciated
// Launch an authentication operation...
auth.authAnonymously()
    // ...and catch the results as usual
    .then(authDetails => console.log(`Authenticated user token is: ${authDetails.webcomToken}`))
    .catch(error => console.log(`Authentication failed: ${error.message}`));

Of course, it remains possible to further switch the ServerlessDb Service online by invoking the serverlessDb property:

const database = app.serverlessDb; // a websocket is implicitly open with back end
// you can explicitly ask to disconnect or to (re)connect:
serverlessDb.disconnect();
serverlessDb.connect();

In Kotlin, the simplest way to prevent the ServerlessDb Service from starting is to set the startOnline property of the webcom.properties asset file to false (see the “App configuration” chapter for further details):

# mandatory property, it expects a string
applicationId=<IDENTIFIER-OF-YOUR-WEBCOM-APPLICATION>
# optional property, set to "false" to prevent ServerlessDb Service from starting
startOnline=false

val myApp = WebcomApplication.default // the app defined by the above 'webcom.properties' asset file

However, if you don't use an asset file to configure your Webcom application, you can also directly set the startOnline property of the WebcomConfiguration object:

val myApp = WebcomApplication(WebcomConfiguration("myapp.identifier", startOnline = false))

You can then invoke all methods of the Authentication Service as usual:

val authenticator = myApp.authenticationService
authenticator.getGuestMethod().authenticate {
    when (it) { // it: WebcomResult<AuthenticationDetails>
        is WebcomResult.Success -> print("Successfully signed-in token: ${it.result.authenticationToken}")
        is WebcomResult.Failure -> print("Failed signing in: ${it.error.message}")
    }
}

Nonetheless, it remains possible to further switch the ServerlessDb Service online by setting its isConnectionEnabled property to true:

val datasync = myApp.datasyncService
datasync.isConnectionEnabled = true

In Swift, the ServerlessDb Service starts only when it is instantiated. Thus, while you don't call the datasyncService property of a WebcomApplication instance, the web-socket to the Webcom back end is not established. In the meanwhile, you can invoke any method of the Authentication Service as usual:

let authenticationService = app.authenticationService
authenticationService.authenticate(with: AuthenticationMethodGuest()) { result in
    switch result {
    case let .success(details):
        print("Successfully signed-in with token: \(details.authenticationToken)")
    case let .failure(error):
        print("Failed signing in: \(error.message)")
    }
}

On the server side

Once the application client has identified the user using the Webcom Authentication Service, it can pass the got token to all the requests to your application-specific back end. The back end must then check the validity of the token before allowing or rejecting the requested operations.

Then there are two options to check the token validity: either by requesting the Webcom back end, or by checking the token locally on your back end.

Checking a token by requesting the Webcom back end

Simply use the following REST request (replace “<your-app>” with your actual application identifier):

curl -X GET "https://io.datasync.orange.com/auth/v2/<your-app>/decode?token=<the-token-to-validate>"

or better (using the Authorization header prevents from revealing your token within the back end logs):

curl -X GET "https://io.datasync.orange.com/auth/v2/<your-app>/decode"
     -H 'Authorization: Bearer <the-token-to-validate>'

  It is answered either with a 200 OK response when the given token is valid or a 403 Forbidden response otherwise.

Checking a token locally on your back end

As tokens issued by the Webcom backend are JSON Web Tokens (JWT), they can be verified using a library implementing the JWT standard, provided that you host the HMAC secret used by Webcom backend on your own back end. The secret can be retrieved on the Webcom developer console in the "authentication" tab / "secret" card of your Webcom application.

As an example, in nodejs, using the jsonwebtoken library (npm install jsonwebtoken), you can implement something like:

var jwt = require('jsonwebtoken');
var token = "<the-token-to-verify>";
var secret = "<the-app-secret-picked-from-the-developer-console>";
jwt.verify(token, secret, function(err, decoded) {
  if (err) {
    console.error("INVALID TOKEN");
  } else {
    // the token is valid, going on the requested operation
  }
});

To find out a proper JWT library suited to the programming language of your backend, take a look at this website.

↑ ↑