Tutorial: Standalone authentication

The [[service]] Authentication Service may be used independently from the Datasync Service when you only need to authenticate users or you have your own backend to provide other application-specific services.

Client Side

On the client application side, use the "offline" option of the Webcom object, 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 [[service]] 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 [[service]] backend

Simply use the following REST request [[snippet]]:

GET "[[baseUrl]]/auth/v2/<your-app>/decode?token=<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 [[service]] 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 [[service]] backend on your own backend. The secret can be retrieved on the [[console]] in the "authentication" tab / "secret" card of your [[service]] 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.