Tutorial: Standalone authentication

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

Client Side

On the client application side, set the "goOnline" option of the Webcom object to false, so that the connection to the Datasync Service is not established. This way, all authentication-related methods and functions remain available:

// Create a Webcom instance with the "offline" option
var ref = new Webcom("<your-app>", {goOnline: false});
// Launch an authentication operation...
ref.authAnonymously()
    // ...and catch the results
    .then(auth => console.log(`Authenticated user is ${auth.displayName} (with uid ${auth.uid})`))
    .catch(error => console.log(`Authentication failed: ${error.message}`));

// Create a Webcom instance with the "offline" option
WebcomOptions options = new WebcomOptions.create().setOffline();
Webcom ref = new Webcom("<your-app>", options);
// Launch an authentication operation
ref.authAnonymously(new OnAuth() {
    @Override
    public void onComplete(@Nullable AuthResponse authResponse) {
        Identity auth = authResponse.getIdentity();
        Log.v(TAG, "Authenticated user is " + auth.getDisplayName() + " (with uid " + auth.getUid() + ")");
    }
    @Override
    public void onError(WebcomError error) {
        Log.v(TAG, "Authentication failed: " + error.getMessage());
    }
});

Warning: the registerAuthCallback(), unregisterAuthCallback() and resume() functions are specific to the Datasync Service and don't work in "offline" mode. All authentication results (successes or failures) must be caught using promises returned by (or callbacks passed to) the authentication functions.

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 backend. The backend must then check the validity of the token before allowing or rejecting the requested operation.

Then there are two options to check the token validity:

Requesting the Webcom backend

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

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):

GET "https://io.datasync.orange.com/auth/v2/<your-app>/decode"
// with header:
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 the token locally

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 backend. 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.