The 10Duke Entitlements Developer Guide entitlements_developer-guide.pdf

Table of Contents

Introduction

10Duke Entitlements 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, 10Duke Entitlements 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 10Duke Entitlements, together with a number of specific use case examples. It aims to help you to both understand how 10Duke Entitlements is structured and how its capabilities may best be harnessed for the particular use case you have. Specific examples of Entitlements 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.

Let's look at a few examples of how a client application might make a request to access a 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. Let’s assume the system has an Identity Service, which owns this user information. The 10Duke Entitlements is responsible for providing the authorization decision while the Identity service/application 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. The Identity application has delegated the authorisation decision to the Entitlement service.

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). Here again, the 10Duke Entitlements does not own the protected resource, and cannot enforce authorization for it. Instead, it provides the 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 10Duke Entitlements 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 10Duke Entitlements 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 10Duke Entitlements provides authorization decisions based on the following underlying authorization engines:

  • Role-based Authorization Engine
  • Licensing Engine

We will explain the differences between the two later on in this guide.

Identity-based Licensing

The 10Duke Entitlements solutions implements the concept of ‘identity-based licensing’ (or identity-based entitlements, depending on your perspective. From an implementation point of view, they are the same.) Identity-based licensing is a method of controlling access to a digital product (or any protected resource) based on the authenticated identity of an individual while also retaining flexibility in terms of licensing a product to him based on a number of constraints such as company, device, location and application type.

Identity-based licensing is enabled by three components:

  1. An Identity Provider API which is responsible for authentication.
  2. An Entitlements API which is responsible for authorisation.
  3. The end-user - either a human or technical actor that is trying to access the protected resource
  4. a Reporting API - a fourth, optional aspect of identity-based licensing is which allows for the collections of all event data generated in the system

Components of identity based licensing

For developers, identity-based licensing offers more flexibility both in terms of the licensing terms under which you can make your products available and in terms of improving the ease with which your customer can access and interact with your products.

Terminology and Models

Software applications use an object model to express and represent real world entities. The 10Duke Entitlements operates on entities like people, groups, and companies in its model.

The table below outlines a simple mapping of some of the main objects use in 10Duke Entitlements and how they map to their real-world equivalents.

Explanation Object model
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. Person
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. AbstractCredentialRelatedObject
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. Profile
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. ProfileGroup
Company A company is modeled using a class called Organization. The Organization object's type field value is set to "company" in this case.

Organization 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 10Duke Entitlements.
Organization
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 10Duke Entitlements is free to name the type of related ProfileGroup objects according to its own rules by setting the value of type field.
Organization members
Product An important part of using the 10Duke Entitlements 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. ProductPackage
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. 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. Personal 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). Organization Entitlement
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. Organization 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. Profile as Entitlement owner

Table 1: Mapping real world entities

Additional terminology

Below is a table that lists other key terms you should become familiar with in order to better understand how 10Duke Entitlements works.

Term Explanation
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 10Duke Entitlements 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 10Duke Entitlements 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 10Duke Entitlements.
ConsumerRole Collection of permissions / authorization rules to be used in a scope of a service connected to the 10Duke Entitlements.
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.

Feature highlights

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

Feature Explanation
Graph API Intuitive and generic graph-based server interface for easy and efficient client application and system integration.
High level authorization A caller using the 10Duke Entitlements is decoupled from decision making procedure and logics. Both the 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.

Authorization

At its core, the 10Duke Entitlements allows client applications (web, mobile or desktop) to receive authorization decisions for accessing protected resources. A ‘protected resource’ is an entity for which authorisation is required (i.e the entity you are providing access to, like a software app, video file, or data set) 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 10Duke Entitlements itself. So, 'owned by' in this context means the system component or service that has the prime responsibility of the protected resource.

As you read through the next section it may be useful to keep mind the following two questions as they applied to the particular use case you have:

  1. What is the protected resource that you are defining the entitlement to?
  2. Within what authorization scope does it sit?

Authorization scope

