REST provisioning

The Memority’s REST connector can be used to provision any application that provides REST APIs. However, some prerequisites must be respected to be able to provision the application.

This page explains how the provisioning works in Memority and prerequisites to be able to provision an application.

The technical documentation of the REST connector is in page REST Connector

Definitions

What is a provisioning ?

Provisioning is used to automatically create, update and deactivate/delete accounts in target application and ensure that data are consistent between Memority (the authoritative source) and the application (the target).

It means that once Memority provisions your application, you shouldn't perform any creation, modification or deactivation/deletion of accounts directly in the application, it will be done automatically for you.

What is a REST API ?

REST (Representational State Transfer) APIs (Application Programmatic Interface) are web services based on HTTP conventions:

• Resources to access through URLs (e.g. https://myapplication/api/users/AA0000)

• Manage one resource at a time

• HTTP verb to declare the action performed (e.g. POST, GET, PUT or DELETE)

• Stateless APIs to be able to requests them in any context

REST standard ensure a clear and interoperable way to manage objects through API. 

What is a REST provisioning ?

A REST provisioning is a provisioning from Memority to a target application using application’s REST API.

To be able to provision the application, you first need to known how it works technically and what you want to do functionally (create user’s accounts or organization, what attributes do you need to manage in the application, do you need to handle roles or licenses in the application…).

To sum up, you need much more than the technical documentation of the application, you also need a project process and a functional analysis of your needs.

Memority REST connector

The Memority REST connector is used to create, update and at the end deactivate/delete objects in a target application (user accounts, groups or organizations) thanks to application’s APIs.

The REST connector, like any of others Memority connectors, computes delta between Memority data and target data at each event occurring on the Memority object to determine the action to perform:

• Create an new object

• Link an existing object

• Update an existing object

• Delete / Deactivate an existing object

To perform these actions, the Memority REST connector works thanks to 5 methods that must be defined in the configuration : SEARCH, GET, CREATE, UPDATE and DELETE. Each of these method can contains several API requests.

When an event is detected on an object, and that event impacts the provisioning because it has been defined in mapped attributes, then the following process will be triggered:

• If an application’s object is already linked to the Memority’s object, then the connector use GET method to check if there is delta between Memority and application object

• If a Memority’s object to provision is not linked to an existing application' object, then the connector use SEARCH method to check if there is already an existing application object matching SEARCH method

• Whenever an action method is called (CREATE, PATCH or DELETE), a GET action is performed after that to validate the provisioning worked well. It means there 3 requests for each action performed by the connector.

• When the identity authorization is removed, the connector will use the DELETE method to deactivate or delete the account in the application.

APIs authentication prerequisites

To be able to requests applications APIs, Memority’s connector need to authenticate against the application. The connector supports the authentication for each method and their requests if the authentication in included in the followed list:

• Basic Auth https://datatracker.ietf.org/doc/html/rfc7617

• JWT Token https://datatracker.ietf.org/doc/html/rfc7519

• OAuth2 https://datatracker.ietf.org/doc/html/rfc6749

  • Client Credentials : The Client Credentials grant is used when applications request an access token to access their own resources, not on behalf of a user

  • ROPC : The Resource Owner Password Credentials (ROPC) grant flow lets the client use the resource owner's user name and password to get an access token

Any modification from standards won't be supported (specific headers or api_key query param for example).

The application must provide a provisioning account with credentials according to the authentication method. This account must also have mandatory rights according to APIs calls and data managed through the connector.

APIs prerequisites

To be able to configure the REST connector, the 5 methods must be implemented.

SEARCH

The search method is used to look up for an existing object in the target application thanks to one or several search parameters that needs to be known from Memority (for example, the REST connector cannot look up for an existing object thanks to the application’s object identifier that is not known from Memority at this step).

APIs used to search for an object must return none, one or a list of results according to the search (if there is several results, an error will be triggered). Each entries found must be returned with the account identifier that will be used to perform the GET method after that.

APIs used in SEARCH method can be the same than in GET method.

GET

This call is used to retrieve all informations from the target application and checks the data conformity between the identity provider and the application thanks to the object identifier (that should be available in SEARCH method). To be able to do that, it means that APIs should return all attributes managed by Memority’s connector.

Bear in mind that the REST connector enables to perform several requests in a method, for example one API request to get the user account and a second one to get the role assignments.

APIs used in SEARCH method can be the same than in GET method.

CREATE

The create method is used to create a new object into application thanks to one or several APIs calls. In this case, note that requests are sent sequentially and it cannot be possible to set delays between these requests, so APIs should only respond once their process is fully done on target’s application side.

No particular return is waited from this API.

UPDATE

The update method is used to update an object into application thanks to one or several APIs calls using the object identifier (that should be available in SEARCH method). In this case, note that requests are sent sequentially and it cannot be possible to set delays between these requests, so APIs should only respond once their process is fully done on target’s application side.

No particular return is waited from this API.

DELETE

The delete method is used to delete or deactivate an object into application thanks to one or several APIs calls using the object identifier (that should be available in SEARCH method). In this case, note that requests are sent sequentially and it cannot be possible to set delays between these requests, so APIs should only respond once their process is fully done on target’s application side.

Note that once the delete method executed, the application’s object won’t be managed anymore by Memority.

No particular return is waited from this API.

Quotas

Memority REST connector can handle application’s APIs quotas thanks to 2 policies:

• Rate limiting policy - The connector will limit the number of calls to the application to not reach quotas (cannot below 60 provisioning actions per minute)

• Quota exceeded policy - The connector will retry actions that failed because of quota exceeded

Due to high performance of Memority and the large amount of objects that can be managed for a tenant, we advise to have at least 200 requests/second available on application side.

Error management

Memority REST connector is able to detect and retry automatically network issues that prevent access to the application.

For other errors, the application’s APIs must return clear error response based on HTTP code. The response should contains a clear message explaining the error we can raise into Memority audits for helpdesk teams.