Set up an entitlement service for AEM Mobile apps

Prerequisite knowledge

Understanding of MySQL and PHP
Understanding of AEM Mobile
Knowledge of creating and publishing content through the On-Demand Portal

Required products

AEM Mobile

Using an entitlement service, Experience Manager Mobile apps can support user login and grant access (entitlement) to certain collections based on the sign-in credentials.

Note that AEM Mobile supports only the Direct Entitlement API v2. See Entitlement in AEM Mobile.

To start working with the example entitlement server code, download the entitlement service files.

Megjegyzés:

By downloading the software listed below, I acknowledge that I have read and agreed to the terms of the Adobe.com Terms of Use and the Adobe Online Privacy Policy.

Download Source Code from Github

Megjegyzés:

The example implementation is to be provided as is, Adobe will not provide support on the code, the implementation, or the deployment process. If you have questions about the implementation, please use the AEM Mobile forum.

The MySQL database must have the correct table structure in order for the entitlement system to store and retrieve information from it.

Please note that while the following examples use the phpMyAdmin to administrate MySQL database, other MySQL administrative tools can achieve the same result.

If you already have phpMyAdmin installed in the server, please continue to the next section about creating a new database.

Navigate to the phpMyAdmin homepage.

Click the "Download x.x.x" button to download the most recent version of phpMyAdmin.

Follow the phpMyAdmin installation guide, and install the phpMyAdmin in the server that will host the direct entitlement.

Navigate to the phpMyAdmin portal from the server that it was installed on. Example: http://<my-domain>/phpmyadmin

If prompted to log in, enter the database username and password to the server.

From the home page of phpMyAdmin, click on either the “New” button located on the left sidebar or the “Database” tab located on the top navigation bar.

On the database page, enter a new database name (preferably “entitlement_admin”) in the “Create database” field.

Click the “Create” button to generate a new database with the input name.

After successfully creating the database, click on the database “entitlement_admin” (or the specified database name) from the list.

From the “entitlement_admin” database page, click the “Import” tab located on the top navigation bar.

Click the “Choose File” option to open the browser window.

From the browser window, navigate to the downloaded entitlement server folder, and select the pre-defined database file named “entitlement_admin.sql”.

Click the “Go” button to upload the selected database.

A message notifies you when the upload is successful.

You need to update a section of the source code in order for the entitlement service to communicate with the database that you just created.

Navigate to the entitlement server’s source code folder.

Open the “settings.php” file with a text editor, located in the following directory: “Source-Code/php/settings.php”.

Update the values for the following parameters:

// enter the MySQL host name
$db_host = 'localhost';
// enter the MySQL database username
$db_user = 'root';
// enter the MySQL database password
$db_password = 'root';
// enter the name of the MySQL database
$db_name = 'entitlement_admin';

Update the list of predefined administrative users for the parameter $admin_list. This is the list of admin users that will be able to access the custom entitlement server example once it is hosted.

Each of the admin users is tied to an AEM Mobile app. If you have two iOS apps, you would need to create two admin users.

The list contains the following format:

$admin_list = array(
    // admin user #1
    array(
        'username' => 'admin1',
        'password' => '202cb962ac59075b964b07152d234b70'
    ),
    // admin user #2
    array(
        'username' => 'admin2',
        'password' => '202cb962ac59075b964b07152d234b70'
    ),
    // add as many admin users as necessary
);

Megjegyzés:

You need to perform an MD5 hash on the password (i.e. PHP function md5()). In the above example, the sample password "202cb962ac59075b964b07152d234b70" is an MD5 hash of the value "123".

<?php

// this will output 202cb962ac59075b964b07152d234b70
// replace the value '123' below with the desired password for the admin
echo md5('123');

?>

Upload the entitlement service source code with the updated settings to the hosted server that the database was set up in the previous steps.

Use an FTP client such as Transmit to connect to the web server that will host your entitlement service.

Set the upload destination to the desired directory of the web server.

Select the entitlement server’s source code folder.

Upload all the files within the entitlement server’s source code folder.

Navigate to the path of the source code folder from the web server to see the login screen.

A set of tests has been provided to test the setup of the entitlement service. Please navigate to the setup_check.html from the hosting server. Click on any one of the buttons on the left sidebar to perform the corresponding test. Each check will return an “ok” if successful or an error message if not successful.

This includes following tests:

