Getting Started with User Management

Getting Started with User Management

Telerik Platform provide an out-of-the box user management solution with support for common user operations such as:

  • User registration
  • User authentication and authorization
  • Role management
  • Recovering user accounts (reset password)
  • Linking and unlinking user accounts from social providers or AD FS providers
  • Sending automated emails

In this article you will learn how to create a user account through the Telerik Platform web portal and how to set its permissions. Then you will proceed to integrating user authentication in a JavaScript application.

Steps at a glance:

  1. Create a User Account
  2. Verify the Account
  3. Specify What Data the User Can or Cannot Access
  4. Source and Install the SDK
  5. Initialize the Everlive Instance
  6. Log In the User to Your Application
  7. Connect to Data
  8. Log Out the User
  9. (Advanced) Persist the Access Token
  10. (Advanced) Check If the User is Logged In

Prerequisites

Create a User Account

After you have the User Management service set up, you can proceed to creating user accounts:

  1. Open you app.
  2. Navigate to Users > Users Browser.
  3. Click the Add a user button. You see the Add a user form:
    Create a user account from the portal
  4. Fill in all the fields, having these things in mind:

    • You will need Username and Password for other user tasks such as integrating user authentication in your application code; write them down or make sure you remember them.
    • You will need to access the provided email mailbox to receive the user's Welcome and Verify Your Account emails.

      Telerik Platform stores the password securely in the database using an irreversible password hash.

      All user accounts are assigned the default role set for your Telerik Platform app. You can manage the default role or add new roles by going to Users → Roles in the left-side navigation.

  5. Click Save when you are ready.

You can also create user accounts programmatically using the approach explained in Registering Users.

Verify the Account

Telerik Platform handles the user verification process for each new user by sending an automated email titled Verify your account featuring a verification link. In addition, the user receives a Welcome email that greets them on behalf of your application.

Go to Users in the left-hand navigation pane and then click Automated Emails to edit the email templates or click Emails Settings to manage other email-related settings.

To verify the user account, log in to the user email account you provided earlier, find the Verify your account message and click the verification link.

This verifies your account. The VERIFIED column for the user in the Users Browser now shows Yes.

Note that both verified and unverified accounts are treated the same unless you implement your own programming logic based on the VERIFIED field.

Verified user account image

Specify What Data the User Can or Cannot Access

After creating the user account, you can proceed to granting or denying it access to various data in your application.

You do that by specifying the content type's permissions model.

  • Choosing the Private model allows authenticated users to read and write only their own data in the respective content type.
  • Choosing the Shared model allows authenticated users to read and write shared data in addition to their own data in the respective content type.
  • Choosing the Role-based model allows you to specify granular permissions for each of the predefined roles. For example you can grant read permissions to users in the Anonymous role but deny them create, update or delete permissions.

Take the following steps to manage role-based permissions through the UI:

  1. Navigate to Data > Permissions.
  2. Locate the content type that you want to manage.
  3. Click the drop-down menu next to the content type name and select Role-based.
  4. Use the check boxes to set granular permissions.
  5. Click the Save button.

To understand how permissions work, assume that you want to give the following permissions on the content type to the following roles:

  • Anonymous (e.g. unauthenticated users) is denied any access
  • Registered (e.g. the default role of the application) can read and create new data, but cannot modify or delete existing data
  • Owner (defaults to who created a given item, can be changed) can read all data items (inherited from Registered) and modify or delete their own items

To achieve this, make sure that:

  • All check boxes for the Anonymous role are cleared
  • The Read and Create boxes for the Registered role are checked and that Update and Delete are cleared
  • All boxes for Owner are checked

The next image shows the result of taking these actions.

Role-based permissions for a content type

You can learn more about roles in Introduction to Roles.

To manage permissions programmatically, see Introduction to Access Control.

Source and Install the SDK

The first step of integrating User Management in your app is obtaining and installing the JavaScript SDK. How to do that depends on your development platform.

You can read detailed information about installing and accessing the SDK in your project in Getting Started with the JavaScript SDK.

Hybrid Cordova (AppBuilder)

In the AppBuilder window, include the following script resource in your index.html file immediately after the cordova.js reference.

<script src="https://bs-static.cdn.telerik.com/latest/everlive.all.min.js">