Authorizing access to a protected resource is required in different scopes. For instance, a Profile Group may need to define resources that must be accessible only by members of the group. Or user information may need to be available to members of all groups that the user belongs to. In these cases, authorization is performed in the scope of the Profile Group (or Groups). Generally, this would use the ProfileGroup authorization scope. In implementing your system, it may be helpful to think of placing a protected resource within the authorisation scope of a company, group of people or similar (those who will be accessing the protected resource if they are allowed to.

Some example Authorization scopes are:

Scope Enforced by Description Use case example
10Duke Entitlements 10Duke Entitlements The system-wide scope User A and User B are not members of any same Organization or ProfileGroup, is User A allowed to access information of User B?
Organization 10Duke Entitlements Authorizing in scope of an Organization (company). Scope defined by objects or attributes considered as owned by Organization, Organization membership or OrganizationRoles defined in the scope of each Organization. User A attempts to change name of Organization X. Is she allowed to do this, without given privileges to any other Organization?
ProfileGroup 10Duke Entitlements Authorizing in scope of a ProfileGroup. Scope defined by objects or attributes considered as owned by ProfileGroup, ProfileGroup membership or ProfileGroupRoles defined in the scope of each ProfileGroup. User A attempts to invite a new member to a group, is she allowed to send the invitation?
Consumer Consumer Authorizing in scope of a application connected to the 10Duke Entitlements Social support forum user attempts to change the name of a message board, is she allowed to do this?
License Client application or application connected to the 10Duke Entitlements Authorizing licensable resources like application features or chargeable / limited access website content User A tries to use Feature B in a client application, is she allowed to use the feature?

Table 2: authorization scopes

Note: Scopes may be overlapping in some cases, which is currently seen in that OrganizationRoles may imply ProfileGroupRoles.

The following picture depicts some example authorization scopes in which profile information, (a protected resource owned by an Identity service primary scopes in which user information (‘owned’ by an Identity Service) is authorized.

Authorization scopes Logical authorization scopes

Role-based Authorization Engine

The 10Duke Entitlements allows users (subjects) to work in several roles. Role membership alone never gives authorization, but there must always be permissions given for the role or roles. Thus, knowledge of user's roles does not describe what the user is or is not allowed to do without knowledge of permissions associated with the roles.

The Role-based Authorization Engine used within 10Duke Entitlements implements the common role-based authorization / role-based access control (RBAC) schema. http://en.wikipedia.org/wiki/Role-based_access_control Wikipedia describes the three primary rules of RBAC:

  1. Role assignment: a subject can exercise a permission only if the subject has selected or been assigned a role.
  2. Role authorization: a subject's active role must be authorized for the subject. With rule 1 above, this rule ensures that users can take on only roles for which they are authorized.
  3. Permission authorization: a subject can exercise a permission only if the permission is authorized for the subject's active role. With rules 1 and 2, this rule ensures that users can exercise only permissions for which they are authorized.

When using the 10Duke Entitlements for role-based authorization, the client requesting authorization decisions does not need to take care of any of the assignment or authorization tasks, as the 10Duke Entitlements will just respond whether authorization for a protected resource is granted or denied.

The authorization model is a meta-level on top of the domain model. The domain model defines entities required to implement interaction between an end user and a service. Some Identity Service example entities are: Profile, Person, EmailAddress, ProfileGroup, Organization and relations between these entities. The authorization model allows defining authorization rules for accessing the domain model entities. It is especially significant to distinguish between role concepts defined by the authorization model (Role, ProfileGroupRole and OrganizationRole) and user groups defined by the domain model (ProfileGroup). ProfileGroups consist of users that logically belong together because they share an attribute in the identity domain. For instance, they may be employees of the same company, work together in the same content group, or be users of the same service or product. ProfileGroup membership does not necessarily have anything to do with authorization. Roles, in contrast, only exist for the purposes of authorization.

The only common factor between members of a role is that they have been granted the same privileges via the role. In many cases, ProfileGroups are natural scopes of authorization. What may happen here is that members of ProfileGroup are given a role based on their group membership - but still the ProfileGroup membership itself doesn't define any permissions, but roles are used in a similar manner as in any other authorization scope.

Built-in roles

Built-in role Description
Viewer Granted to all users, authenticated or not, interacting with the system
Authenticated user Granted to all users authenticated against the Identity Service
Author When authorizing access to an entity owned by the service (e.g. Identity Service), granted to original author of the entity
Last editor When authorizing access to an entity owned by the service (e.g. Identity Service), granted to last actor that has made a change to the entity
Owner When authorizing access to an entity owned by the service (e.g. Identity Service), granted to owner of the entity. Entity owner may be set explicitly or resolved using the overridable OwnerResolver.
Organization member roles When actor for which authorization is requested belongs to same Organization as the entity being authorized, granted to the actor
ProfileGroup member roles When actor for which authorization is requested belongs to same ProfileGroup as the entity being authorized, granted to the actor

Table 3: Built-in roles

Organization member and ProfileGroup member built-in roles work on three different levels:

  1. ProfileGroup member and Organization member built-in roles are granted when authorizing in the scope of any Organization or ProfileGroup
  2. ProfileGroup type member and Organization type member built-in roles are granted when type of the Organization or ProfileGroup used as authorization scope matches the built-in role type
  3. Specific ProfileGroup member and Specific Organization member built-in roles are applied only when authorizing in the scope of a specific Organization or ProfileGroup explicitly associated with the role

With these three levels, it is easier to manage permissions that are common to all ProfileGroups or Organizations, permissions that are specific to all ProfileGroups of Organizations of a certain type (e.g. Content Groups)), and permissions that apply only for a certain ProfileGroup or Organization.

Product Licensing and Entitlement Management

The primary use case for 10Duke Entitlements is the licensing of software applications or digital content to end users. This process can be more generally referred to as Entitlement Management and the core processes related to it are:

  • Product management
  • Granting rights to customers, entitling the customer (fulfilment)
  • License activation
  • Help and support
  • Administration and monitoring

Product management

The product management aspect in this 10Duke Entitlements includes the mapping from sellable items to product package definitions.. Each sellable item will map to a product package in this 10Duke Entitlements. Buying several items in one go means calling license initialization for several product packages to ensure fulfillment and delivery of all contracted licenses for the customer.

Working from the lowest level, mapping from the real-world item(s) you sell to a customer, th application or features within an application are designated as ‘licensed items’ within 10Duke Entitlements. For example, an application “SimWorld” might be a single licensed item to be licensed to end customers.

To this licensed item (or combination of licensed items) you then apply a license model (such as subscription, perpetual, etc).

This combination of license item(s) and a license model creates a product package. A product package is related by a many-to-many relation to licensed items. This way several product packages may include same licensed items.

A license model is associated with the relation between a product package and a licensed item. This way the same licensed item can be licensed by different attributes and behaviors depending on product package that is used for granting license.

Fulfillment

Calling this 10Duke Entitlements to initialize licenses based on a product package will grant the privileges that the customer made a contract for. The granted licenses are made available to the customer based on the license model assigned to the product package and each licensed item in the package.

The contents of an Entitlement are related to a user or a company (as per defined by licensor). In the event that the entitlement belongs to a company, then people related to the company may be able to access the entitlement and licenses within it.

License activation

License activation is an optional step and may apply only for specific licensing technologies. The license engine provided by this 10Duke Entitlements does not use a separate activation step by default. The activation of a license is an implicit action as part of some licensing models available (e.g. checking out licenses for use without a network connection).

License Formats

Format Explanation
JSON JSON object response with relevant fields including license check result, expiration date, etc. No license enforcing mechanisms are applicable in client applications that use this format.
JSONP Similar format to JSON but includes a JavaScript method call wrapper to allow cross domain calls from browser applications. No license enforcing mechanisms are applicable in client applications that use this format.
JWT JSON Web Token. Encoded and digitally signed format with same fields as JSON format. This format allows strong license enforcing in client applications.
Text false plain text format response to license check. No license enforcing mechanisms are applicable in client applications that use this format.
XML XML response with relevant fields including license check result, expiration date, etc. No license enforcing mechanisms are applicable in client applications that use this format.

License hardening

The 10Duke Entitlements provides a service for the client application to check which system participant's certificates are trusted. This feature can be used, for example, for license hardening making it difficult to a inject a fake 10Duke Entitlements in between the client and the real Authorization service.

Checking license results in the client application is based on JSON Web Token (JWT), which allows using encoding and encryption of license information. You can learn more about JWT at: http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-12.

The authorization is capable of responding with a result in JWT format, which allows for the easy implementation of secure client side license handling.

APIs

The 10Duke Entitlements employs two main endpoints to serve client requests. These are:

  • /authz/ - endpoint for requesting authorization decisions
  • /graph/ - endpoint for requesting data access and other business logical operations than authorization decisions

/authz/

The /authz/ service is used for all authorization cases. In order to receive authorization decisions, the client does not need to know whether decisions will be based on Role-based Authorization or Licensing. Authorization decisions are always returned in a uniform manner independent of the authorization engine, and all supported response formats are applicable to all authorization requests. However, depending on the engine actually used for responding to an authorization request, additional metadata contained by the response may vary. For instance, the Licensing Engine may include license expiration date in the response, but the Role-based Authorization Engine cannot do this because there is no concept of expiration in role-based authorization.

The syntax for calling /authz/ by URL pattern is:

https://ent.10duke.com/authz/[.jwt|.json|.jsonp|.txt|.xml]?[<name_1>[=<actions_1>]][&<name_2>[=<actions_2>]]...[&<name_N>[=<actions_N>]]

where

  • <> denotes a variable
  • [] denotes optional parts of the URL
  • name_x denotes a permission or licensed item name to check
  • actions_xdenotes a permission action list

Response types

Plain text

Plain text responses contain a "&" separated list of true of false values mapping to the list of permission name parameters provided in the original request.

JWT

The JSON Web Token response payload contains 3 parts, which are separated by a "." character. Each part is Base64 encoded. JWT supports signed and secure authorization tokens to be stored and handled in client applications.

The first part is a header, which e.g. contains signature and cryptography method algorithm used, e.g.: {"alg":"RS256"}

The second part contains the token payload, e.g.:

{
    "exp":1410266620,
    "AppFeature-XYZ":true,
    "iss":"52e24d8a-dfe6-4b6a-80ad-cddf798c0210",
    "jti":"269c9f73-229c-4895-bfc2-1827d20bc8d5",
    "iat":1410180220,
    "ibe":1411478986,
    "rfr":1410180820
}

The third part contains signature produced of header and payload

JSON

The JSON response is a license grant entity serialized as a JSON object.

{
    "exp": 1410266853,
    "AppFeature-XYZ": true,
    "iss": "52e24d8a-dfe6-4b6a-80ad-cddf798c0210",
    "jti": "269c9f73-229c-4895-bfc2-1827d20bc8d5",
    "iat": 1410180453,
    "ibe": 1411478986,
    "rfr": 1410181053
}

Examples

Example permission check with plain text response

Example, where the scenario to check if a permission to read Profile entities and delete Person entities is granted to the caller:

Request example
GET or POST

https://ent.10duke.com/authz/.txt?Profile=read&Person=delete
Response example
Headers:

Content-Type:text/plain; charset=utf-8

Response body:

true&false

The same example, with Json web token response:

Request example
GET or POST

https://ent.10duke.com/authz/.jwt?Profile=read
Response example
Headers:

Content-Type:application/jwt; charset=utf-8

Response body:

eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTAxNzgxNzEsImlzcyI6IjUyZTI0ZDhhLWRmZTYtNGI2YS04MGFkLWNkZGY3OThjMDIxMCIsIlByb2ZpbGVfZXJyb3JDb2RlIjoibm90QXV0aG9yaXplZCIsIlByb2ZpbGVfZXJyb3JLZXkiOiJub3RBdXRob3JpemVkIiwiUHJvZmlsZV9lcnJvclRlY2huaWNhbCI6IkF1dGhvcml6YXRpb24gZmFpbGVkIGZvciBcIlByb2ZpbGVcIiIsImlhdCI6MTQxMDE3ODExMSwiUHJvZmlsZV9lcnJvck1lc3NhZ2UiOiJBY2Nlc3MgdG8gXCJQcm9maWxlXCIgZGVuaWVkIn0.Uf3lsDnRDxekn0_CqHQp6rSqDRzCCeh05sWPcENebcIon6kx7ZacW8nTbsf1LS5egS4kI84WuMN5uTXUSHhal1f2qh5bxpgQggh1YQAOq07uOY1PlEpRlh6IF2IdsXNfUuFuKYVmLkTqMnKKat_CSqvvvRuTdA53N8eNzukWato