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.