If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

Introduction

In securing their projects Appery.io users have several options to select from:

  1. Authenticating with Users collection of the Appery.io DB (data storage: Appery.io DB or user’s DB).
  2. Authenticating with LDAP (data storage: Appery.io DB or user’s DB).
  3. Authenticating with Social network provider.

In this example, you’ll see how a developer using Appery.io DB as data storage for his mobile apps and LDAP as a security provider can protect his data from other users with the mechanism of creating users with the same names as users in customer LDAP after successful login.

Quickstart

If you’re new to API Express, we recommend reading this document: API Express.

Before you can test how LDAP authentication and authorization works in API Express, you must create a database, a DB connection, select (create) a security provider, create a project and a model, and, lastly, generate REST service(s) to refer to the database you added to the project.

Creating database

You can use your existing database or create a new one: in the project, go to the Databases tab and click “Create new database”, pass the name and confirm.

Here you can read more on Appery.io databases.

1. First, create a new collection (Places, for example). You can also select the existing custom one (if any).

2. Then, open it and click the “Change default ACL” tab to open the ACL Editor.

3. Select the user you would like to define the access rights for.

Select All users* to manage access rights for all users or select @Creator to manage access rights for the user that created the current object.

The most common use case is @Creator.

4. Click “Add User”, then: “Save and Close”.

5. Now, open the Security and permissions tab, check the “Secure collection” checkbox, and save:

Updating LDAP security provider

1. Now, update your LDAP security provider: on the Resources tab, open the Security view and select your Security provider (here: LDAP). Since you plan to access the data stored in Appery.io database, you must check the “Save users for appery.io database” checkbox in the Security provider section.

More information on  security providers can be found here.

2. Click “Test” to check if everything is working. Then click “Save”. You should see the success message:

If needed, add a new security provider and configure it.

Securing API Express project

Then, open your project (here: ExpenseReport) under the API Express tab and, under the Settings tab, check the “Allow only authenticated users to call REST” checkbox to secure data by making the system require entering a session token. Then, select the security provider you ‘ve just updated from the drop-down:

 If neccessary, create a new project – learn here how to do it.

Adding connection to Appery.io DB

1. Before creating a model, you must add a new DB connection with your Appery.io database credentials. To do it, go to: API Express > Create new DB connection.

2. Enter the required credentials. For example:

  • Database connection name – ExpenseReportConnection.
  • Connection type – Appery.io Database.
  • Database name – ExpenseReport.
  • Username – type your username.
  • Password – password that you typed when creating the user record.

3. Click “Test” to check if everything is working. Then, click “Save”. You should see the success message:

Creating model

Lastly, a model for your DB collection (here, places) can be created: select the Database connection you have created earlier (ExpenseReportConnection) and select the table (here: Places) from the drop-down:

The term Collection in Appery.io databases corresponds to the term Table in SQL databases.

For more information on models, check this link.

Testing Model

Now, let’s see how authentication and authorization with LDAP as a security provider works.

1. In your project, click the test link to open the places model view:

2. Before testing the services (FIND, GET, CREATE, UPDATE, or DELETE), the LDAP session token must be obtained: click “Obtain” and pass the required LDAP credentials.

3. Then, API Express verifies the user’s username/password in LDAP and:

  • if API Express verification of the user username/password in LDAP fails, API Express returns information about the invalid credentials and the user gets the 403 error (“Wrong username or password”);
  • If API Express verification is successful, API Express generates its own session token, creates a user in Users collection with the same username as in LDAP (if it doesn’t exist yet), obtains the backend session token, saves both: the API Express session token and the backend session token, and then returns the API Express session token to the user under the API tab.

4. Having obtained the API Express session token, the user can invoke REST services of API Express (for example, CREATE operation) providing the session token obtained. Here, the next two scenarios are possible:

  • If API Express doesn’t find the session token in the session token storage, API Express returns information about the invalid session token and the user gets the 403 error (“Incorrect or absent X-Appery-Session-Token header”).
  • If API Express finds the session token in the session token storage, it then finds the backend session token by the API Express session token and invokes backend service (an sql query in the database) with the backend session token and returns the 200 response to the user.

Invoking the CREATE operation:

Verifying Appery.io DB

Now, when you go back to the database, you will see that the user name (LDAP username) was added to the Users collection of the ExpenseReport database (the duplicate name of the LDAP user):

And, after you open the Places collection, you will also see the new record made with the value of the ACL field referring to the user created:

The primary purpose of this authentication and authorization method is that LDAP users should see only his\her data (personally created entities) and can’t see the data of other users.