Entitlement in AEM Mobile apps

Entitlement is a method to provide authentication and content authorization to users. When users sign in, they can access content that they were previously unable to view. There are two main uses for entitlement.

To offer different content to different users based on sign-in accounts. For example, a scuba diving app could provide one set of collections to students who sign up for a course and a different set of collections to scuba instructors.

To tie the digital subscription to a print subscription. Users can either purchase or subscribe to content through a store (such as iTunes App Store), or they can sign in directly through the publisher. If the user’s sign-in account is registered in the publisher’s entitlement database, signing in gives users access to content.

Entitlement is supported on all platforms: iOS, Android, Windows, and Desktop Web Viewer.

To use entitlement, an entitlement service is required that implements the Direct Entitlement API v2:

How entitlement works

Entitlement is based on the product that is associated with the collection. Products are listed in the Products & Subscriptions section of the On-Demand Portal.

A user who is entitled to a collection has access to all articles in that collection.

Users are not automatically entitled to nested collections.

If a collection has a product type set to Entitled, the Article Access setting for each article determines whether users have access to that article. If an article is set to Free, users can view it. If an article is set to Protected, users cannot view it unless they are permitted to. If an article is set to Metered, the threshold settings apply. Setting articles as Metered is predominantly used for commercial apps to allow users to preview content before purchasing. (See Paywalls and article preview in AEM Mobile apps.)

If a collection has a product that is set to Free, all articles inside the collection are treated as free even if Article Access is set to Protected or Metered.

By default, a standard sign-in prompt appears in the app when a user taps the Account or Sign In option. To change the sign-in interface, you can set up custom authentication. For example, you can enable sign-in through an identity provider such as Facebook or Google, and configure your entitlement server to work with that identity provider. (See Custom authentication in AEM Mobile.)

Enabling entitlement

Set up an entitlement server.

Experience Manager Mobile requires an entitlement service that implement Direct Entitlement API v2. For information about setting up an entitlement server, see the following articles:

We recommend using HTTPS domains instead of HTTP. If you use HTTP, make sure that you select the Allow Content from HTTP option when building the iOS app.

Test your server by performing a request using a Java 8 JRE (or later) and the Apache HttpClient library. We recommend using TLS 1.2. TLS 1.1 and TLS 1.0 are supported but do not comply with Apple ATS guidelines. If you use TLS 1.1 or 1.0, select the Allow Content from HTTP option when building the iOS app.SSL 3 is no longer supported and we advise against using TLS 1.0.

Be proactive about renewing your server certificate before it expires; otherwise, communication with the entitlement service will stop functioning completely once the certificate expires.

The Master Admin uses the Entitlement Services tab in Master Settings to create entitlement services for all the projects in the account that use entitlement. At least one entitlement service must be created in order for entitlement to be enabled on the project level.

Entitlement Endpoint

Specify the URL of the entitlement endpoint of your entitlement service.

Authentication Endpoint

Specify the URL of the SignInWithCredentials endpoint of your entitlement service, if it is different from the Entitlement Endpoint.

Entitlements Cache

Specify the length of time (in seconds) that entitlement information granted by your service may be cached. After the cache duration expires, your entitlement service may be contacted for updated entitlement information. Specify a value between 0 and 31546000 seconds (approximately 1 year). If no value is specified, then entitlement responses are not cached, as if the value 0 is specified.

Note that the lack of entitlement is also cached following the same specified value, only with an upper limit of one hour. For that reason, it is safe to allow entitlements to be cached for much longer than an hour, since adding an entitlement would still take at most one hour to become effective. The drawback is that removing an entitlement can take longer to become effective. If that is not a concern, we recommend setting high cache values (such as one month). High cache values reduce server load and improve responsiveness and reliability for users.

If caching for such a long time is not an option, the recommended value for Entitlements Cache is higher than the length of the typical user session. Specifying even a low value such as one minute is useful for improving load times and responsiveness.

Authentication Token Cache

Specify the length of time (in seconds) that authentication tokens provided by your service may be cached. After the cache duration expires, your service may be contacted to renew the authentication token. Specify a value between 0 and 31546000 seconds. If no value is specified, then the authentication token is cached for 3600 seconds (1 hour). If 0 is specified, authentication tokens are not cached (not recommended).

The value for Authentication Token Cache should not be lower than the value for Entitlements Cache if the RenewAuthToken API always returns a different authToken than the one passed in..

Connection Timeout

Specify the number of seconds (between 1 and 60) that the entitlement server will wait to establish a connection and obtain a response. If no value is specified, the connection timeout is set to 15 seconds.

Edit your project settings, click the Access tab, and specify the following options:

Choose Enable Entitlement. At least one entitlement service must be created in Master Settings for this option to be available.

Select the entitlement service that was created in Master Settings. Make sure that you select the correct entitlement service for the project.

Specify the Bundle ID used in your entitlement service. Specifying a Bundle ID in project settings is necessary if your entitlement service requires a different Bundle ID than the one you specify when building your app. The Bundle ID is also required for Desktop Web Viewer entitlement.

If desired, specify Create Account URL and Forgot Password options. Your users can tap these buttons to view the web page you specify.

Publish collections.

Publishing a collection adds the Product ID to Products & Subscriptions (unless you created the Product ID beforehand and selected it when editing the collection).

In the Products & Subscriptions section of the Portal, select the product associated with each collection, and edit it to make it Entitled or Restricted.

When you define the Product type, you can choose Free, Entitled, or Restricted. Free collections are available to all users. If you want to require users to sign in to access a collection, choose either Entitled or Restricted. Entitled collections are visibile to all app users, but protected articles include a paywall. Restricted collections are invisible to users unless they sign in to gain access. For information about restricted collections, see Restricted collections in AEM Mobile.

Specifying the Product Type

For collections in which the product type is set to "Entitled," edit article properties to specify whether each article is set to Free, Metered, or Protected.

In "entitled" collections, all users have access to free articles. A paywall appears over protected articles, prompting the user to sign in. For metered articles, threshold settings apply.

In "free" or "protected" collections, the article access settings don't matter. Articles in free collections are available to all users, and articles in restricted collections are hidden until the user signs in.

Build the app and test sign-in capabilities.

Preflight apps do not support entitlement features.

Entitlement service performance

Ideally, entitlement requests are served quickly at all times. Generally speaking, with shorter response times from the entitlement service, more requests per second can be sustained.

When using both entitlement and push notifications, be aware that severe traffic spikes may occur, depending on the percentage of users that are signed in. We recommend monitoring the server load during a push and throttling the rate of sent push notifications accordingly.