How to authenticate through OAuth in Kuzzle

HOW_TO_AUTHENTICATE _THROUGH_OAUTH_IN_KUZZLE
Kuzzle authentication is handled by Passport so naturally you can add OAuth strategies to your login. JavaScript and Android SDK will handle the redirection for you.

STEP 1: INSTALLATION

You need to get OAuth authentication plugin in Kuzzle.

The easiest way for you is to use Kuzzle’s CLI:

kuzzle plugins --install --npmVersion "*" kuzzle-plugin-auth-passport-oauth

STEP 2: CONFIGURATION

Within Kuzzle, OAuth plugin is using Passport so you should configure it using passportjs strategies.
First you have to configure the plugin to specify which strategies you want to use and state your credentials for each provider.
You can import a JSON file with Kuzzle’s CLI.
Here is a configuration example:

"strategies": {
        "github": {
          "credentials": {
            "clientID": "<your client id>",
            "clientSecret": "<your client secret>",
            "callbackUrl": "http://localhost:8888/#!/github"
          },
          "persist": [
            "login",
            "avatar_url",
            "name",
            "email"
          ],
          "scope": [
            "user:email",
            "user:avatar_url"
          ]
        },
        "facebook": {
          "credentials": {
            "clientID": "<your client id>",
            "clientSecret": "<your client secret>",
            "callbackURL": "http://localhost:8888/#!/facebook"
          },
          "persist": [
            "login",
            "public_profile",
            "name",
            "email"
          ],
          "scope": [
            "email",
            "public_profile"
          ]
        }
      }

Then here is how to proceed if you want to import it using Kuzzle’s CLI (more here):

kuzzle plugins --importConfig config.json kuzzle-plugin-auth-passport-oauth

 

The credentials object defines your tokens and redirects URI according to the chosen strategy.

The persist array defines what you want to put in Kuzzle to create a new user. If this attribute is empty or does not exist the user won’t be persisted and not logged in.

The scope array defines a private access to the user information you want to get. You can see more here: http://passportjs.org/docs/oauth.

When you add a strategy to the configuration you’ll need to install the passport strategy accordingly. Here is an example for Facebook’s strategy:

npm install passport-facebook

You can find more on the passport website.

STEP 3A: USING JS SDK EXTENSION FOR OAUTH AUTHENTICATION

You need OAuth extension for JS SDK to add the loginOauthPopup function to Kuzzle.

You can get it with npm:

npm install kuzzle-sdk-login-oauth-popup

Include it to your project:

<script src="node_modules/kuzzle-sdk-login-oauth-popup/index.js" type="text/javascript"></script>

And then:

var strategy = 'facebook';
kuzzle.loginOauthPopup(strategy, (err, res) => {
  // This callback will be called once the user is logged in
});

STEP 3B: USING ANDROID SDK FOR OAUTH AUTHENTICATION

Android SDK gives you a WebViewClient called KuzzleWebViewClient to handle OAuth’s authentication with Kuzzle. Here is how to use it:

 

final String strategy = "facebook";
WebView webView = (WebView) findViewById(R.id.webview);
webView.setWebViewClient(kuzzle.getKuzzleWebViewClient());
kuzzle.login(strategy, new KuzzleResponseListener<JSONObject>() {
  @Override
  public void onSuccess(final JSONObject object) {
    handler.post(new Runnable() {
      @Override
      public void run() {
        try {
          if (object.has("headers")) {
            webView.loadUrl(object.getJSONObject("headers").getString("Location"));
          } else {
            // The user is now logged in
            // Here you can hide the webview and go on with the login process
          }
        } catch (JSONException e) {
          // Handle JSON exception
        }
      }
    });
  }

  @Override
  public void onError(JSONObject error) {
    // Handle error
  }
});

 

LINKS:

You can find the passport documentation here for more information about passport strategies.

Some more documentation on how to create an authentication plugin for Kuzzle here.

Kevin Blondel
07.18.2016