1 Introduction

The 10Duke Entitlement Service provides a scalable solution for executing access policies across devices, people, companies, groups, services, IP assets and software applications. Utilised in conjunction with an enterprise grade Identity Provider, the 10Duke Entitlement Service offers a powerful solution for identity based licensing for any online application that needs to control user access to any digital product whether it be an application or a piece of digital content.

The following developer guide provides an introduction to the core concepts and elements within the Entitlement Service, together with a number of specific use case examples. It aims to help you to both understand how the Entitlement Service is structured and how its capabilities may best be harnessed for the particular use case you have. Specific examples of the Entitlement Service in action, together with an explanation of how it works and demo scripts, are provided at the end of this developer guide. Although some of these concepts may be unfamiliar to you (and at times can seem like pretty dense reading), if you read through the guide from the perspective of a particular use case, the relevant concepts will become clear quite quickly.

At its core, the Entitlement Service allows client applications to receive authorization decisions for accessing protected resources. The concept of the service and abstractions used by it allows a protected resource to reside in any part of the entire system you are building. To discuss authorization of a protected resource it usually helps to describe a logical ownership to the resource. In some cases, the resource may be of global nature and shared by many parts of the system. The protected resource might also be owned by e.g. an Identity Service or the Entitlement Service itself. So, 'owned by' in this context means the system component or service that has the prime responsibility of the protected resource. This guide will use a term 'authorization scope', which also relates to the point of view 'who has got the primary responsibility of a protected resource'.

As part of the introduction, let's look at a few examples of client requests for protected resource:

Scenario A: is the currently logged in user allowed to read email address of User B? In this example, the protected resource is the email address of another user. Lets assume the system has an Identity Service, which owns this user information. The Entitlement Service is responsible for providing the authorization decision while the Identity Service is responsible for enforcing it. In other words, when user A attempts to read email address of user B, the Identity Service will allow this only based on the decision provided by the Entitlement Service, which depends on if user B has sufficient privileges.

Scenario B: is the currently logged in user allowed to use Feature A of an application? Here, the protected resource is a feature of an application (Feature A). In this case, the Entitlement Service does not own the protected resource, and cannot enforce authorization for it. Instead, it provides for authorization decisions and the means for the client application to do the enforcing. Typically, the Entitlement Service Licensing Engine would be used for checking whether the user has a valid license for using the feature, and the license check results would be returned in a secure way so that client application can rely on the response and enforce it.

Scenario C: there is a separate service called "Discussion Board". Is the currently logged in user allowed to create a new discussion topic in this service? Here, the protected resource is discussion topic, and authorization is requested for creating a new discussion topic. "Discussion Board" is a separate service, and the Entitlement Service does not own the discussion topics. The Entitlement Service can still be used for providing the authorization decisions. This would often be beneficial because this can make access management simpler and more manageable by allowing reuse of existing Profile Groups and roles, and by allowing administrators to manage access centrally. In this example, the Entitlement Service would typically use the Role-based Authorization Engine, and the required roles and permissions would be defined in a separate scope that allows the Entitlement Service to distinguish them from roles and permissions that control access to resources owned by it. The mentioned scope would be: 'scope of "Discussion Board" application', which in this guide will be generalized as 'Consumer scope' lending some semantics from the OAuth authorization protocol.

Scenario D: is the caller allowed to add a 'Licensed Item X' into 'Product Package Y'? In this example, the protected resources are entities owned by the Entitlement Service itself. It means that authorization decision enforcing responsibility resides within the Entitlement Service alone. In other words, the 'authorization scope' is global from the Entitlement Service point of view and authorization is applied per the direct connection to the caller. Role based authorization would be used in this case rather than license based authorization.

The examples above explain use cases where the Entitlement Service provides authorization decisions based on the following underlying authorization engines:

  • Role-based Authorization Engine
  • Licensing Engine

1.1 Model

Software applications use an object model to express and represent real world entities. This Entitlement Service operates on entities like people, groups, companies, etc in its model.

Mapping real world entities

