REST API

Overview

The REST API enables connectivity with custom-built applications, public cloud services not natively supported by Entitle, and ETL processes for applications lacking REST API support—for example, those managing permissions through database queries.

The REST API can connect to non-public IP addresses for internal customer applications and services. For example, a Kubernetes (K8s) agent installed on a private cloud can connect to these applications.

Click here to view an example of how an implemented HTTP server for REST API integration should look.

This page will provide you with instructions on how to integrate Entitle and REST API.

General guidelines

• To integrate REST API with Entitle, you are required to implement an HTTP server that supports one of two integration modes: Standing Accounts or Ephemeral Accounts:
  • Standing Accounts means only existing users will be given access.
  • Ephemeral Accounts means temporary users are created and given access. After that, the users are deleted.
  • Within the two integration modes, you will be able to choose whether you wish to implement get all permissions (get_all_permissions) or get asset permissions (get_asset_permissions).

Set up REST API to work with Entitle

Note: In each of the two integration modes, there are mandatory fields that need to be implemented as well as optional ones.

Standing Accounts:

1. Mandatory fields to implement:
   1. get_all_permissions or get_asset_permissions
   2. get_assets
   3. get_actors
   4. give_access
   5. revoke_access
2. Optional fields:
   1. check_config
   2. create_actor
   3. delete_actor

Ephemeral Accounts:

1. Mandatory fields to implement:
   1. get_all_permissions or get_asset_permissions
   2. get_assets
   3. create_actor
   4. delete_actor
2. Optional fields:
   1. check_config

Definitions of entities

Below you will find an explanation for each entity that exists as a field (mandatory and optional ones).

Actor

An actor represents an entity that interacts with assets within a system. This actor could be a user, a service account, or any entity that requires access to resources or performs actions within the system.

Asset

An asset represents a resource or entity within a system that actors interact with or access.

Permission

Permission represents the relationship between a role and an actor or asset, requiring an external mapping to an asset. There are two types of permissions:

1. Actor permissions

   An Actor (e.g. user) is granted permission to an asset.

   Field	Field Type	Description
   actor_id	string	The unique identifier of the actor who has said permission
   role_code	string	The role code of the permission the actor has

2. Asset permissions

   An Asset (e.g. group) grants permission to an asset.

   Field	Field Type	Description
   asset_id	string	The unique identifier of the actor who has said permission
   role_code	string	The role code of the permission the actor has

Endpoints specification

Entitle's agent expects all responses to be in JSON format with the following structure:

Note: Entitle's agent expects a status code 200 for success. All other status codes will indicate a failure.

[GET] Get Actors

Request body: empty

Response: {'data': {'actors': <as below>}}

[GET] Get Assets

Request body: empty

Response:{'data': {'assets': <as below>}}

[GET] Get All Permissions

Request body: empty

Response: {'data': {'actor_permissions': <as below>, 'asset_permissions': <as below>}}

[GET] Get Asset Permissions

Path parameters: The URL we call will look like this - <get_asset_permissions_path>/{asset_identifier}

Request body: empty

Response: {'data': {'actor_permissions': <as below>, 'asset_permissions': <as below>}}

[POST] Give Access

The request body is in JSON format with the following fields:

Response: {'data': {}}

[POST] Revoke Access

the request body is in JSON format with the following fields:

Response: {'data': {}}

[POST] Check Config (optional)

the request body is in JSON format with the following fields:

Response: {'data': {'valid': <true/false>, 'reason': '<if the config is invalid, why?>'}}

Endpoints SWAGGER - visual presentation

Open API definition

For a more convenient view of this specification and to automatically generate code stubs in different languages, visit the Swagger Editor and input the following definition.

Example server for REST API integration

Click here to view an example of how an implemented HTTP server for REST API integration should look.

Creating the integration in Entitle

All that is left to do is create an integration on the Entitle application.

1. Log into Entitle and navigate to the Integrations page.

2. After clicking the Add Integration button, type REST API in the Application field.

3. Don’t forget to set the Save on field with your configuration, i.e. your own hosted agent or Entitle’s cloud.

4. Select one of the four available options in the Connection field within the two integration modes (Standing Accounts or Ephemeral Accounts). Note that the according configuration JSON presents only the mandatory fields:

   

5. Choose whether you wish to specify full or relative paths:
   • Full path: To specify full paths, do not add schema and host to the configuration.
   • Relative path: To specify relative paths, add schema (”http”/”https”) and host (e.g. “yourhost.com”) to the final configuration.

"schema": "http", // http or https (optional)
"host": "yourhost.com", // the hostname which hosts your permissions server (optional)

6. Choose one of two options for authentication and authorization:
   • Option 1: OAuth
     • Client credentials flow according to the Client Credentials flow.
     • Under the oauth_data field, insert the relevant information.
       See the example below:

{
	"schema": "http", // http or https (optional)
	"host": "yourhost.com", // the hostname which hosts your permissions server (optional)
	"get_actors_path": "/my_actors", // get actors will call GET 'yourhost.com/my_actors'
	"get_assets_path": "/my_assets", // get assets will call GET 'yourhost.com/my_assets'
	"get_all_permissions_path": "/perm", // get all permissions will call GET 'yourhost.com/perm'
	"give_access_path": "/give", // give access will call POST 'yourhost.com/give"
	"revoke_access_path": "/revoke", // revoke access will call POST 'yourhost.com/revoke"
  "oauth_data": {
      "auth_server": "<http://myauth.company.com>",
      "client_id": "\\<CLIENT_ID>",
      "client_secret": "\\<CLIENT_SECRET>",
      "audience": "" //(optional)
  }
}

• Option 2: Token-based
  • Insert the Token in the according position under the headers field.
    See the example below:

{
	"get_actors_path": "http://yourhost.com/my_actors", // get actors will call GET 'yourhost.com/my_actors'
	"get_assets_path": "http://yourhost.com/my_assets", // get assets will call GET 'yourhost.com/my_assets'
	"get_asset_permissions_path": "http://yourhost.com/perm", // get asset permissions will call GET 'yourhost.com/perm/{asset_identifier}'
	"give_access_path": "http://yourhost.com/give", // give access will call POST 'yourhost.com/give"
	"revoke_access_path": "http://yourhost.com/revoke", // revoke access will call POST 'yourhost.com/revoke"
  "headers": {
      "Authorization": "Bearer <TOKEN>",
  }
}