All – This will perform the entire test below.
PHP Modules – Check if the necessary PHP modules, utilized by the direct entitlement source code, are installed.
Configuration – Check if the user has updated the settings.php file. By default, the values are commented out, so the users will have to provide their real values.
Database – Check if the direct entitlement database has been successfully created. Check if the direct entitlement database can be accessed with the provided credentials (in settings.php).
HTTP Connection – Check if the hosting server can access HTTP (unsecured) websites.
HTTPS Connection – Check if the hosting server can access HTTPS (encrypted) websites.

This section will help you tailor the entitlement service to your own brand. All the images should be placed in the “images” folder within the entitlement server’s source code folder.

Customize the background of the Login Screen

Create an image with the following dimension: 1200x1200 pixels.
Save the image as “login_bg.jpg”.

Customize the logo in the Login Screen

Create an image with the following dimension: 34x33 pixels.
Save the image as “aemmobile_logo.png”.

Customize the Banner in the Home Page

Create an image with the following dimension: 1200x170 pixels.
Save the image as “header.jpg”.

Customize the Text in the Login Page

Navigate to the Direct Entitlement server’s source code folder.
Open the “index.html” file with a text editor.
Edit the follow values:

Login Header

Locate the following: “Adobe Experience Manager Mobile” (line 31).
Change the value to your own login header.

Username Placeholder

Locate the following: “Sign in with your Adobe ID for AEM Mobile” (line 40)
Change the value to your own username placeholder.

Password Placeholder

Locate the following: “Password” (line 48)
Change the value to your own password placeholder.

The entitlement service will automatically create the administrators if it doesn’t already exist during sign in. Once logged in, you will be presented with the screen to entitle users and groups to collections. For more information on how entitlement works, please refer to this article: Entitlement in AEM Mobile apps.

Enter the Bundle ID for the AEM Mobile app. This should match the one that is set in one of the following places from On-Demand Services:

Project settings

Go to Project Settings > Access tab > Bundle ID. If aIf the Bundle ID is specified here, this will be sent to the entitlement service instead of the Bundle ID value in Apps.

Apps settings

Go to Apps in the left rail and create or edit an app. If no Bundle ID is specified in project settings, this Bundle ID is used.

Using the entitlement admin, you can create and update users. Users must have a username and password and contain an optional description field. A user can be entitled to one or more products and can be assigned to one or more groups.

To add a user, click “Add User” from the “Users” tab.
To edit a user, select a user from the grid then either click “Edit User “or double-click on a user entry. In the Edit User dialog, you can update the username, password or description. You only need to set the password if you are updating it; otherwise, you can leave it blank.
To entitle a product to the user, select a product from the first drop down and click the “+” button.
To add the user to a group, select a group from the second drop down and click the “+” button.
To remove a product or group from the user, select it from the list and click “Remove”.

Using the entitlement admin, you can create and update groups. Groups are not required, but they are helpful for entitling groups of users to one or more products. Groups must have a name and contain an optional description field. You can entitle products to a group and assign users to a group.

To add a group, click “Add Group” from the “Groups” tab.
To edit a group, select a group from the grid then either click “Edit Group” or double-click. In the Edit Group dialog, you can update the name or description.
To entitle a product to the group, select a product from the first drop down and click the “+” button.
To add a user to the group, select a user from the second drop down and click the “+” button.
To remove a product or user from the group, select it from the list and click “Remove”.

Using the entitlement admin, you can create and update products. Products must have a product label, product description, product ID, and availability date. When creating the products, please make sure that the product ID matches the one created in the Products & Subscriptions section of the On-Demand Portal. For more information, please refer to this article: In-app purchases and subscriptions for AEM Mobile.

To add a product, click “Add Product” from the “Product” tab.
To edit a product, select a product from the grid then either click “Edit Product” or double-click. In the Edit Product dialog, you can update the product label, product description, product ID, or availability date.
To entitle a group to the product, select a group from the first drop down and click the “+” button.
To entitle a user to the product, select a user from the second drop down and click the “+” button.
To remove a group or user from the product, select it from the list and click “Remove”.

To associate the entitlement server with an AEM Mobile project, you need the following:

Input the bundle ID into the entitlement server. This must match the one that was set in the On-Demand Services.

This can be found in the On-Demand Services project metadata:

Or in the AEM Mobile App settings (if not set on the project level).

Input the entitlement endpoint into the On-Demand Services. For more information, please refer to this help article: Entitlement in AEM Mobile apps.