Real world Object model Explanation
A person Person Person
A real person is represented by an object model class named Person in this application. The Person class is in other words the core identity model for an individual.
Credential AbstractCredentialRelatedObject Credentials
Credentials are used to identify a person. Credentials are mainly divided into public and private types. E.g. a password is a private credential. Credentials are related to a person. The most common credential type used in this application is a user name - password credential type.
User profile Profile User Profile
A person who uses this application does so with a certain profile. The profile model enables management of the roles that a user can be associated with. A Profile can also be related with consuming licenses.
A group of users ProfileGroup Group
A group of users are modeled using the ProfileGroup class. ProfileGroup is not only used to define the group itself but also to associate a group with roles and privileges, and to enable license consumption on group basis.
Company Organization Company
A company is modeled using a class called Organization. The Organization object's type field value is set to "company" in this case.
The Organization model is also capable of representing other types of Organizations if that is relevant for the application. In this case the Organization object's type field value is set some relevant value defined by the application that uses the Entitlement Service.
Employees Organization members Employees
A company will consist of people working for it. Users are connected to an Organization using the ProfileGroup model. The value of the type field in ProfileGroup is set to "employees" to denote that all connected users are employees of the company.
Group members
Organizations may have people associated with it in many roles (e.g. not employees). In this case the application using the Entitlement Service is free to name the type of related ProfileGroup objects according to its own rules by setting the value of type field.
Product ProductPackage Product
An important part of using the Entitlement Service is granting licenses and managing existing licenses. The base on which license management operates uses a model called ProductPackage. Product packages are associated with a license model and have licenseable items as their the content. A licenseable item together with a license model function as an intelligent template when granting licenses.
Entitlement Entitlement Entitlement
An Entitlement is a container for licenses. The ability to resolve a license consumer relation between a user and an Entitlement is required before a license check or license consumption can be called for a user.
Personal licenses Personal Entitlement Personal License(s)
A user can call license checking or license consumption if related to an Entitlement directly using a Many-to-Many relation object called LicenseConsumerRelation.
Company licenses Organization Entitlement Company's License(s)
Users that "belong" to a company may consume licenses granted to the company by relating selected ProfileGroup objects to the Organization object's Entitlement. The connection from ProfileGroup objects to Entitlement objects is a Many-to-Many relation object called LicenseConsumerRelation (same relation object as used to relate Profile objects with Entitlements directly).
An Organization as Entitlement owner Organization as Entitlement owner Organization as Entitlement Owner
Company level right to manage an Entitlement and its content is implied by an owner relation to the Entitlement object. A direct One-To-Many relation between Organization and Entitlement is used as the model to denote this owner type relation between a company and its Entitlement.
A user as Entitlement owner Profile as Entitlement owner Person as Entitlement Owner
A personal right to manage an Entitlement and its content is implied by an owner relation to the Entitlement object. A direct One-To-Many relation between Profile and Entitlement is used as the model to denote this owner type relation between a user and his / her Entitlement.

Additional terminology

Licensor Licensor is the legal entity that grants the right to use (license) to an asset, e.g. to a software application. Most commonly the licensor is a company.
Licensee Licensee is the legal entity that receives the right to use an asset licensed by the licensor, e.g. right to use a software application. Most commonly the licensee is a company or a person.
Entitlement A logical container that is used to authorize access to licenses and permissions that grant the privilege to use / consume assets licensed by the licensor. The contents of an Entitlement expresses the current state of rights related to a contract. In other words. the entitlement represents the customers' rights to use products and services licensed by the licensor.
License The right to use / consume an asset licensed by the licensor. E.g. a software application, content, permit to access premises
License model Attributes, rules and behaviors that are applied when granting and checking licenses. Such attributes may be: maximum concurrent use, maximum installations, maximum consumption, etc. Rules may include things such as how to determine start date of licenses, how to enforce concurrent use, etc.
Product package A container that defines licensed items to grant to the customer based on a purchase or other type of contract; e.g. a product package in the Entitlement system maps to a sellable item in an online store for example. In this case, the customer makes a purchase and is granted licenses based on the content of the associated product package.
ProfileGroupRole Type used to model and manage permissions that apply in profile group scope.
OrganizationRole Type used to model and manage permissions that apply in Organization scope.
Protected Resource Entity for which authorization is required.
Permission Named permission definition, used for controlling access to protected resources. Two basic categories of permissions are defined: Entity type permissions and operation permissions. Entity type permissions are used for authorizing access to entities based on entity class / type. Operation permissions are used for authorizing access to operations. Permission class applies in the scope of the Entitlement Service for the resources it owns.
Permission action Actions that user may execute on a protected resource. Actions are technically stored and logically applied in the relation between a permission and the object the permission is in relation to. e.g. this allows reusing Permissions in several Roles as it is possible the control the allowed permission actions separately per each Role.
Role Collection of permissions / authorization rules. When a Role is granted to a user, user is granted the permissions defined by the Role. Role class applies in the scope of the Entitlement Service for the resources it owns.
ConsumerPermission Named permission definition. Similar to Permission, but for controlling access to protected resources owned / defined by a service connected to the Entitlement Service.
ConsumerRole Collection of permissions / authorization rules to be used in a scope of a service connected to the Entitlement Service.
OrganizationRole A role applicable in a scope of an Organization
ProfileGroupRole A role applicable in a scope of a ProfileGroup.
Built-in Role A role that is given to user implicitly, for example based on authentication or group membership.

1.2 Feature highlights

The Entitlement Service offers a number of features that can be used in a wide variety of use cases:

Feature Explanation
Graph interface Intuitive and generic REST server interface for easy and efficient client application and system integration.
High level authorization Caller using Entitlement service is decoupled from decision making procedure and logics. Both licensing engine and role based authorization engine are used for providing authorization result.
Identity based authorization Entitlements, roles and permissions can be associated to organizations (companies) and users. Consuming licenses or accessing protected resources requires user authentication.
Authorization within organizations Licenses and role based authorization can be used in a scope of an organization (e.g. a company). For example, administrator of a Licensee company may assign users and groups rights to use licenses contained in an Entitlement, or the administrator may assign users and group rights to access protected resources in the Entitlement system (e.g. license meta information, user and organization information).
Authorization within groups Similarly to authorization within organizations, licenses and role based authorization can be used in a scope of a Profile Group. Although a Profile Group cannot normally be used as a Licensee, administrator of a group may administrate authorization within the scope of the group. The Entitlement system allows creating groups as needed, groups may include different kinds of collaboration groups, groups of users with different responsibilities in organization etc.
License model support Supports versatile license models from traditional perpetual hardware-locked licenses to subscription based online licenses that may allow concurrent usage.

Accept & Close

We have placed cookies on your computer to help make this website better. You can change your cookie settings at any time. Otherwise, we'll assume you're OK to continue.