10Duke Entitlements Authorization API

Table of Contents

Introduction

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

  • /authz/ - an endpoint for requesting authorization decisions
  • /graph/ - an endpoint for requesting data access and business logical operations other than authorization decisions. Please see the 10Duke Entitlements Graph API reference.

This API reference is concerned with the /authz endpoint.

/authz/

The '/authz/' service is used for all authorization cases. In order to receive authorization decisions, the client application 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
  • _x denotes 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

Request example

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

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

Request example

The same example, with Json web token response:

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

General parameters

Predefined parameters for API calls (other parameter names denote licensed items or permission names):

Parameters name Valid values / description
consumptionMode cache or checkOut

This parameter is optional, defaults to cache
consumeDuration license consumption (check-out / reservation) duration in milliseconds.

This parameter is optional.

The underlying implementation may choose to grant different duration depending on model.
doConsume Parameter for consume / don't consume licenses when checking.

This parameter is optional, default to false and is not needed when using default consume mode or definind consumptionMode explicitly
release true or false to release consumed license

Use of this parameter also requires use of parameter AssignmentConsumptionId
AssignmentConsumptionId Identifier of the license assignment to release

License and permission checks

Hardware / device locked licenses

NOTE:

  • Ties check / consume to user and hardware
  • Is applicable if using concurrent consumption constraint
GET /authz/?LICENSED_ITEM_NAME&hw=HARDWARE_ID

Please note the hw=HW_ID parameter in addition to the licensed item name. Variants with different response types:

JSON

GET /authz/.json?LICENSED_ITEM_NAME&hw=HARDWARE_ID

JWT

GET /authz/.jwt?LICENSED_ITEM_NAME&hw=HARDWARE_ID

General license checks, not locked to specific device(s)

NOTE:

  • Ties check / consume to user only
  • Is not applicable if using concurrent consumption constraint
GET /authz/?LICENSED_ITEM_NAME&hw=hw-id-here

Please note the hw=hw-id-here parameter in addition to the licensed item name. Variants with different response types:

JSON

GET /authz/.json?LICENSED_ITEM_NAME&hw=hw-id-here

JWT

GET /authz/.jwt?LICENSED_ITEM_NAME&hw=hw-id-here

License Checks with client defined duration

NOTE:

  • Ties check / consume to user only
GET /authz/?LICENSED_ITEM_NAME&hw=hw-id-here&consumeDuration=3600000

Please note the consumeDuration=... parameter in addition to the licensed item name. Variants with different response types follow the same pattern as explained earlier

Checks with specified entitlement ID

License checks can be restricted to scope of an entitlement. Id of the entitlement can be specified in the path part of the /authz/ URL:

GET /authz/entitlements/ENTITLEMENT_ID?LICENSED_ITEM_NAME

Here, ENTITLEMENT_ID is the UUID that uniquely identifies the entitlement targeted by the license check.

Permission checks

GET /authz/?PERMISSION_NAME=PERMISSION_ACTION

Predefined permission actions:

  • create
  • read
  • update
  • delete
  • query
  • impersonate