With the current set up, the administrative user credentials are set in the /php/settings.php file. To optimize this process of curating the admin users, it is best to store the $admin_list into the database and use MySQL administrative tools (like phpMyAdmin) to create/edit/update/delete them.

Create a new table (i.e. admins) in the database, you can use the same database (preferred) that was created earlier, and create any many admin users as necessary.

In the /php/settings.php file, you will need to replace the $admin_list = array() with MySQL prepare statements that will query the database for the list of admin users. Below is an example:

// initializes the empty list of admin user
$admin_list = array();

// connects to the database
$dbconnect = $mysqli = new mysqli($db_host, $db_user, $db_password, $db_name);

if ($dbconnect) { // successfully connected to the database
	// queries the database for the list of admin user credentials: username, password
	$stmt = $mysqli->prepare('SELECT username, password FROM admins);

	if ($stmt) { // prepare statement succeeded
		$stmt->bind_param('ss', $username, $password);
		$stmt->execute();
		// stores the queried results
		$stmt->store_result();

		if ($stmt->num_rows > 0) { // there exists admin users in the database
			// appends the queried admin credentials to the list
			while($stmt->fetch()) {
				$admin_list[] = array(
					'username' => $username,
					'password' => $password
				);
			}
		}
	}
}

This example entitlement server now supports the use of Google, Facebook, or a Generic identity provider. That way, users can sign in using a Google or Facebook account, or using a custom sign-in experience that you design. By default, the entitlement service does not support all three types of identity providers simultaneously.

For more information about custom authentication, see Custom authentication in AEM Mobile apps.

When using Google or Facebook as the Identity Provider, the AEM Mobile app will provide the authToken in the Entitlement V2 API: /entitlements. Depending on the entitlement server configuration, this example entitlement server will use the Google or Facebook API to pull the user email based on the authToken and check with the entitlement database.

To configure the server, update the parameter $identity_provider to either “google” or “facebook”. This parameter is found in /php/settings.php.

When using a generic identity provider, the app will redirect users to the provided custom sign-in UI. The UI must handle the login credentials, validate it, and pass the result back to the app.

A sample sign-in UI has been set up in /idp directory. When setting up the generic identity provider in the On-Demand Services, the authentication URL should be as follows:
http://<domain>/<path-to-course-code>/idp/index.html

If you have previously configured the server to use either Google or Facebook, please update the parameter $identity_provider back to “default”. This parameter is found in /php/settings.php.

Each app supports only one identity provider: Google, Facebook, or Generic. By default, this example entitlement server will only support one as well. However, if you have a reason to support more than one identity provider, such as using the same entitlement server for multiple apps, you need to copy the /services directory and rename it to something else, such as services-google. In the newly copied directory, force set the parameter $identity_provider to the desired identity provider (example: $identity_provider = "google") by adding it after line #13.

// in /services-google/index.php

require_once "../php/settings.php";
require_once "../php/utils.php";

$identity_provider = "google"

$path_info = $_SERVER["PATH_INFO"];
$call = substr($path_info, 1);

In this example, the new entitlement endpoint will be as follows:
http://<domain>/<path-to-source-code>/services-google/index.php

Jogi közlemények | Online adatvédelmi nyilatkozat

Setting up an entitlement service

Requirements

Introduction to Custom Entitlement

Download the source code

Install the entitlement database

Installing phpMyAdmin

Creating a new database

Uploading the pre-defined database structure

Configure the source code

Updating the MySQL settings

Hosting the source code

Test the entitlement server setup

Customize your entitlement service

Access the entitlement service

Specifying the Bundle ID

Managing users

Managing groups

Managing products

Activate the entitlement server for AEM Mobile project

Production Improvements

Using custom authentication in entitlement service

Using Google or Facebook as an identity provider

Using a generic identity provider

Configuring the service to support identity providers

Kérdezze a közösséget

Kapcsolat

Setting up an entitlement service

Requirements

Introduction to Custom Entitlement

Download the source code

Install the entitlement database

Installing phpMyAdmin

Creating a new database

Uploading the pre-defined database structure

Configure the source code

Updating the MySQL settings

Hosting the source code

Test the entitlement server setup

Customize your entitlement service

Access the entitlement service

Specifying the Bundle ID

Managing users

Managing groups

Managing products

Activate the entitlement server for AEM Mobile project

Production Improvements

Using custom authentication in entitlement service

Using Google or Facebook as an identity provider

Using a generic identity provider

Configuring the service to support identity providers

Ehhez hasonlók