Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Getting Started with User Management

Getting Started with User Management

Telerik Platform provides 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 native Android 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. Declare the Required Permissions for the App
  6. Initialize the Everlive Instance
  7. Log In the User to Your Application
  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 Android SDK.

  1. Log in to your Telerik Platform account and click Getting StartedDownloads in the top right corner.
  2. Under Download SDKs & Tools click Backend Services to see a list of available downloads.
  3. Follow the instructions on the page to download a ZIP archive containing the Android SDK to your local machine.

    Downloads overview image

  4. Unzip the archive, copy the .jar SDK file to your app and add it as a library.

  5. Add the following statements to import the required namespaces from the SDK:
import com.telerik.everlive.sdk.core.EverliveApp;
import com.telerik.everlive.sdk.core.EverliveAppSettings;
import com.telerik.everlive.sdk.core.model.system.AccessToken;
import com.telerik.everlive.sdk.core.result.RequestResult;
import com.telerik.everlive.sdk.core.result.RequestResultCallbackAction;

Declare the Required Permissions for the App

Logging in a user requires the INTERNET Android permission. To request it, add the following declaration in you app's AndroidManifest.xml just before the <application> opening tag:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

Initialize the Everlive Instance

The Everlive object connects the client app to its Telerik Platform backend. To initialize it and to specify your App ID value, add these literals as static fields of your activity class:

private static final String APP_ID = "your-app-id";

private static EverliveAppSettings everliveAppSettings;
private static EverliveApp everliveApp;

Then initialize the Everlive instance in the entry point of your application (for intsance, in the onCreate method of an activity) by adding the following lines:

everliveAppSettings = new EverliveAppSettings();
everliveAppSettings.setAppId(APP_ID);
everliveAppSettings.setUseHttps(true); //set to false or delete to use HTTP

everliveApp = new EverliveApp(everliveAppSettings);

All of the snippets below use the asynchronous methods exposed by the Backend Services Android SDK. Alternatively, to obtain more control over your app you can use the synchronous methods of the SDK and wrap them into AsyncTasks in your Android application. You can read more about the different synchronous and asynchronous flavors of the SDK in this article.

Log In the User to Your Application

The SDK communicates with your Telerik Platform app using the internet connection of the device. Add the <uses-permission android:name="android.permission.INTERNET" /> to your app's manifest.

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 Android SDK uses this access token automatically in consequent user requests for server resources while the EverliveApp instance exists. Based on the provided access token in the request the server recognizes the role and the access permissions for the request.

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 that you created earlier as values of the username and the password variables:

String username = "my-username";
String password = "my-password";

everliveApp.workWith().authentication().login(username, password).executeAsync(new RequestResultCallbackAction() {
    @Override
    public void invoke(RequestResult requestResult) {

        if (requestResult.getSuccess()) {
            AccessToken loginResult = (AccessToken) requestResult.getValue();
            String accessToken = loginResult.getToken();
            String tokenType = loginResult.getTokenType();

        } else {
            // Handle errors coming from requestResult.getError().getMessage()
        }
    }
});

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. Sample snippets can be found in Getting Started with Data.

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 on the server:

everliveApp.workWith().authentication().logout().executeAsync(
    new RequestResultCallbackAction() {
        @Override
        public void invoke(RequestResult requestResult) {

            if (requestResult.getSuccess()) {
                Boolean isLogout = (Boolean) requestResult.getValue();
            } else {
                // handle the logout error here
            }
        }
    }
);

(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. One way to do this is to save the token type and the access token in Android's SharedPreferences or in another storage that fits your needs when a user logs in successfully to your app.

After you have the access token saved locally, you can assign it to the EverliveApp instance for further use. This is done with the setAccessToken method of the SDK:

everliveApp.setAccessToken(new AccessToken(tokenType, accessToken));

Don't forget to remove the token from SharedPreferences when you log the user out.

(Advanced) Check If the User is Logged In

The existence of an access token on the client device does not mean that the bearer of this access token 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.

Use the getMe SDK method to obtain the information about the current user:

everliveApp.workWith().users().getMe().executeAsync(
    new RequestResultCallbackAction() {
        @Override
        public void invoke(RequestResult requestResult) {

            if (requestResult.getSuccess()) {
                // the user is logged in
            } else {
                // the user is not logged in
            }
        }
    }
);

Then, if the user is not logged in, you could for example redirect them to the login screen.

Next Steps

See Also


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