NativeScript

  1. Download the JavaScript SDK as a ZIP archive from https://bs-static.cdn.telerik.com/sdk/latest/javascript/EverliveSDK.JS.zip and unpack it in your project's app folder.
  2. Require the JavaScript SDK, specifying the path to the SDK file relative to your project's app folder:
var Everlive = require('./everlive.all.min');

Node.js

  1. Run this command in your project folder: sh npm install everlive-sdk
  2. Add the following line of code to your project:

    var Everlive = require('everlive-sdk')
    

Web

Include the following script resource in your index.html file:

<script src="https://bs-static.cdn.telerik.com/latest/everlive.all.min.js">

Initialize the Everlive Instance

The Everlive object connects the client application to a Telerik Platform app.

To initialize the Everlive object in your application's entry point add the following code to the onDeviceReady handler in js/index.js right after the navigator.splashscreen.hide(); call.

var everlive = new Everlive({
    appId: "your-app-id",
    scheme: "https"
});

Log In the User to Your Application

After initializing the SDK you can start adding code that logs in the user to your application.

The Telerik Platform User Management service implements token-based authentication. After a successful login based on a username and password pair, the user receives an access token from the server. The JavaScript SDK uses this access token automatically in consequent user requests for server resources while the application is running.

See (Advanced) Persist the Access Token and (Advanced) Check If the User is Logged In for more information about working with access tokens.

In the code below, assign the username and the password for the user you created earlier as values of the username and the password variables:

var everlive = new Everlive({
    appId: "your-app-id",
    scheme: "https"
});

var username = '';
var password = '';

everlive.authentication.login(username, password, function(data) {
    var accessToken = data.result.access_token;
    alert("Successfully logged the user in! Received access token: " + accessToken);
}, function(err) {
    alert("Unfortunately an error occurred: " + err.message);
});

Connect to Data

After successful authentication the user gets access to any registered users-only data. To operate with this data, add your programming logic in the success handler of the login method.

 var everlive = new Everlive({
     appId: "your-app-id",
     scheme: "https"
 });

 var username = '';
 var password = '';

 everlive.authentication.login(username, password, function(data) {

     var places = everlive.data('Places');
     places.get(null, function(data) {
         alert(JSON.stringify(data));
     }, function(err) {
         alert(err.message);
     });

 }, function(err) {
     alert("Unfortunately an error occurred: " + err.message);
 });  

Log Out the User

To log the user out of the application, call the SDK's logout method like in the following example. This invalidates the access token for the user.

var everlive = new Everlive({
    appId: "your-app-id",
    scheme: "https"
});

everlive.authentication.logout(function() {
    alert("Logout successful!");
}, function(err) {
    alert("Failed to logout: " + err.message);
});

(Advanced) Persist the Access Token

Often you may want to extend the user session, keeping the user logged in to the application until they choose to log out or the access token expires. To achieve this, you need to persist the access token on application exit and then reuse it in the next application start ups.

To do that, set the authentication.persist parameter to true when initializing Everlive as the example shows. This tells the JavaScript SDK to automatically save the token and reuse it the next time you initialize Everlive with the same parameter.

To handle the case where the token has expired, set authentication.onAuthenticationRequired to a custom function that redirects the user to the log-in screen or performs another similar action.

var everlive = new Everlive({
        appId: "your-app-id",
        scheme: "https",
        authentication: {
            persist: true,
            onAuthenticationRequired: function() {
                alert('Your access token has expired. Please log in.');
                // Redirect to log-in page
            }
        }
});


var username = '';
var password = '';

everlive.authentication.login(username, password);

(Advanced) Check If the User is Logged In

The existence of an access token on the client device does not mean that the user is actually authenticated or logged in. The access token may have expired, the user may delete their account, change their password, or log out. That is why before each business-critical operation of the application you might want to verify the state of the current user.

You can leverage the SDK's currentUser method to do that, as follows:

var everlive = new Everlive({
    appId: "your-app-id",
    scheme: "https",
    authentication: {
            persist: true
    }
});

everlive.Users.currentUser(function(data) {
    if (data.result) {
        var username = data.result.Username;
        alert(username + " is logged in!");
    } else {
        alert("Missing access token. Please log in!");
    }
}, function(err) {
    alert(err.message + " Please log in.");
});

If you have already defined a function for Everlive's authentication.onAuthenticationRequired parameter as in the previous step, it will be executed in case the access token has expired. Respectively, the currentUser method's error callback will not be called.

Next Steps

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.